5824: Update/clarify docs and comments.

diff --git a/apps/workbench/app/controllers/collections_controller.rb b/apps/workbench/app/controllers/collections_controller.rb
index 847e5eedab728185f8b438d4ddb8f57f1e6819ba..0806a0a4297e57c9c546a3a5d724c56a19e6c32f 100644 (file)
--- a/apps/workbench/app/controllers/collections_controller.rb
+++ b/apps/workbench/app/controllers/collections_controller.rb
@@ -137,6 +137,8 @@ class CollectionsController < ApplicationController
       return
     end
 
+    # If we are configured to use a keep-web server, just redirect to
+    # the appropriate URL.
     if Rails.configuration.keep_web_url or
         Rails.configuration.keep_web_download_url
       opts = {}
@@ -153,6 +155,9 @@ class CollectionsController < ApplicationController
       return redirect_to keep_web_url(params[:uuid], params[:file], opts)
     end
 
+    # No keep-web server available. Get the file data with arv-get,
+    # and serve it through Rails.
+
     file_name = params[:file].andand.sub(/^(\.\/|\/|)/, './')
     if file_name.nil? or not coll.manifest.has_file?(file_name)
       return render_not_found
@@ -336,10 +341,10 @@ class CollectionsController < ApplicationController
       # (and when there is no preview link configured)
       tmpl = Rails.configuration.keep_web_download_url
     else
-      test_uri = URI.parse(tmpl % fmt)
+      check_uri = URI.parse(tmpl % fmt)
       if opts[:query_token] and
-          not test_uri.host.start_with?(munged_id + "--") and
-          not test_uri.host.start_with?(munged_id + ".")
+          not check_uri.host.start_with?(munged_id + "--") and
+          not check_uri.host.start_with?(munged_id + ".")
         # We're about to pass a token in the query string, but
         # keep-web can't accept that safely at a single-origin URL
         # template (unless it's -attachment-only-host).
@@ -348,7 +353,7 @@ class CollectionsController < ApplicationController
           raise ArgumentError, "Download precluded by site configuration"
         end
         logger.warn("Using download link, even though inline content " \
-                    "was requested: #{test_uri.to_s}")
+                    "was requested: #{check_uri.to_s}")
       end
     end
 

diff --git a/apps/workbench/config/application.default.yml b/apps/workbench/config/application.default.yml
index dd499772e47d95bb8a9abc8af9addd8ccecdb1be..c4a92d273950bbebe15b0faf29ccbe58b3cde3b4 100644 (file)
--- a/apps/workbench/config/application.default.yml
+++ b/apps/workbench/config/application.default.yml
@@ -228,7 +228,7 @@ common:
 
   # Format of preview links. If false, use keep_web_download_url
   # instead, and disable inline preview. If both are false, use
-  # Workbench's built-in download mechanism.
+  # Workbench's built-in file download/preview mechanism.
   #
   # Examples:
   # keep_web_url: https://%{uuid_or_pdh}.collections.uuid_prefix.arvadosapi.com
@@ -242,8 +242,10 @@ common:
   # Format of download links. If false, use keep_web_url with
   # disposition=attachment query param.
   #
-  # The host here should match the -attachment-only-host argument
-  # given to keep-web.
+  # The host part of the keep_web_download_url value here must match
+  # the -attachment-only-host argument given to keep-web: if
+  # keep_web_download_url is "https://FOO.EXAMPLE/c=..." then keep-web
+  # must run with "-attachment-only-host=FOO.EXAMPLE".
   #
   # If keep_web_download_url is false, and keep_web_url uses a
   # single-origin form, then Workbench will show an error page

diff --git a/doc/install/install-keep-web.html.textile.liquid b/doc/install/install-keep-web.html.textile.liquid
index dedce5e17e717232004b3e008de3657bdb59ba46..5eb4191e8cab6133944904a6a43c4028b19e39ee 100644 (file)
--- a/doc/install/install-keep-web.html.textile.liquid
+++ b/doc/install/install-keep-web.html.textile.liquid
@@ -78,7 +78,7 @@ The keep-web service will be accessible from anywhere on the internet, so we rec
 
 This is best achieved by putting a reverse proxy with SSL support in front of keep-web, running on port 443 and passing requests to keep-web on port 9002 (or whatever port you chose in your run script).
 
-Note: A wildcard SSL certificate is required in order to proxy keep-web effectively.
+Note: A wildcard SSL certificate is required in order to support a full-featured secure keep-web service. Without it, keep-web can offer file downloads for all Keep data; however, in order to avoid cross-site scripting vulnerabilities, keep-web refuses to serve private data as web content except when it is accessed using a "secret link" share. With a wildcard SSL certificate and DNS configured appropriately, all data can be served as web content.
 
 For example, using Nginx:
 
@@ -121,14 +121,16 @@ If neither of the above wildcard options is feasible, only unauthenticated reque
 
 h3. Tell Workbench about the keep-web service
 
-Add the following entry to your Workbench configuration file (@/etc/arvados/workbench/application.yml@):
+Workbench has features like "download file from collection" and "show image" which work better if the content is served by keep-web rather than Workbench itself. We recommend using the two different hostnames ("download" and "collections" above) for file downloads and inline content respectively.
+
+Add the following entry to your Workbench configuration file (@/etc/arvados/workbench/application.yml@). This URL will be used for file downloads.
 
 <notextile>
 <pre><code>keep_web_download_url: https://download.<span class="userinput">uuid_prefix</span>.your.domain/c=%{uuid_or_pdh}
 </code></pre>
 </notextile>
 
-Additionally, add *one* of the following entries to your Workbench configuration file, depending on your DNS setup:
+Additionally, add *one* of the following entries to your Workbench configuration file, depending on your DNS setup. This URL will be used to serve user content that can be displayed in the browser, like image previews and static HTML pages.
 
 <notextile>
 <pre><code>keep_web_url: https://%{uuid_or_pdh}--collections.<span class="userinput">uuid_prefix</span>.your.domain