From: Peter Amstutz Date: Tue, 10 Dec 2019 21:14:00 +0000 (-0500) Subject: Merge branch 'master' into 15572-new-install-docs X-Git-Tag: 2.0.0~72^2~22 X-Git-Url: https://git.arvados.org/arvados.git/commitdiff_plain/db31bedb109a4d918830a910654685a9f591cf28?hp=75b025460ce334b77e116d3455add89f6a4642d4 Merge branch 'master' into 15572-new-install-docs Arvados-DCO-1.1-Signed-off-by: Peter Amstutz --- diff --git a/doc/_config.yml b/doc/_config.yml index bcb66fdb39..2003594da4 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -191,11 +191,10 @@ navbar: - install/arvados-on-kubernetes.html.textile.liquid - Manual installation: - install/install-manual-prerequisites.html.textile.liquid - - install/install-components.html.textile.liquid + - install/packages.html.textile.liquid + - install/config.html.textile.liquid - Core: - - install/install-postgresql.html.textile.liquid - install/install-api-server.html.textile.liquid - - install/install-controller.html.textile.liquid - Keep: - install/install-keepstore.html.textile.liquid - install/configure-fs-storage.html.textile.liquid @@ -205,14 +204,15 @@ navbar: - install/install-keep-web.html.textile.liquid - install/install-keep-balance.html.textile.liquid - User interface: + - install/setup-login.html.textile.liquid - install/install-sso.html.textile.liquid - install/install-workbench-app.html.textile.liquid - install/install-workbench2-app.html.textile.liquid - install/install-composer.html.textile.liquid - Additional services: - install/install-ws.html.textile.liquid - - install/install-shell-server.html.textile.liquid - install/install-arv-git-httpd.html.textile.liquid + - install/install-shell-server.html.textile.liquid - Containers API support on SLURM: - install/crunch2-slurm/install-prerequisites.html.textile.liquid - install/crunch2-slurm/install-slurm.html.textile.liquid @@ -223,3 +223,8 @@ navbar: - install/install-compute-ping.html.textile.liquid - Containers API support on cloud (beta): - install/install-dispatch-cloud.html.textile.liquid + - External dependencies: + - install/install-postgresql.html.textile.liquid + - install/ruby.html.textile.liquid + - install/nginx.html.textile.liquid + - install/google-auth.html.textile.liquid diff --git a/doc/_includes/_assign_volume_uuid.liquid b/doc/_includes/_assign_volume_uuid.liquid index cdd0f1a6db..97bc67c293 100644 --- a/doc/_includes/_assign_volume_uuid.liquid +++ b/doc/_includes/_assign_volume_uuid.liquid @@ -4,4 +4,6 @@ Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} -Note that each volume has a UUID, like @zzzzz-nyw5e-0123456789abcde@. You assign these manually: replace @zzzzz@ with your cluster ID, and replace @0123456789abcde@ with an arbitrary string of 15 alphanumerics. Once assigned, UUIDs should not be changed. +Note that each volume has a UUID, like @zzzzz-nyw5e-0123456789abcde@. You assign these manually: replace @zzzzz@ with your Cluster ID, and replace @0123456789abcde@ with an arbitrary unique string of 15 alphanumerics. Once assigned, UUIDs should not be changed. + +Essential configuration values are highlighted in red. Remaining parameters are provided for documentation, with their default values. \ No newline at end of file diff --git a/doc/_includes/_install_debian_key.liquid b/doc/_includes/_install_debian_key.liquid index 75942c7bcb..e74bba21de 100644 --- a/doc/_includes/_install_debian_key.liquid +++ b/doc/_includes/_install_debian_key.liquid @@ -4,7 +4,10 @@ Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} + + -
~$ sudo /usr/bin/apt-key adv --keyserver pool.sks-keyservers.net --recv 1078ECD7
+
# apt-get --no-install-recommends install gnupg
+# /usr/bin/apt-key adv --keyserver pool.sks-keyservers.net --recv 1078ECD7
 

 
diff --git a/doc/_includes/_install_postgres_database.liquid b/doc/_includes/_install_postgres_database.liquid
index f4b95ac0be..e93457f188 100644
--- a/doc/_includes/_install_postgres_database.liquid
+++ b/doc/_includes/_install_postgres_database.liquid
@@ -4,29 +4,29 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-
    
+
      
 
    1. Start a shell for the postgres user:
-
      ~$ sudo -u postgres bash
      
+
      # su postgres
      
 
      2. 
 
    2. Generate a new database password:
-
      $ ruby -e 'puts rand(2**128).to_s(36)'
+
      postgres$ tr -dc 0-9a-zA-Z </dev/urandom | head -c25; echo
 yourgeneratedpassword
 
       Record this.  You'll need it when you set up the Rails server later.
 
      3. 
 
    3. Create a database user with the password you generated:
-  
      $ createuser --encrypted -R -S --pwprompt {{service_role}}
+  
      postgres$ createuser --encrypted --no-createrole --no-superuser --pwprompt {{service_role}}
   Enter password for new role: yourgeneratedpassword
   Enter it again: yourgeneratedpassword
      
 
      4. 
 
    4. Create a database owned by the new user:
-  
      $ createdb {{service_database}} -T template0 -E UTF8 -O {{service_role}}
      
+  
      postgres$ createdb {{service_database}} -T template0 -E UTF8 -O {{service_role}}
      
 
      5. 
 {% if use_contrib %}
 
    5. Enable the pg_trgm extension
-  
      $ psql {{service_database}} -c "CREATE EXTENSION IF NOT EXISTS pg_trgm"
      
+  
      postgres$ psql {{service_database}} -c "CREATE EXTENSION IF NOT EXISTS pg_trgm"
      
 
      6. 
 {% endif %}
 
    6. Exit the postgres user shell:
-  
      $ exit
      
+  
      postgres$ exit
      
 
      7. 
 
    
diff --git a/doc/_includes/_install_rails_command.liquid b/doc/_includes/_install_rails_command.liquid
index 027f64bebb..10c17a0c2d 100644
--- a/doc/_includes/_install_rails_command.liquid
+++ b/doc/_includes/_install_rails_command.liquid
@@ -28,17 +28,6 @@ This template recognizes four variables:
   {% assign railscmd = "bundle exec rails console" %}
 {% endunless %}
 
-Using RVM:
-
-
-
    {{railshost}}~$ cd {{railsdir}}
-{{railshost}}{{railsdir}}$ sudo -u webserver-user RAILS_ENV=production `which rvm-exec` default {{railscmd}}
-{% if railsout %}{{railsout}}
-{% endif %}
    
-    
-
-Not using RVM:
-
 
 
    {{railshost}}~$ cd {{railsdir}}
 {{railshost}}{{railsdir}}$ sudo -u webserver-user RAILS_ENV=production {{railscmd}}
diff --git a/doc/_includes/_install_redhat_key.liquid b/doc/_includes/_install_redhat_key.liquid
index 69cfd5a013..1a621dcb3a 100644
--- a/doc/_includes/_install_redhat_key.liquid
+++ b/doc/_includes/_install_redhat_key.liquid
@@ -7,8 +7,7 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 The Curoverse signing key fingerprint is
 
 
-
    
-pub  2048R/1078ECD7 2010-11-15 Curoverse, Inc Automatic Signing Key 
+
    pub  2048R/1078ECD7 2010-11-15 Curoverse, Inc Automatic Signing Key 
       Key fingerprint = B2DA 2991 656E B4A5 0314  CA2B 5716 5911 1078 ECD7
 sub  2048R/5A8C5A93 2010-11-15
 
    
diff --git a/doc/_includes/_install_ruby_and_bundler.liquid b/doc/_includes/_install_ruby_and_bundler.liquid
index a8323f592d..7871f2dc60 100644
--- a/doc/_includes/_install_ruby_and_bundler.liquid
+++ b/doc/_includes/_install_ruby_and_bundler.liquid
@@ -6,26 +6,64 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 
 Ruby 2.5 is recommended; Ruby 2.3 is also known to work.
 
-h4(#rvm). *Option 1: Install with RVM*
+* "Option 1: Install from packages":#packages
+* "Option 2: Install with RVM":#rvm
+* "Option 3: Install from source":#fromsource
+
+h2(#packages). Option 1: Install from packages
+
+h3. Centos 7
+
+The Ruby version shipped with Centos 7 is too old.  Use "RVM.":#rvm
+
+h3. Debian and Ubuntu
+
+
+
    # apt-get --no-install-recommends install ruby-dev bundler
    
+    
+
+h2(#rvm). Option 2: Install with RVM
+
+h3. Install gpg and curl
+
+h4. Centos 7
+
+
    +yum install gpg curl which
+
    
+
+h4. Debian and Ubuntu
+
+
    +apt-get --no-install-recommends install gpg curl
+
    
+
+h3. Install RVM
+
+
+
    # gpg --keyserver pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+\curl -sSL https://get.rvm.io | bash -s stable --ruby=2.5
+
    
+
+To use Ruby installed from RVM, load it in an open shell like this:
 
 
-
    sudo gpg --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
-\curl -sSL https://get.rvm.io | sudo bash -s stable --ruby=2.5
+
    . /usr/local/rvm/scripts/rvm
 
    
 
-Either log out and log back in to activate RVM, or explicitly load it in all open shells like this:
+Alternately you can use @rvm-exec@ (the first parameter is the ruby version to use, or "default"), for example:
 
 
-
    source /usr/local/rvm/scripts/rvm
+
    rvm-exec default rails console
 
    
 
-Once RVM is activated in your shell, install Bundler:
+Finally, install Bundler:
 
 
 
    ~$ gem install bundler
 
    
 
-h4(#fromsource). *Option 2: Install from source*
+h2(#fromsource). Option 3: Install from source
 
 Install prerequisites for Debian 8:
 
diff --git a/doc/images/proxy-chain.svg b/doc/images/proxy-chain.svg
new file mode 100644
index 0000000000..4fe4a5f777
--- /dev/null
+++ b/doc/images/proxy-chain.svg
@@ -0,0 +1,179 @@
+
+
+
+ 
+  
+   
+  
+  
+   
+  
+ 
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+ 
+  
+ 
+ 
+  
+   
+  
+  
+   
+  
+  
+   
+  
+  
+   
+  
+  
+   
+  
+  
+   
+  
+  
+   
+  
+  
+   
+  
+  
+   
+  
+  
+   
+  
+ 
+ 
+ 
+  
+   
+   
+  
+ 
+ 
+  
+   
+    
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        Client
+       
+      
+      
+       
+        
+        
+        
+        Nginx
+       
+      
+      
+       
+        
+        
+        
+        Arvadoscontroller
+       
+      
+      
+       
+        
+        
+        
+        Arvados API server
+       
+      
+      
+       
+        
+        
+        
+        PostgreSQL
+       
+      
+      
+       
+        
+        
+        
+       
+      
+      
+       
+        
+        
+        
+       
+      
+      
+       
+        
+        
+        
+       
+      
+      
+       
+        
+        
+        
+       
+      
+      
+       
+        
+        
+        
+       
+      
+     
+    
+   
+  
+ 
+
\ No newline at end of file
diff --git a/doc/install/config.html.textile.liquid b/doc/install/config.html.textile.liquid
new file mode 100644
index 0000000000..4527470ac2
--- /dev/null
+++ b/doc/install/config.html.textile.liquid
@@ -0,0 +1,52 @@
+---
+layout: default
+navsection: installguide
+title: Configuration files
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+h2. Arados /etc/arvados/config.yml
+
+The configuration file is normally found at @/etc/arvados/config.yml@ and will be referred to as just @config.yml@ in this guide.  This configuration file should be kept in sync across every node in the cluster, except compute nodes (which usually do not require config.yml).  We recommend using a devops configuration management tool such as "Puppet":https://puppet.com/open-source/ to synchronize the config file.
+
+h3. Syntax
+
+The configuration file is in "YAML":https://yaml.org/ format.  This is a block syntax where indentation is significant (similar to Python).  By convention we use two space indent.  The first line of the file is always "Clusters:", underneath it at the first indent level is the Cluster ID.  All the actual cluster configuration come under the Cluster ID.  This means all configuration parameters are indented by at least two levels (four spaces).  Comments start with @#@ .
+
+We recommend a YAML-syntax plugin for your favorite text editor, such as @yaml-mode@ (Emacs) or @yaml-vim@.
+
+Example file:
+
+
    +Clusters:                         # Clusters block, everything else is listed under this
+  abcde:                          # Cluster ID, everything under it is configuration for this cluster
+    ExampleConfigKey: "fghijk"    # An example configuration key
+    ExampleConfigGroup:           # A group of keys
+      ExampleDurationConfig: 12s  # Example duration
+      ExampleSizeConfig: 99KiB    # Example with a size suffix
+
    
+
+Each configuration group may only appear once.  When a configuration key is within a config group, it will be written with the group name leading, for example @ExampleConfigGroup.ExampleSizeConfig@.
+
+Duration suffixes are s=seconds, m=minutes or h=hours.
+
+Size suffixes are K=10 ^3^, Ki=2 ^10^ , M=10 ^6^, Mi=2 ^20^, G=10 ^9^, Gi=2 ^30^, T=10 ^12^, Ti=2 ^40^, P=10 ^15^, Pi=2 ^50^, E=10 ^18^, Ei=2 ^60^.  You can optionally follow with a "B" (eg "MB" or "MiB") for readability (it does not affect the units.)
+
+h3(#empty). Create empty configuration file
+
+
+
    # export ClusterID=xxxxx
+# mkdir -p /etc/arvados
+# cat > /etc/arvados/config.yml <<EOF
+Clusters:
+  ${ClusterID}:
+EOF
    
+    
+
+h2. Nginx configuration
+
+This guide will also cover setting up "Nginx":https://www.nginx.com/ as a reverse proxy for Arvados services.  Nginx performs two main functions: TLS termination and virtual host routing.  The virtual host configuration for each component will go in its own file in @/etc/nginx/conf.d/@.
diff --git a/doc/install/configure-azure-blob-storage.html.textile.liquid b/doc/install/configure-azure-blob-storage.html.textile.liquid
index 2f68c8a4bf..4dc75c8bed 100644
--- a/doc/install/configure-azure-blob-storage.html.textile.liquid
+++ b/doc/install/configure-azure-blob-storage.html.textile.liquid
@@ -50,10 +50,8 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
 
 {% include 'assign_volume_uuid' %}
 
-
    Clusters:
-  uuid_prefix:
-    Volumes:
-      uuid_prefix-nyw5e-000000000000000:
+
        Volumes:
+      ClusterID-nyw5e-000000000000000:
         AccessViaHosts:
           # This section determines which keepstore servers access the
           # volume. In this example, keep0 has read/write access, and
@@ -65,21 +63,21 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
           "http://keep0.uuid_prefix.example.com:25107/": {}
           "http://keep1.uuid_prefix.example.com:25107/": {ReadOnly: true}
 
-        Driver: Azure
+        Driver: Azure
         DriverParameters:
           # Storage account name and secret key, used for
           # authentication.
-          StorageAccountName: exampleStorageAccountName
-          StorageAccountKey: zzzzzzzzzzzzzzzzzzzzzzzzzz
+          StorageAccountName: exampleStorageAccountName
+          StorageAccountKey: zzzzzzzzzzzzzzzzzzzzzzzzzz
+
+          # Storage container name.
+          ContainerName: exampleContainerName
 
           # The cloud environment to use,
           # e.g. "core.chinacloudapi.cn". Defaults to
           # "core.windows.net" if blank or omitted.
           StorageBaseURL: ""
 
-          # Storage container name.
-          ContainerName: exampleContainerName
-
           # Time to wait for an upstream response before failing the
           # request.
           RequestTimeout: 10m
diff --git a/doc/install/configure-fs-storage.html.textile.liquid b/doc/install/configure-fs-storage.html.textile.liquid
index be0a48cb8c..608d3e3bf2 100644
--- a/doc/install/configure-fs-storage.html.textile.liquid
+++ b/doc/install/configure-fs-storage.html.textile.liquid
@@ -17,31 +17,17 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
 
 {% include 'assign_volume_uuid' %}
 
-Note that each volume has an AccessViaHosts section indicating that (for example) keep0's /mnt/local-disk directory is volume 0, while keep1's /mnt/local-disk directory is volume 1.
+Note that each volume entry has an @AccessViaHosts@ section indicating which Keepstore instance(s) will serve that volume.  In this example, keep0 and keep1 each have their own data disk.  The @/mnt/local-disk@ directory on keep0 is volume @ClusterID-nyw5e-000000000000000@, and the @/mnt/local-disk@ directory on keep1 is volume @ClusterID-nyw5e-000000000000001@ .
 
 
-
    Clusters:
-  uuid_prefix:
-    Volumes:
-      uuid_prefix-nyw5e-000000000000000:
+
        Volumes:
+      ClusterID-nyw5e-000000000000000:
         AccessViaHosts:
-          "http://keep0.uuid_prefix.example.com:25107": {}
-        Driver: Directory
+          "http://keep0.ClusterID.example.com:25107": {}
+        Driver: Directory
         DriverParameters:
           # The directory that will be used as the backing store.
-          Root: /mnt/local-disk
-
-          # When true, read and write operations (for whole 64MiB
-          # blocks) on an individual volume will queued and issued
-          # serially.  When false, read and write operations will be
-          # issued concurrently.
-          #
-          # May improve throughput if you experience contention when
-          # there are multiple requests to the same volume.
-          #
-          # When using SSDs, RAID, or a shared network filesystem, you
-          # probably don't want this.
-          Serialize: false
+          Root: /mnt/local-disk
 
         # How much replication is performed by the underlying
         # filesystem.  (for example, a network filesystem may provide
@@ -53,25 +39,22 @@ Note that each volume has an AccessViaHosts section indicating that (for example
         # reads.
         ReadOnly: false
 
-        # Storage classes to associate with this volume.  See "Storage
-        # classes" in the "Admin" section of doc.arvados.org.
+        # Storage classes to associate with this volume.
         StorageClasses: null
 
-      uuid_prefix-nyw5e-000000000000001:
+      ClusterID-nyw5e-000000000000001:
         AccessViaHosts:
-          "http://keep1.uuid_prefix.example.com:25107": {}
-        Driver: Directory
+          "http://keep1.ClusterID.example.com:25107": {}
+        Driver: Directory
         DriverParameters:
-          Root: /mnt/local-disk
+          Root: /mnt/local-disk
 
    
 
-In the case of a network-attached filesystem, the AccessViaHosts section can have multiple entries. If the filesystem is accessible by all keepstore servers, the AccessViaHosts section can be empty, or omitted entirely.
+In the case of a network-attached filesystem, the @AccessViaHosts@ section can have multiple entries. If the filesystem is accessible by all keepstore servers, the AccessViaHosts section can be empty, or omitted entirely.  In this example, the underlying storage system performs replication, so specifying @Replication: 2@ means a block is considered to be stored twice for the purposes of data integrity, while only stored on a single volume from the perspective of Keep.
 
 
-
    Clusters:
-  uuid_prefix:
-    Volumes:
-      uuid_prefix-nyw5e-000000000000002:
+
        Volumes:
+      ClusterID-nyw5e-000000000000002:
         AccessViaHosts:
           # This section determines which keepstore servers access the
           # volume. In this example, keep0 has read/write access, and
@@ -80,10 +63,10 @@ In the case of a network-attached filesystem, the AccessViaHosts section can hav
           # If the AccessViaHosts section is empty or omitted, all
           # keepstore servers will have read/write access to the
           # volume.
-          "http://keep0.uuid_prefix.example.com:25107/": {}
-          "http://keep1.uuid_prefix.example.com:25107/": {ReadOnly: true}
-        Driver: Directory
+          "http://keep0.ClusterID.example.com:25107/": {}
+          "http://keep1.ClusterID.example.com:25107/": {ReadOnly: true}
+        Driver: Directory
         DriverParameters:
-          Root: /mnt/network-attached-filesystem
+          Root: /mnt/network-attached-filesystem
         Replication: 2
 
    
diff --git a/doc/install/configure-s3-object-storage.html.textile.liquid b/doc/install/configure-s3-object-storage.html.textile.liquid
index b721dba9e1..aab906b1ad 100644
--- a/doc/install/configure-s3-object-storage.html.textile.liquid
+++ b/doc/install/configure-s3-object-storage.html.textile.liquid
@@ -15,10 +15,8 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
 
 {% include 'assign_volume_uuid' %}
 
-
    Clusters:
-  uuid_prefix:
-    Volumes:
-      uuid_prefix-nyw5e-000000000000000:
+
        Volumes:
+      ClusterID-nyw5e-000000000000000:
         AccessViaHosts:
           # This section determines which keepstore servers access the
           # volume. In this example, keep0 has read/write access, and
@@ -30,37 +28,37 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
           "http://keep0.uuid_prefix.example.com:25107/": {}
           "http://keep1.uuid_prefix.example.com:25107/": {ReadOnly: true}
 
-        Driver: S3
+        Driver: S3
         DriverParameters:
+          # Bucket name.
+          Bucket: example-bucket-name
+
           # IAM role name to use when retrieving credentials from
           # instance metadata. It can be omitted, in which case the
           # role name itself will be retrieved from instance metadata
           # -- but setting it explicitly may protect you from using
           # the wrong credentials in the event of an
           # installation/configuration error.
-          IAMRole: ""
+          IAMRole: ""
 
           # If you are not using an IAM role for authentication,
           # specify access credentials here instead.
-          AccessKey: ""
-          SecretKey: ""
+          AccessKey: ""
+          SecretKey: ""
+
+          # Storage provider region. For Google Cloud Storage, use ""
+          # or omit.
+          Region: us-east-1a
 
           # Storage provider endpoint. For Amazon S3, use "" or
           # omit. For Google Cloud Storage, use
           # "https://storage.googleapis.com".
           Endpoint: ""
 
-          # Storage provider region. For Google Cloud Storage, use ""
-          # or omit.
-          Region: us-east-1a
-
           # Change to true if the region requires a LocationConstraint
           # declaration.
           LocationConstraint: false
 
-          # Bucket name.
-          Bucket: example-bucket-name
-
           # Requested page size for "list bucket contents" requests.
           IndexPageSize: 1000
 
@@ -75,13 +73,6 @@ Volumes are configured in the @Volumes@ section of the cluster configuration fil
           # Maximum eventual consistency latency
           RaceWindow: 24h
 
-          # Enable deletion (garbage collection) even when the
-          # configured BlobTrashLifetime is zero.  WARNING: eventual
-          # consistency may result in race conditions that can cause
-          # data loss.  Do not enable this unless you understand and
-          # accept the risk.
-          UnsafeDelete: false
-
         # How much replication is provided by the underlying bucket.
         # This is used to inform replication decisions at the Keep
         # layer.
diff --git a/doc/install/google-auth.html.textile.liquid b/doc/install/google-auth.html.textile.liquid
new file mode 100644
index 0000000000..ef45a841d8
--- /dev/null
+++ b/doc/install/google-auth.html.textile.liquid
@@ -0,0 +1,26 @@
+---
+layout: default
+navsection: installguide
+title: Setting up Google auth
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+In order to use Google for authentication, you must use the Google Developers Console to create a set of client credentials.
+
+# Go to the Google Developers Console and select or create a project; this will take you to the project page.
+# On the sidebar, click on *APIs & auth* then select *APIs*.
+## Search for *Contacts API* and click on *Enable API*.
+## Search for *Google+ API* and click on *Enable API*.
+# On the sidebar, click on *Credentials*; under *OAuth* click on *Create new Client ID* to bring up the *Create Client ID* dialog box.
+# Under *Application type* select *Web application*.
+# If the authorization origins are not displayed, clicking on *Create Client ID* will take you to *Consent screen* settings.
+## On consent screen settings, enter the appropriate details and click on *Save*.
+## This will return you to the *Create Client ID* dialog box.
+# You must set the authorization origins.  Edit @auth.your.domain@ to the appropriate hostname that you will use to access the SSO service:
+## JavaScript origin should be @https://auth.example.com/@
+## Redirect URI should be @https://auth.example.com/users/auth/google_oauth2/callback@
+# Copy the values of *Client ID* and *Client secret* from the Google Developers Console and add them to the appropriate configuration.
diff --git a/doc/install/index.html.textile.liquid b/doc/install/index.html.textile.liquid
index 527b62cf3b..efa671db8c 100644
--- a/doc/install/index.html.textile.liquid
+++ b/doc/install/index.html.textile.liquid
@@ -9,7 +9,7 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-Arvados components run on GNU/Linux systems, and supports multiple cloud operating stacks.  Arvados supports Debian and derivatives such as Ubuntu, as well as Red Hat and derivatives such as CentOS.  "Arvados is Free Software":{{site.baseurl}}/copying/copying.html and self-install installations are not limited in any way.  Commercial support and development are also available from "Curii Corporation.":mailto:info@curii.com
+Arvados components run on GNU/Linux systems, and supports AWS, GCP and Azure cloud platforms as well as on-premises installs.  Arvados supports Debian and derivatives such as Ubuntu, as well as Red Hat and derivatives such as CentOS.  "Arvados is Free Software":{{site.baseurl}}/copying/copying.html and self-install installations are not limited in any way.  Commercial support and development are also available from "Curii Corporation.":mailto:info@curii.com
 
 Arvados components can be installed and configured in a number of different ways.
 
diff --git a/doc/install/install-api-server.html.textile.liquid b/doc/install/install-api-server.html.textile.liquid
index c234bca927..1f885f909a 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: installguide
-title: Install the API server
+title: Install API server and Controller
 ...
 {% comment %}
 Copyright (C) The Arvados Authors. All rights reserved.
@@ -9,269 +9,221 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-h2. Install prerequisites
+# "Introduction":#introduction
+# "Install dependencies":#dependencies
+# "Set up database":#database-setup
+# "Update config.yml":#update-config
+# "Update nginx configuration":#update-nginx
+# "Install arvados-api-server and arvados-controller":#install-packages
+# "Confirm working installation":#confirm-working
 
-The Arvados package repository includes an API server package that can help automate much of the deployment.
+h2(#introduction). Introduction
 
-h3(#install_ruby_and_bundler). Install Ruby and Bundler
+The Arvados core API server consists of four services: PostgreSQL, Arvados Rails API, Arvados Controller, and Nginx.
 
-{% include 'install_ruby_and_bundler' %}
+Here is a simplified diagram showing the relationship between the core services.  Client requests arrive at the public-facing Nginx reverse proxy.  The request is forwarded to Arvados controller.  The controller is able handle some requests itself, the rest are forwarded to the Arvados Rails API.  The Rails API server implements the majority of business logic, communicating with the PostgreSQL database to fetch data and make transactional updates.  All services are stateless, except the PostgreSQL database.  This guide assumes all of these services will be installed on the same node, but it is possible to install these services across multiple nodes.
 
-h2(#install_apiserver). Install API server and dependencies
+!(full-width){{site.baseurl}}/images/proxy-chain.svg!
 
-On a Debian-based system, install the following packages:
+h2(#dependencies). Install dependencies
 
-
-
    ~$ sudo apt-get install bison build-essential libcurl4-openssl-dev git arvados-api-server
-
    
-    
-
-On a Red Hat-based system, install the following packages:
-
-
-
    ~$ sudo yum install bison make automake gcc gcc-c++ libcurl-devel git arvados-api-server
-
    
-    
-
-{% include 'install_git' %}
-
-h2(#configure_application). Configure the API server
+# "Install PostgreSQL":install-postgresql.html
+# "Install Ruby and Bundler":ruby.html
+# "Install nginx":nginx.html
+# "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html
 
-Edit @/etc/arvados/config.yml@ to set the keys below.  Only the most important configuration options are listed here.  The example configuration fragments given below should be merged into a single configuration structure.  Correct indentation is important.  The full set of configuration options are listed in "config.yml":{{site.baseurl}}/admin/config.html
+h2(#database-setup). Set up database
 
-h3(#uuid_prefix). ClusterID
+{% assign service_role = "arvados" %}
+{% assign service_database = "arvados_production" %}
+{% assign use_contrib = true %}
+{% include 'install_postgres_database' %}
 
-The @ClusterID@ is used for all database identifiers to identify the record as originating from this site.  It is the first key under @Clusters@ in @config.yml@.  It must be exactly 5 lowercase ASCII letters and digits.  All configuration items go under the cluster id key (replace @zzzzz@ with your cluster id in the examples below).
+h2(#update-config). Update config.yml
 
-
-
    Clusters:
-  zzzzz:
-    ...
    
-    
-
-h3(#configure). PostgreSQL.Connection
+Starting from an "empty config.yml file,":config.html#empty add the following configuration keys.
 
-Replace the @xxxxxxxx@ database password placeholder with the "password you generated during database setup":install-postgresql.html#api.
+h3. Tokens
 
 
-
    Clusters:
-  zzzzz:
-    PostgreSQL:
-      Connection:
-        host: localhost
-        user: arvados
-        password: xxxxxxxx
-        dbname: arvados_production
-      
    
-    
-
-h3. API.RailsSessionSecretToken
-
-The @API.RailsSessionSecretToken@ is used for for signing cookies.  IMPORTANT: This is a site secret. It should be at least 50 characters.  Generate a random value and set it in @config.yml@:
-
-
-
    ~$ ruby -e 'puts rand(2**400).to_s(36)'
-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
-
    
-
-Example @config.yml@:
-
-
-
    Clusters:
-  zzzzz:
+
        SystemRootToken: "$system_root_token"
+    ManagementToken: "$management_token"
     API:
-      RailsSessionSecretToken: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
    
-
-
-h3(#blob_signing_key). Collections.BlobSigningKey
-
-The @Collections.BlobSigningKey@ is used to enforce access control to Keep blocks.  This same key must be provided to the Keepstore daemons when "installing Keepstore servers.":install-keepstore.html  IMPORTANT: This is a site secret. It should be at least 50 characters.  Generate a random value and set it in @config.yml@:
-
-
-
    ~$ ruby -e 'puts rand(2**400).to_s(36)'
-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-
    
-
-Example @config.yml@:
-
-
-
    Clusters:
-  zzzzz:
+      RailsSessionSecretToken: "$rails_secret_token"
     Collections:
-      BlobSigningKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    
+      BlobSigningKey: "blob_signing_key"
+
    
     
 
-h3(#omniauth). Login.ProviderAppID, Login.ProviderAppSecret, Services.SSO.ExternalURL
-
-The following settings enable the API server to communicate with the "Single Sign On (SSO) server":install-sso.html to authenticate user log in.
+@SystemRootToken@ is used by Arvados system services to authenticate as the system (root) user when communicating with the API server.
 
-Set @Services.SSO.ExternalURL@ to the base URL where your SSO server is installed.  This should be a URL consisting of the scheme and host (and optionally, port), without a trailing slash.
-
-Set @Login.ProviderAppID@ and @Login.ProviderAppSecret@ to the corresponding values for @app_id@ and @app_secret@ used in the "Create arvados-server client for Single Sign On (SSO)":install-sso.html#client step.
-
-Example @config.yml@:
-
-
-
    Clusters:
-  zzzzz:
-    Services:
-      SSO:
-        ExternalURL: https://sso.example.com
-    Login:
-      ProviderAppID: arvados-server
-      ProviderAppSecret: wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
    
-    
+@ManagementToken@ is used to authenticate access to system metrics.
 
-h3. Services.Workbench1.ExternalURL
+@API.RailsSessionSecretToken@ is required by the API server.
 
-Set @Services.Workbench1.ExternalURL@ to the URL of your workbench application after following "Install Workbench.":install-workbench-app.html
+@Collections.BlobSigningKey@ is used to control access to Keep blocks.
 
-Example @config.yml@:
+You can generate a random token for each of these items at the command line like this:
 
 
-
    Clusters:
-  zzzzz:
-    Services:
-      Workbench1:
-        ExternalURL: https://workbench.zzzzz.example.com
    
+
    ~$ tr -dc 0-9a-zA-Z </dev/urandom | head -c50; echo
+
    
     
 
-h3. Services.Websocket.ExternalURL
-
-Set @Services.Websocket.ExternalURL@ to the @wss://@ URL of the API server websocket endpoint after following "Install the websocket server":install-ws.html .
-
-Example @config.yml@:
+h3. PostgreSQL.Connection
 
 
-
    Clusters:
-  zzzzz:
-    Services:
-      Websocket:
-        ExternalURL: wss://ws.zzzzz.example.com
    
+
        PostgreSQL:
+      Connection:
+        host: localhost
+        user: arvados
+        password: $postgres_password
+        dbname: arvados_production
+
    
     
 
-h3(#git_repositories_dir). Git.Repositories
-
-The @Git.Repositories@ setting specifies the directory where user git repositories will be stored.
+Replace the @$postgres_password@ placeholder with the password you generated during "database setup":#database-setup .
 
-The git server setup process is covered on "its own page":install-arv-git-httpd.html. For now, create an empty directory in the default location:
+h3. Services
 
 
-
    ~$ sudo mkdir -p /var/lib/arvados/git/repositories
-
    
-
-If you intend to store your git repositories in a different location, specify that location in @config.yml@.  Example:
-
-
-
    Clusters:
-  zzzzz:
-    Git:
-      Repositories: /var/lib/arvados/git/repositories
    
+
        Services:
+      Controller:
+        ExternalURL: "https://xxxxx.example.com"
+        InternalURLs:
+          "http://xxxxx.example.com:8003": {}
+      RailsAPI:
+        # Does not have an ExternalURL
+        InternalURLs:
+          "http://xxxxx.example.com:8004": {}
+
    
     
 
-h3(#enable_legacy_jobs_api). Containers.JobsAPI.Enable
+Replace @xxxxx.example.com@ with the hostname that you previously selected for the API server.
 
-Enable the legacy "Jobs API":install-crunch-dispatch.html .  Note: new installations should use the "Containers API":crunch2-slurm/install-prerequisites.html
+The @Services@ section of the configuration helps Arvados components contact one another (service discovery).  Each service has one or more @InternalURLs@ and an @ExternalURL@.  The @InternalURLs@ describe where the service runs, and how the Nginx reverse proxy will connect to it.  The @ExternalURL@ is how external clients contact the service.
 
-Disabling the jobs API means methods involving @jobs@, @job_tasks@, @pipeline_templates@ and @pipeline_instances@ are disabled.  This functionality is superceded by the containers API which consists of @container_requests@, @containers@ and @workflows@.  Arvados clients (such as @arvados-cwl-runner@) detect which APIs are available and adjust behavior accordingly.  Note the configuration value must be a quoted string.
+h2(#update-nginx). Update nginx configuration
 
-* 'auto' -- (default) enable the Jobs API only if it has been used before (i.e., there are job records in the database), otherwise disable jobs API .
-* 'true' -- enable the Jobs API even if there are no existing job records.
-* 'false' -- disable the Jobs API even in the presence of existing job records.
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-api-and-controller.conf@ with the following configuration.  Options that need attention are marked with "TODO".
 
 
-
    Clusters:
-  zzzzz:
-    Containers:
-      JobsAPI:
-        Enable: 'auto'
    
-    
+
    proxy_http_version 1.1;
 
-h4(#git_internal_dir). Containers.JobsAPI.GitInternalDir
+# When Keep clients request a list of Keep services from the API
+# server, use the origin IP address to determine if the request came
+# from the internal subnet or it is an external client.  This sets the
+# $external_client variable which in turn is used to set the
+# X-External-Client header.
+#
+# The API server uses this header to choose whether to respond to a
+# "available keep services" request with either a list of internal keep
+# servers (0) or with the keepproxy (1).
+#
+# TODO: Following the example here, update the netmask to the
+# your internal subnet.
 
-Only required if the legacy "Jobs API" is enabled, otherwise you should skip this.
-
-The @Containers.JobsAPI.GitInternalDir@ setting specifies the location of Arvados' internal git repository.  By default this is @/var/lib/arvados/internal.git@.  This repository stores git commits that have been used to run Crunch jobs.  It should _not_ be a subdirectory of the directory in @Git.Repositories@.
+geo $external_client {
+  default        1;
+  10.20.30.0/24  0;
+}
 
-Example @config.yml@:
+# This is the port where nginx expects to contact arvados-controller.
+upstream controller {
+  server     xxxxx.example.com:8003  fail_timeout=10s;
+}
 
-
-
    Clusters:
-  zzzzz:
-    Containers:
-      JobsAPI:
-        GitInternalDir: /var/lib/arvados/internal.git
    
-    
+server {
+  # This configures the public https port that clients will actually connect to,
+  # the request is reverse proxied to the upstream 'controller'
 
-h2(#set_up). Set up Nginx and Passenger
+  listen       xxxxx.example.com:443 ssl;
+  server_name  xxxxx.example.com;
 
-The Nginx server will serve API requests using Passenger. It will also be used to proxy SSL requests to other services which are covered later in this guide.
+  ssl on;
+  ssl_certificate     /TODO/YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key /TODO/YOUR/PATH/TO/cert.key;
 
-First, "Install Nginx and Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html.
+  # Refer to the comment about this setting in the passenger (arvados
+  # api server) section of your Nginx configuration.
+  client_max_body_size 128m;
 
-Edit the http section of your Nginx configuration to run the Passenger server. Add a block like the following, adding SSL and logging parameters to taste:
+  location / {
+    proxy_pass            http://controller;
+    proxy_redirect        off;
+    proxy_connect_timeout 90s;
+    proxy_read_timeout    300s;
+
+    proxy_set_header      X-Forwarded-Proto https;
+    proxy_set_header      Host $http_host;
+    proxy_set_header      X-External-Client $external_client;
+    proxy_set_header      X-Real-IP $remote_addr;
+    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
+  }
+}
 
-
-
    
 server {
-  listen 127.0.0.1:8000;
+  # This configures the Arvados API server.  It is written using Ruby
+  # on Rails and uses the Passenger application server.
+
+  listen xxxxx.example.com:8004;
   server_name localhost-api;
 
   root /var/www/arvados-api/current/public;
   index  index.html index.htm index.php;
 
   passenger_enabled on;
-  # If you're using RVM, uncomment the line below.
+
+  # TODO: If you are using RVM, uncomment the line below.
+  # If you're using system ruby, leave it commented out.
   #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
 
   # This value effectively limits the size of API objects users can
   # create, especially collections.  If you change this, you should
   # also ensure the following settings match it:
-  # * `client_max_body_size` in the server section below
-  # * `client_max_body_size` in the Workbench Nginx configuration (twice)
+  # * `client_max_body_size` in the previous server section
   # * `API.MaxRequestSize` in config.yml
   client_max_body_size 128m;
 }
+
    
+    
 
-upstream api {
-  server     127.0.0.1:8000  fail_timeout=10s;
-}
+h2(#install-packages). Install arvados-api-server and arvados-controller
 
-proxy_http_version 1.1;
+h3. Centos 7
 
-# When Keep clients request a list of Keep services from the API server, the
-# server will automatically return the list of available proxies if
-# the request headers include X-External-Client: 1.  Following the example
-# here, at the end of this section, add a line for each netmask that has
-# direct access to Keep storage daemons to set this header value to 0.
-geo $external_client {
-  default        1;
-  10.20.30.0/24  0;
-}
+
+
    # yum install arvados-api-server arvados-controller
 
    
     
 
-Restart Nginx to apply the new configuration.
+h3. Debian and Ubuntu
 
 
-
    ~$ sudo nginx -s reload
+
    # apt-get --no-install-recommends install arvados-api-server arvados-controller
 
    
 
 
-h2. Prepare the API server deployment
+h2(#confirm-working). Confirm working installation
+
+Confirm working controller:
+
+
    +$ curl https://xxxxx.example.com/arvados/v1/config
+
    
 
-{% assign railspkg = "arvados-api-server" %}
-{% include 'install_rails_reconfigure' %}
+Confirm working Rails API server:
 
-{% include 'notebox_begin' %}
-You can safely ignore the following messages if they appear while this command runs:
+
    +$ curl https://xxxxx.example.com/discovery/v1/apis/arvados/v1/rest
+
    
 
-
    Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will
-break this application for all non-root users on this machine.
    
+Confirm that you can use the system root token to act as the system root user:
 
-
    fatal: Not a git repository (or any of the parent directories): .git
    
-{% include 'notebox_end' %}
+
    +$ curl -H "Authorization: Bearer $system_root_token" https://xxxxx.example.com/arvados/v1/users/current
+
    
 
-h2. Troubleshooting
+h3. Troubleshooting
 
-Once you have the API Server up and running you may need to check it back if dealing with client related issues. Please read our "admin troubleshooting notes":{{site.baseurl}}/admin/troubleshooting.html on how requests can be tracked down between services.
\ No newline at end of file
+See the admin page on "Logging":{{site.baseurl}}/admin/logging.html .
diff --git a/doc/install/install-arv-git-httpd.html.textile.liquid b/doc/install/install-arv-git-httpd.html.textile.liquid
index c25fdee1dd..964f5a25ac 100644
--- a/doc/install/install-arv-git-httpd.html.textile.liquid
+++ b/doc/install/install-arv-git-httpd.html.textile.liquid
@@ -9,63 +9,46 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-Arvados allows users to create their own private and public git repositories, and clone/push them using SSH and HTTPS.
+# "Introduction":#introduction
+# "Install dependencies":#dependencies
+# "Create "git" user and storage directory":#create
+# "Install gitolite":#gitolite
+# "Configure gitolite":#config-gitolite
+# "Configure git synchronization":#sync
+# "Update config.yml":#update-config
+# "Update nginx configuration":#update-nginx
+# "Install arvados-git-httpd package":#install-packages
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
+
+h2(#introduction). Introduction
+
+Arvados support for git repository management enables using Arvados permissions to control access to git repositories.  Users can create their own private and public git repositories and share them with others.
 
 The git hosting setup involves three components.
 * The "arvados-git-sync.rb" script polls the API server for the current list of repositories, creates bare repositories, and updates the local permission cache used by gitolite.
-* Gitolite provides SSH access.
-* arvados-git-http provides HTTPS access.
+* Gitolite provides SSH access.  Users authenticate by SSH keys.
+* arvados-git-http provides HTTPS access.  Users authenticate by Arvados tokens.
 
-It is not strictly necessary to deploy _both_ SSH and HTTPS access, but we recommend deploying both:
-* SSH is a more appropriate way to authenticate from a user's workstation because it does not require managing tokens on the client side;
-* HTTPS is a more appropriate way to authenticate from a shell VM because it does not depend on SSH agent forwarding (SSH clients' agent forwarding features tend to behave as if the remote machine is fully trusted).
-* HTTPS is also used by Arvados Composer to access git repositories from the browser.
+Git services must be installed on the same host as the Arvados Rails API server.
 
-The HTTPS instructions given below will not work if you skip the SSH setup steps.
+h2(#dependencies). Install dependencies
 
-h2. Set up DNS
-
-By convention, we use the following hostname for the git service:
+h3. Centos 7
 
 
-
    git.uuid_prefix.your.domain
+
    # yum install git perl-Data-Dumper openssh-server
 
    
 
 
-{% include 'notebox_begin' %}
-Here, we show how to install the git hosting services *on the same host as your API server.* Using a different host is not yet fully supported. On this page we will refer to it as your git server.
-{% include 'notebox_end' %}
-
-DNS and network configuration should be set up so port 443 reaches your HTTPS proxy, and port 22 reaches the OpenSSH service on your git server.
-
-h2. Generate an API token
-
-{% assign railshost = "gitserver" %}
-{% assign railscmd = "bundle exec ./script/create_superuser_token.rb" %}
-{% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %}
-Use the following command to generate an API token.  {% include 'install_rails_command' %}
-
-Copy that token; you'll need it in a minute.
-
-h2. Install git and other dependencies
-
-On Debian-based systems:
+h3. Debian and Ubuntu
 
 
-
    gitserver:~$ sudo apt-get install git openssh-server
+
    # apt-get --no-install-recommends install git openssh-server
 
    
 
 
-On Red Hat-based systems:
-
-
-
    gitserver:~$ sudo yum install git perl-Data-Dumper openssh-server
-
    
-    
-
-{% include 'install_git' %}
-
-h2. Create a "git" user and a storage directory
+h2(#create). Create "git" user and storage directory
 
 Gitolite and some additional scripts will be installed in @/var/lib/arvados/git@, which means hosted repository data will be stored in @/var/lib/arvados/git/repositories@. If you choose to install gitolite in a different location, make sure to update the @git_repositories_dir@ entry in your API server's @application.yml@ file accordingly: for example, if you install gitolite at @/data/gitolite@ then your @git_repositories_dir@ will be @/data/gitolite/repositories@.
 
@@ -93,15 +76,16 @@ git@gitserver:~$ rm .ssh/authorized_keys
 
    
     
 
-h2. Install gitolite
+h2(#gitolite). Install gitolite
 
 Check "https://github.com/sitaramc/gitolite/tags":https://github.com/sitaramc/gitolite/tags for the latest stable version. This guide was tested with @v3.6.4@. _Versions below 3.0 are missing some features needed by Arvados, and should not be used._
 
 Download and install the version you selected.
 
 
-
    git@gitserver:~$ echo 'PATH=$HOME/bin:$PATH' >.profile
-git@gitserver:~$ source .profile
+
    # su git
+git@gitserver:~$ echo 'PATH=$HOME/bin:$PATH' >.profile
+git@gitserver:~$ . .profile
 git@gitserver:~$ git clone --branch v3.6.4 https://github.com/sitaramc/gitolite
 ...
 Note: checking out '5d24ae666bfd2fa9093d67c840eb8d686992083f'.
@@ -137,7 +121,7 @@ Everything up-to-date
 
    
 
 
-h3. Configure gitolite
+h2(#config-gitolite). Configure gitolite
 
 Configure gitolite to look up a repository name like @username/reponame.git@ and find the appropriate bare repository storage directory.
 
@@ -175,17 +159,17 @@ Uncomment the 'Alias' line in the section that begins @ENABLE => [@:
 
    
     
 
-h2. Configure git synchronization
+h2(#sync). Configure git synchronization
 
 Create a configuration file @/var/www/arvados-api/current/config/arvados-clients.yml@ using the following template, filling in the appropriate values for your system.
-* For @arvados_api_token@, use the token you generated above.
+* For @arvados_api_token@, use @SystemRootToken@
 * For @gitolite_arvados_git_user_key@, provide the public key you generated above, i.e., the contents of @~git/.ssh/id_rsa.pub@.
 
 
 
    production:
   gitolite_url: /var/lib/arvados/git/repositories/gitolite-admin.git
   gitolite_tmp: /var/lib/arvados/git
-  arvados_api_host: uuid_prefix.example.com
+  arvados_api_host: ClusterID.example.com
   arvados_api_token: "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
   arvados_api_host_insecure: false
   gitolite_arvados_git_user_key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7aBIDAAgMQN16Pg6eHmvc+D+6TljwCGr4YGUBphSdVb25UyBCeAEgzqRiqy0IjQR2BLtSirXr+1SJAcQfBgI/jwR7FG+YIzJ4ND9JFEfcpq20FvWnMMQ6XD3y3xrZ1/h/RdBNwy4QCqjiXuxDpDB7VNP9/oeAzoATPZGhqjPfNS+RRVEQpC6BzZdsR+S838E53URguBOf9yrPwdHvosZn7VC0akeWQerHqaBIpSfDMtaM4+9s1Gdsz0iP85rtj/6U/K/XOuv2CZsuVZZ52nu3soHnEX2nx2IaXMS3L8Z+lfOXB2T6EaJgXF7Z9ME5K1tx9TSNTRcYCiKztXLNLSbp git@gitserver"
@@ -196,115 +180,37 @@ h3. Enable the synchronization script
 
 The API server package includes a script that retrieves the current set of repository names and permissions from the API, writes them to @arvadosaliases.pl@ in a format usable by gitolite, and triggers gitolite hooks which create new empty repositories if needed. This script should run every 2 to 5 minutes.
 
-If you are using RVM, create @/etc/cron.d/arvados-git-sync@ with the following content:
-
-
-
    */5 * * * * git cd /var/www/arvados-api/current && /usr/local/rvm/bin/rvm-exec default bundle exec script/arvados-git-sync.rb production
-
    
-    
-
-Otherwise, create @/etc/cron.d/arvados-git-sync@ with the following content:
+Create @/etc/cron.d/arvados-git-sync@ with the following content:
 
 
 
    */5 * * * * git cd /var/www/arvados-api/current && bundle exec script/arvados-git-sync.rb production
 
    
     
 
-h3. Configure the API server to advertise the correct SSH URLs
+h2(#update-config). Update config.yml
 
-Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.GitSSH.ExternalURL@. Replace @uuid_prefix@ with your cluster id.
+Edit the cluster config at @/etc/arvados/config.yml@ .
 
 
-
    Clusters:
-  uuid_prefix:
-    Services:
+
        Services:
       GitSSH:
-        ExternalURL: git@git.uuid_prefix.your.domain:
-
    
-
-
-Make sure to include the trailing colon.
-
-h2. Install the arvados-git-httpd package
-
-This is needed only for HTTPS access.
-
-The arvados-git-httpd package provides HTTP access, using Arvados authentication tokens instead of passwords. It is intended to be installed on the system where your git repositories are stored, and accessed through a web proxy that provides SSL support.
-
-On Debian-based systems:
-
-
-
    ~$ sudo apt-get install git arvados-git-httpd
-
    
-    
-
-On Red Hat-based systems:
-
-
-
    ~$ sudo yum install git arvados-git-httpd
-~$ sudo systemctl enable arvados-git-httpd
-
    
-    
-
-Verify that @arvados-git-httpd@ and @git-http-backend@ can be run:
-
-
-
    ~$ arvados-git-httpd -h
-[...]
-Usage: arvados-git-httpd [-config path/to/arvados/git-httpd.yml]
-[...]
-~$ git http-backend
-Status: 500 Internal Server Error
-Expires: Fri, 01 Jan 1980 00:00:00 GMT
-Pragma: no-cache
-Cache-Control: no-cache, max-age=0, must-revalidate
-
-fatal: No REQUEST_METHOD from server
-
    
-    
-
-h3. Enable arvados-git-httpd
-
-{% include 'notebox_begin' %}
-
-The arvados-git-httpd package includes configuration files for systemd.  If you're using a different init system, you'll need to configure a service to start and stop an @arvados-git-httpd@ process as desired.
-
-{% include 'notebox_end' %}
-
-Edit the cluster config at @/etc/arvados/config.yml@ and set the following values. Replace @uuid_prefix@ with your cluster id.
-
-
-
    Clusters:
-  uuid_prefix:
-    Services:
+        ExternalURL: git@git.ClusterID.example.com:
       GitHTTP:
-        ExternalURL: https://git.uuid_prefix.your.domain/
+        ExternalURL: https://git.ClusterID.example.com/
         InternalURLs:
-	  "http://localhost:9001": {}
+	  "http://git.ClusterID.example.com:9001": {}
     Git:
       GitCommand: /var/lib/arvados/git/gitolite/src/gitolite-shell
       GitoliteHome: /var/lib/arvados/git
-      Repositories: /var/lib/arvados/git/repositories
-
    
-    
-
-Make sure to include the trailing slash for @Services.GitHTTP.ExternalURL@.
-
-Restart the systemd service to ensure the new configuration is used.
-
-
-
-
    ~$ sudo systemctl restart arvados-git-httpd
+      Repositories: /var/lib/arvados/git/repositories	
 
    
     
 
-h3. Set up a reverse proxy to provide SSL service
-
-The arvados-git-httpd service will be accessible from anywhere on the internet, so we recommend using SSL.
+Make sure to include the trailing colon in @Services.GitSSH.ExternalURL@.
 
-This is best achieved by putting a reverse proxy with SSL support in front of arvados-git-httpd, running on port 443 and passing requests to @arvados-git-httpd@ on port 9001 (or whichever port you used in your run script).
+h2(#update-nginx). Update nginx configuration
 
-Add the following configuration to the @http@ section of your Nginx configuration:
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-git.conf@ with the following configuration.  Options that need attention are marked with "TODO".
 
 
 
    
@@ -313,7 +219,7 @@ upstream arvados-git-httpd {
 }
 server {
   listen                  [your public IP address]:443 ssl;
-  server_name             git.uuid_prefix.your.domain;
+  server_name             git.ClusterID.example.com;
   proxy_connect_timeout   90s;
   proxy_read_timeout      300s;
 
@@ -322,7 +228,7 @@ server {
   ssl_certificate_key     /YOUR/PATH/TO/cert.key;
 
   # The server needs to accept potentially large refpacks from push clients.
-  client_max_body_size 50m;
+  client_max_body_size 128m;
 
   location  / {
     proxy_pass            http://arvados-git-httpd;
@@ -331,55 +237,55 @@ server {
 
    
     
 
-h2. Restart Nginx
+h2(#install-packages). Install the arvados-git-httpd package
+
+The arvados-git-httpd package provides HTTP access, using Arvados authentication tokens instead of passwords. It must be installed on the system where your git repositories are stored.
+
+h3. Centos 7
+
+
+
    # yum install arvados-git-httpd
+
    
+    
 
-Restart Nginx to make the Nginx and API server configuration changes take effect.
+h3. Debian and Ubuntu
 
 
-
    gitserver:~$ sudo nginx -s reload
+
    # apt-get --no-install-recommends install arvados-git-httpd
 
    
 
 
-h2. Clone Arvados repository
+h2(#restart-api). Restart the API server and controller
 
-Here we create a repository object which will be used to set up a hosted clone of the arvados repository on this cluster.
+After adding Workbench to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 
 
-
    ~$ uuid_prefix=`arv --format=uuid user current | cut -d- -f1`
-~$ echo "Site prefix is '$uuid_prefix'"
-~$ all_users_group_uuid="$uuid_prefix-j7d0g-fffffffffffffff"
-~$ repo_uuid=`arv --format=uuid repository create --repository "{\"owner_uuid\":\"$uuid_prefix-tpzed-000000000000000\", \"name\":\"arvados\"}"`
-~$ echo "Arvados repository uuid is '$repo_uuid'"
-
    
+
    # systemctl restart nginx arvados-controller
+
    
+
+
+h2(#confirm-working). Confirm working installation
 
-Create a link object to make the repository object readable by the "All users" group, and therefore by every active user. This makes it possible for users to run the bundled Crunch scripts by specifying @"script_version":"master","repository":"arvados"@ rather than pulling the Arvados source tree into their own repositories.
+Create 'testrepo' in the Arvados database.
 
 
-
    ~$ read -rd $'\000' newlink <<EOF; arv link create --link "$newlink"
-{
- "tail_uuid":"$all_users_group_uuid",
- "head_uuid":"$repo_uuid",
- "link_class":"permission",
- "name":"can_read"
-}
-EOF
+
    ~$ arv --format=uuid repository create --repository '{"name":"testrepo"}'
 
    
 
-In a couple of minutes, your arvados-git-sync cron job will create an empty repository on your git server. Seed it with the real arvados repository. If your git credential helpers were configured correctly when you "set up your shell server":install-shell-server.html, the "git push" command will use your API token instead of prompting you for a username and password.
+The arvados-git-sync cron job will notice the new repository record and create a repository on disk.  Because it is on a timer (default 5 minutes) you may have to wait a minute or two for it to show up.
+
+h3. SSH
 
 
-
    ~$ cd /tmp
-/tmp$ git clone --bare https://github.com/curoverse/arvados.git
-/tmp git --git-dir arvados.git push https://git.uuid_prefix.your.domain/arvados.git '*:*'
+
    ~$ git clone git@git.ClusterID.example.com:username/testrepo.git
 
    
 
 
-If you did not set up a HTTPS service, you can push to git@git.uuid_prefix.your.domain:arvados.git using your SSH key, or by logging in to your git server and using sudo.
+h3. HTTP
+
+Set up git credential helpers as described in "install shell server":install-shell-server.html for the "git push" command to use your API token instead of prompting you for a username and password.
 
 
-
    gitserver:~$ sudo -u git -i bash
-git@gitserver:~$ git clone --bare https://github.com/curoverse/arvados.git /tmp/arvados.git
-git@gitserver:~$ cd /tmp/arvados.git
-git@gitserver:/tmp/arvados.git$ gitolite push /var/lib/arvados/git/repositories/your_arvados_repo_uuid.git '*:*'
+
    ~$ git clone https://git.ClusterID.example.com/username/testrepo.git
 
    
 
diff --git a/doc/install/install-composer.html.textile.liquid b/doc/install/install-composer.html.textile.liquid
index f0938e860d..d27db4d4e5 100644
--- a/doc/install/install-composer.html.textile.liquid
+++ b/doc/install/install-composer.html.textile.liquid
@@ -11,57 +11,70 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 
 Arvados Composer is a web-based javascript application for building Common Workflow Languge (CWL) Workflows.
 
-h2. Prerequisites
+# "Install dependencies":#dependencies
+# "Update config.yml":#update-config
+# "Update Nginx configuration":#update-nginx
+# "Install arvados-composer":#install-packages
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
 
-In addition to Arvados core services, Composer requires "Arvados hosted git repositories":install-arv-git-httpd.html which are used for storing workflow files.
-
-h2. Install
+h2(#dependencies). Install dependencies
 
-Composer may be installed on the same host as Workbench, or on a different host.  Composer communicates directly with the Arvados API server.  It does not require its own backend and should be served as a static file.
-
-On a Debian-based system, install the following package:
+In addition to Arvados core services, Composer requires "Arvados hosted git repositories":install-arv-git-httpd.html which are used for storing workflow files.
 
-
-
    ~$ sudo apt-get install arvados-composer
-
    
-    
+h2(#configure). Update config.yml
 
-On a Red Hat-based system, install the following package:
+Edit @config.yml@ and set @Services.Composer.ExternalURL@ to the location from which it is served:
 
 
-
    ~$ sudo yum install arvados-composer
-
    
+
        Services:
+      Composer:
+        ExternalURL: https://workbench.CusterID.example.com/composer
    
     
 
-h2. Configure
+h2(#update-nginx). Update nginx configuration
 
-h3. Nginx
+Composer may be served from the same host as Workbench.  Composer communicates directly with the Arvados API server.  It does not require its own backend and should be served as a static file.
 
-Add Composer to your Nginx configuration.  This example will host Composer at @/composer@.
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-composer.conf@ with the following configuration.  Options that need attention are marked with "TODO".
 
-
    -location /composer {
+
+
    location /composer {
   root   /var/www/arvados-composer
   index  index.html
 }
-
    
 
-h3. composer.yml
+location /composer.yml {
+  return 200 '{ "API_HOST": "ClusterID.example.com" }';
+}
+
    
+
+
+h2(#install-packages). Install arvados-composer
 
-Create @/var/www/arvados-composer/composer.yml@ and set @API_HOST@ to your API server:
+h3. Centos 7
 
-
    -API_HOST: zzzzz.arvadosapi.com
-
    
+
+
    # yum install arvados-composer
+
    
+    
 
-h3. Workbench link to composer
+h3. Debian and Ubuntu
 
-Edit @config.yml@ and set @Services.Composer.ExternalURL@ to the location from which it is served:
+
+
    # apt-get --no-install-recommends install arvados-composer
+
    
+    
+
+h2(#restart-api). Restart the API server and controller
+
+After adding Workbench to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 
 
-
    Clusters:
-  zzzzz:
-    Services:
-      Composer:
-        ExternalURL: https://workbench.zzzzz.arvadosapi.com/composer
    
+
    # systemctl restart nginx arvados-controller
+
    
     
+
+h2(#confirm-working). Confirm working installation
+
+Visit @https://workbench.ClusterID.example.com/composer@ in a browser.  You should be able to log in using the login method you configured previously.
diff --git a/doc/install/install-controller.html.textile.liquid b/doc/install/install-controller.html.textile.liquid
deleted file mode 100644
index f78467f5be..0000000000
--- a/doc/install/install-controller.html.textile.liquid
+++ /dev/null
@@ -1,197 +0,0 @@
----
-layout: default
-navsection: installguide
-title: Install the controller
-...
-{% comment %}
-Copyright (C) The Arvados Authors. All rights reserved.
-
-SPDX-License-Identifier: CC-BY-SA-3.0
-{% endcomment %}
-
-The arvados-controller service must be installed on your API server node.
-
-On Debian-based systems:
-
-
-
    ~$ sudo apt-get install arvados-controller
-
    
-    
-
-On Red Hat-based systems:
-
-
-
    ~$ sudo yum install arvados-controller
-
    
-    
-
-Verify the @arvados-controller@ program is functional:
-
-
-
    ~$ arvados-controller -h
-Usage:
-  -config file
-[...]
-
    
-    
-
-h3. Configure Nginx to route requests to the controller
-
-Add @upstream@ and @server@ definitions inside the @http@ section of your Nginx configuration using the following template.
-
-{% include 'notebox_begin' %}
-
-If you are adding arvados-controller to an existing system as part of the upgrade procedure, do not add a new "server" part here. Instead, add only the "upstream" part as shown here, and update your existing "server" section by changing its @proxy_pass@ directive from @http://api@ to @http://controller@.
-
-{% include 'notebox_end' %}
-
-
-
    upstream controller {
-  server     127.0.0.1:9004  fail_timeout=10s;
-}
-
-server {
-  listen       [your public IP address]:443 ssl;
-  server_name  uuid_prefix.your.domain;
-
-  ssl on;
-  ssl_certificate     /YOUR/PATH/TO/cert.pem;
-  ssl_certificate_key /YOUR/PATH/TO/cert.key;
-
-  # Refer to the comment about this setting in the passenger (arvados
-  # api server) section of your Nginx configuration.
-  client_max_body_size 128m;
-
-  location / {
-    proxy_pass            http://controller;
-    proxy_redirect        off;
-    proxy_connect_timeout 90s;
-    proxy_read_timeout    300s;
-
-    proxy_set_header      X-Forwarded-Proto https;
-    proxy_set_header      Host $http_host;
-    proxy_set_header      X-External-Client $external_client;
-    proxy_set_header      X-Real-IP $remote_addr;
-    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
-  }
-}
-
    
-    
-
-Restart Nginx to apply the new configuration.
-
-
-
    ~$ sudo nginx -s reload
-
    
-    
-
-h3(#configuration). Configure arvados-controller
-
-Create the cluster configuration file @/etc/arvados/config.yml@ using the following template.
-
-
-
    Clusters:
-  uuid_prefix:
-    Services:
-      Controller:
-        InternalURLs:
-          "http://localhost:9004": {} # must match the "upstream controller" section of your Nginx config
-      RailsAPI:
-        arvados-api-server:
-          "http://localhost:8000": {} # must match the "upstream api" section of your Nginx config
-    PostgreSQL:
-      ConnectionPool: 128
-      Connection:
-        host: localhost
-        dbname: arvados_production
-        user: arvados
-        password: xxxxxxxx
-        sslmode: require
-
    
-    
-
-Create the host configuration file @/etc/arvados/environment@.
-
-
-
    ARVADOS_NODE_PROFILE=apiserver
-
    
-    
-
-h3. Start the service (option 1: systemd)
-
-If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
-
-If your system uses systemd, the arvados-controller service should already be set up. Restart it to load the new configuration file, and check its status:
-
-
-
    ~$ sudo systemctl restart arvados-controller
-~$ sudo systemctl status arvados-controller
-● arvados-controller.service - Arvados controller
-   Loaded: loaded (/lib/systemd/system/arvados-controller.service; enabled; vendor preset: enabled)
-   Active: active (running) since Tue 2018-07-31 13:17:44 UTC; 3s ago
-     Docs: https://doc.arvados.org/
- Main PID: 25066 (arvados-control)
-   CGroup: /system.slice/arvados-controller.service
-           └─25066 /usr/bin/arvados-controller
-
-Jul 31 13:17:44 zzzzz systemd[1]: Starting Arvados controller...
-Jul 31 13:17:44 zzzzz arvados-controller[25191]: {"Listen":"[::]:9004","Service":"arvados-controller","level":"info","msg":"listening","time":"2018-07-31T13:17:44.521694195Z"}
-Jul 31 13:17:44 zzzzz systemd[1]: Started Arvados controller.
-
    
-    
-
-Skip ahead to "confirm the service is working":#confirm.
-
-h3(#runit). Start the service (option 2: runit)
-
-Install runit to supervise the arvados-controller daemon.  {% include 'install_runit' %}
-
-Create a supervised service.
-
-
-
    ~$ sudo mkdir /etc/service/arvados-controller
-~$ cd /etc/service/arvados-controller
-~$ sudo mkdir log log/main
-~$ printf '#!/bin/sh\nset -a\n. /etc/arvados/environment\nexec arvados-controller 2>&1\n' | sudo tee run
-~$ printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run
-~$ sudo chmod +x run log/run
-~$ sudo sv exit .
-~$ cd -
-
    
-    
-
-Use @sv stat@ and check the log file to verify the service is running.
-
-
-
    ~$ sudo sv stat /etc/service/arvados-controller
-run: /etc/service/arvados-controller: (pid 12520) 2s; run: log: (pid 12519) 2s
-~$ tail /etc/service/arvados-controller/log/main/current
-{"Listen":"[::]:9004","Service":"arvados-controller","level":"info","msg":"listening","time":"2018-07-31T13:17:44.521694195Z"}
-
    
-    
-
-h3(#confirm). Confirm the service is working
-
-Confirm the service is listening on its assigned port and responding to requests.
-
-
-
    ~$ curl -X OPTIONS http://0.0.0.0:9004/login
-{"errors":["Forbidden"],"error_token":"1533044555+684b532c"}
-
    
-    
-
-h3(#confirm-config). Confirm the public configuration is OK
-
-Confirm the publicly accessible configuration endpoint does not reveal any sensitive information (e.g., a secret that was mistakenly entered under the wrong configuration key). Use the jq program, if you have installed it, to make the JSON document easier to read.
-
-
-
    ~$ curl http://0.0.0.0:9004/arvados/v1/config | jq .
-{
-  "API": {
-    "MaxItemsPerResponse": 1000,
-    "MaxRequestAmplification": 4,
-    "RequestTimeout": "5m"
-  },
-  ...
-
    
-    
diff --git a/doc/install/install-keep-balance.html.textile.liquid b/doc/install/install-keep-balance.html.textile.liquid
index d29166459c..09bc04114d 100644
--- a/doc/install/install-keep-balance.html.textile.liquid
+++ b/doc/install/install-keep-balance.html.textile.liquid
@@ -9,6 +9,13 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+# "Introduction":#introduction
+# "Update config.yml":#update-config
+# "Install keep-balance package":#install-packages
+# "Start the service":#start-service
+
+h2(#introduction). Introduction
+
 Keep-balance deletes unreferenced and overreplicated blocks from Keep servers, makes additional copies of underreplicated blocks, and moves blocks into optimal locations as needed (e.g., after adding new servers). See "Balancing Keep servers":{{site.baseurl}}/admin/keep-balance.html for usage details.
 
 {% include 'notebox_begin' %}
@@ -17,61 +24,49 @@ If you are installing keep-balance on an existing system with valuable data, you
 
 {% include 'notebox_end' %}
 
-h2. Install keep-balance
-
-Keep-balance can be installed anywhere with network access to Keep services. Typically it runs on the same host as keepproxy.
-
-*A cluster should have only one keep-balance process running at a time.*
+h2(#update-config). Update the cluster config
 
-On Debian-based systems:
+Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Keepbalance.InternalURLs@.  This port is only used to publish metrics.
 
 
-
    ~$ sudo apt-get install keep-balance
+
        Services:
+      Keepbalance:
+        InternalURLs:
+          "http://keep.ClusterID.example.com:9005/": {}
 
    
 
 
-On Red Hat-based systems:
+Ensure your cluster configuration has @Collections.BlobTrash: true@ (this is the default).
 
 
-
    ~$ sudo yum install keep-balance
+
    # arvados-server config-dump | grep BlobTrash:
+      BlobTrash: true
 
    
 
 
-Verify that @keep-balance@ is functional:
+If BlobTrash is false, unneeded blocks will be counted and logged by keep-balance, but they will not be deleted.
 
-
-
    ~$ keep-balance -h
-...
-Usage of ./keep-balance:
-  -commit-pulls
-    	send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
-  -commit-trash
-    	send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
-...
-
    
-    
+h2(#install-packages). Install keep-balance package
+
+Keep-balance can be installed anywhere with network access to Keep services. Typically it runs on the same host as keepproxy.
 
-h3. Update the cluster config
+*A cluster should have only one instance of keep-balance running at a time.*
 
-Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Keepbalance.InternalURLs@. Replace @uuid_prefix@ with your cluster id.
+h3. Centos 7
 
 
-
    Clusters:
-  uuid_prefix:
-    Services:
-      Keepbalance:
-        InternalURLs:
-          "http://localhost:9005/": {}
-    TLS:
-      Insecure: false
+
    # yum install keep-balance
 
    
 
 
-Set @TLS.Insecure: true@ if your API server’s TLS certificate is not signed by a recognized CA.
+h3. Debian and Ubuntu
 
-h3. Start the service (option 1: systemd)
+
+
    # apt-get install keep-balance
+
    
+    
 
-If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
+h2(#start-service). Start the service
 
 If your system uses systemd, the keep-balance service should already be set up. Start it and check its status:
 
@@ -92,46 +87,3 @@ Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 skip
 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
 
    
     
-
-h3(#runit). Start the service (option 2: runit)
-
-Install runit to supervise the keep-balance daemon.  {% include 'install_runit' %}
-
-Create a supervised service.
-
-
-
    ~$ sudo mkdir /etc/service/keep-balance
-~$ cd /etc/service/keep-balance
-~$ sudo mkdir log log/main
-~$ printf '#!/bin/sh\nexec keep-balance -commit-pulls -commit-trash 2>&1\n' | sudo tee run
-~$ printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run
-~$ sudo chmod +x run log/run
-~$ sudo sv exit .
-~$ cd -
-
    
-    
-
-Use @sv stat@ and check the log file to verify the service is running.
-
-
-
    ~$ sudo sv stat /etc/service/keep-balance
-run: /etc/service/keep-balance: (pid 12520) 2s; run: log: (pid 12519) 2s
-~$ tail /etc/service/keep-balance/log/main/current
-2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
-2017/02/14 18:56:01 Run: start
-2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
-2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
-
    
-    
-
-h2. Enable garbage collection
-
-Ensure your cluster configuration has @Collections.BlobTrash: true@ (this is the default).
-
-
-
    ~$ arvados-server config-dump | grep BlobTrash:
-      BlobTrash: true
-
    
-    
-
-If BlobTrash is false, unneeded blocks will be counted and logged by keep-balance, but they will not be deleted.
diff --git a/doc/install/install-keep-web.html.textile.liquid b/doc/install/install-keep-web.html.textile.liquid
index a8833f44da..f949d0a6c8 100644
--- a/doc/install/install-keep-web.html.textile.liquid
+++ b/doc/install/install-keep-web.html.textile.liquid
@@ -9,61 +9,104 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-The Keep-web server provides read/write HTTP (WebDAV) access to files stored in Keep. It serves public data to unauthenticated clients, and serves private data to clients that supply Arvados API tokens. It can be installed anywhere with access to Keep services, typically behind a web proxy that provides TLS support. See the "godoc page":http://godoc.org/github.com/curoverse/arvados/services/keep-web for more detail.
+# "Introduction":#introduction
+# "Configure DNS":#introduction
+# "Configure anonymous user token.yml":#update-config
+# "Update nginx configuration":#update-nginx
+# "Install keep-web package":#install-packages
+# "Start the service":#start-service
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
 
-By convention, we use the following hostnames for the Keep-web service:
+h2(#introduction). Introduction
 
-
-
    download.uuid_prefix.your.domain
-collections.uuid_prefix.your.domain
-*.collections.uuid_prefix.your.domain
-
    
-    
+The Keep-web server provides read/write HTTP (WebDAV) access to files stored in Keep.  This makes it easy to access files in Keep from a browser, or mount Keep as a network folder using WebDAV support in various operating systems. It serves public data to unauthenticated clients, and serves private data to clients that supply Arvados API tokens. It can be installed anywhere with access to Keep services, typically behind a web proxy that provides TLS support. See the "godoc page":http://godoc.org/github.com/curoverse/arvados/services/keep-web for more detail.
 
-The above hostnames should resolve from anywhere on the internet.
+h2(#dns). Configure DNS
 
-h2. Install Keep-web
+It is important to properly configure the keep-web service to so it does not open up cross-site-scripting (XSS) attacks.  A HTML file can be stored in collection.  If an attacker causes a victim to visit that HTML file through Workbench, it will be rendered by the browser.  If all collections are served at the same domain, the browser will consider collections as coming from the same origin and thus have access to the same browsing data (such as API token), enabling malicious Javascript in the HTML file to access Arvados as the victim.
 
-Typically Keep-web runs on the same host as Keepproxy.
+There are two approaches to mitigate this.
 
-On Debian-based systems:
+# The service can tell the browser that all files should go to download instead of in-browser preview, except in situations where an attacker is unlikely to be able to gain access to anything they didn't already have access to.
+# Each each collection served by @keep-web@ is served on its own virtual host.  This allows for file with executable content to be displayed in-browser securely.  The virtual host embeds the collection uuid or portable data hash in the hostname.  For example, a collection with uuid @xxxxx-4zz18-tci4vn4fa95w0zx@ could be served as @xxxxx-4zz18-tci4vn4fa95w0zx.collections.ClusterID.example.com@ .  The portable data hash @dd755dbc8d49a67f4fe7dc843e4f10a6+54@ could be served at @dd755dbc8d49a67f4fe7dc843e4f10a6-54.collections.ClusterID.example.com@ .  This requires "wildcard DNS record":https://en.wikipedia.org/wiki/Wildcard_DNS_record and "wildcard TLS certificate.":https://en.wikipedia.org/wiki/Wildcard_certificate
 
-
-
    ~$ sudo apt-get install keep-web
-
    
-    
+h3. Collections download URL
 
-On Red Hat-based systems:
+Downloads links will served from the the URL in @Services.WebDAVDownload.ExternalURL@ .  The collection uuid or PDH is put in the URL path.
 
-
-
    ~$ sudo yum install keep-web
-
    
-    
+If blank, serve links to WebDAV with @disposition=attachment@ query param.  Unlike preview links, browsers do not render attachments, so there is no risk of XSS.
+
+If @WebDAVDownload@ is blank, and @WebDAV@ has a single origin (not wildcard, see below), then Workbench will show an error page
+
+
    +    Services:
+      WebDAVDownload:
+        ExternalURL: https://download.ClusterID.example.com
+
    
+
+h3. Collections preview URL
+
+Collections will be served using the URL pattern in @Services.WebDAV.ExternalURL@ .  If blank, use @Services.WebDAVDownload.ExternalURL@ instead, and disable inline preview.  If both are empty, downloading collections from workbench will be impossible.
+
+h4. In their own subdomain
 
-Verify that @Keep-web@ is functional:
+Collections can be served from their own subdomain:
+
+
    +    Services:
+      WebDAV:
+        ExternalURL: https://*.collections.ClusterID.example.com
+
    
+
+h4. Under the main domain
+
+Alternately, they can go under the main domain by including @--@:
+
+
    +    Services:
+      WebDAV:
+        ExternalURL: https://*--collections.ClusterID.example.com
+
    
+
+h4. From a single domain
+
+Serve preview links from a single domain, setting uuid or pdh in the path (similar to downloads).  This configuration only allows previews of public data or collection-sharing links, because these use the anonymous user token or the token is already embedded in the URL.  Authenticated requests will always result in file downloads from @Services.WebDAVDownload.ExternalURL@.
+
+
    +    Services:
+      WebDAV:
+        ExternalURL: https://collections.ClusterID.example.com
+
    
+
+h2(#update-config). Configure anonymous user token
+
+{% assign railscmd = "bundle exec ./script/get_anonymous_user_token.rb --get" %}
+{% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %}
+If you intend to use Keep-web to serve public data to anonymous clients, configure it with an anonymous token. Use the following command on the API server to create an anonymous user token. {% include 'install_rails_command' %}
 
 
-
    ~$ keep-web -h
-Usage of keep-web:
-  -config file
-    	Site configuration file (default may be overridden by setting an ARVADOS_CONFIG environment variable) (default "/etc/arvados/config.yml")
-  -dump-config
-    	write current configuration to stdout and exit
-[...]
-  -version
-    	print version information and exit.
+
        Users:
+      AnonymousUserToken: "{{railsout}}"
 
    
 
 
-h3. Set up a reverse proxy with TLS support
+Set @Users.AnonymousUserToken: ""@ (empty string) or leave it out if you do not want to serve public data.
+
+h2. Set InternalURL
 
-The Keep-web service will be accessible from anywhere on the internet, so we recommend using TLS for transport encryption.
+
    +    Services:
+      WebDAV:
+        InternalURL:
+	  "http://collections.ClusterID.example.com:9002": {}
+
    
 
-This is best achieved by putting a reverse proxy with TLS 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).
+h3. Update nginx configuration
 
-Note: A wildcard TLS 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 TLS certificate and DNS configured appropriately, all data can be served as web content.
+Put a reverse proxy with SSL support in front of keep-web.  Keep-web itself runs on the port 25107 (or whatever is specified in @Services.Keepproxy.InternalURL@) the reverse proxy runs on port 443 and forwards requests to Keepproxy.
 
-For example, using Nginx:
+Use a text editor to create a new file @/etc/nginx/conf.d/keep-web.conf@ with the following configuration. Options that need attention are marked with “TODO”.
 
 
     upstream keep-web {
@@ -71,18 +114,18 @@ upstream keep-web {
 }
 
 server {
-  listen                [your public IP address]:443 ssl;
-  server_name           download.uuid_prefix.your.domain
-                        collections.uuid_prefix.your.domain
-                        *.collections.uuid_prefix.your.domain
-                        ~.*--collections.uuid_prefix.your.domain;
+  listen                [TODO: your public IP address]:443 ssl;
+  server_name           download.ClusterID.example.com
+                        collections.ClusterID.example.com
+                        *.collections.ClusterID.example.com
+                        ~.*--collections.ClusterID.example.com;
 
   proxy_connect_timeout 90s;
   proxy_read_timeout    300s;
 
   ssl                   on;
-  ssl_certificate       YOUR/PATH/TO/cert.pem;
-  ssl_certificate_key   YOUR/PATH/TO/cert.key;
+  ssl_certificate       /TODO/YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key   /TODO/YOUR/PATH/TO/cert.key;
 
   location / {
     proxy_pass          http://keep-web;
@@ -97,93 +140,38 @@ server {
 
    
 
 {% include 'notebox_begin' %}
-If you restrict access to your Arvados services based on network topology -- for example, your proxy server is not reachable from the public internet -- additional proxy configuration might be needed to thwart cross-site scripting attacks that would circumvent your restrictions. Read the "'Intranet mode' section of the Keep-web documentation":https://godoc.org/github.com/curoverse/arvados/services/keep-web#hdr-Intranet_mode now.
-{% include 'notebox_end' %}
-
-h3(#dns). Configure DNS
-
-Configure your DNS servers so the following names resolve to your Nginx proxy's public IP address.
-* @download.uuid_prefix.your.domain@
-* @collections.uuid_prefix.your.domain@
-* @*--collections.uuid_prefix.your.domain@, if you have a wildcard TLS certificate valid for @*.uuid_prefix.your.domain@ and your DNS server allows this without interfering with other DNS names.
-* @*.collections.uuid_prefix.your.domain@, if you have a wildcard TLS certificate valid for these names.
-
-If neither of the above wildcard options is feasible, you have two choices:
-# Serve web content at @collections.uuid_prefix.your.domain@, but only for unauthenticated requests (public data and collection sharing links). Authenticated requests will always result in file downloads, using the @download@ name. For example, the Workbench "preview" button and the "view entire log file" link will invoke file downloads instead of displaying content in the browser window.
-# In the special case where you know you are immune to XSS exploits, you can enable the "trust all content" mode in Keep-web and Workbench (setting @Collections.TrustAllContent: true@ on the config file). With this enabled, inline web content can be served from a single @collections@ host name; no wildcard DNS or certificate is needed. Do not do this without understanding the security implications described in the "Keep-web documentation":http://godoc.org/github.com/curoverse/arvados/services/keep-web.
+If you restrict access to your Arvados services based on network topology -- for example, your proxy server is not reachable from the public internet -- additional proxy configuration might be needed to thwart cross-site scripting attacks that would circumvent your restrictions.
 
-h2. Configure Keep-web
-
-{% assign railscmd = "bundle exec ./script/get_anonymous_user_token.rb --get" %}
-{% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %}
-If you intend to use Keep-web to serve public data to anonymous clients, configure it with an anonymous token. You can use the same one you used when you set up your Keepproxy server, or use the following command on the API server to create another. {% include 'install_rails_command' %}
-
-Set the cluster config file like the following:
-
-
-
    Clusters:
-  uuid_prefix:
-    Services:
-      Controller:
-        ExternalURL: "https://uuid_prefix.your.domain"
-      WebDAV:
-        InternalURLs:
-          "http://keep_web_hostname_goes_here:9002/": {}
-        ExternalURL: "https://collections.uuid_prefix.your.domain"
-      WebDAVDownload:
-        InternalURLs:
-          "http://keep_web_hostname_goes_here:9002/": {}
-        ExternalURL: "https://download.uuid_prefix.your.domain"
-    Users:
-      AnonymousUserToken: "{{railsout}}"
-    Collections:
-      TrustAllContent: false
-    TLS:
-      Insecure: false
-
    
-    
+Normally, Keep-web accepts requests for multiple collections using the same host name, provided the client's credentials are not being used. This provides insufficient XSS protection in an installation where the "anonymously accessible" data is not truly public, but merely protected by network topology.
 
-Set @Users.AnonymousUserToken: ""@ (empty string) if you do not want to serve public data.
+In such cases -- for example, a site which is not reachable from the internet, where some data is world-readable from Arvados's perspective but is intended to be available only to users within the local network -- the downstream proxy should configured to return 401 for all paths beginning with "/c="
+{% include 'notebox_end' %}
 
-Set @TLS.Insecure: true@ if your API server's TLS certificate is not signed by a recognized CA.
+h2. Install Keep-web package
 
-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.
+Typically Keep-web runs on the same host as Keepproxy.
 
-The following entry on your cluster configuration file (@/etc/arvados/config.yml@) details the URL that will be used for file downloads.
+h3. Centos 7
 
 
-
    Clusters:
-  uuid_prefix:
-    Services:
-      WebDAVDownload:
-        ExternalURL: "https://download.uuid_prefix.your.domain"
+
    # yum install keep-web
 
    
 
 
-Additionally, one of the following entries on your cluster configuration file (depending on your DNS setup) tells Workbench which URL will be used to serve user content that can be displayed in the browser, like image previews and static HTML pages.
+h3. Debian and Ubuntu
 
 
-
    Clusters:
-  uuid_prefix:
-    Services:
-      WebDAV:
-        ExternalURL: "https://*--collections.uuid_prefix.your.domain"
-        ExternalURL: "https://*.collections.uuid_prefix.your.domain"
-        ExternalURL: "https://collections.uuid_prefix.your.domain"
+
    # apt-get install keep-web
 
    
 
 
-h2. Run Keep-web
-
-h3. Start the service (option 1: systemd)
-
-If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
+h2(#start-service). Start the service
 
 If your system uses systemd, the keep-web service should already be set up. Start it and check its status:
 
 
-
    ~$ sudo systemctl restart keep-web
-~$ sudo systemctl status keep-web
+
    # systemctl restart keep-web
+# systemctl status keep-web
 ● keep-web.service - Arvados Keep web gateway
    Loaded: loaded (/lib/systemd/system/keep-web.service; enabled)
    Active: active (running) since Sat 2019-08-10 10:33:21 UTC; 3 days ago
@@ -195,14 +183,27 @@ If your system uses systemd, the keep-web service should already be set up. Star
 
    
 
 
-h3(#runit). Start the service (option 2: runit)
-
-Install runit to supervise the Keep-web daemon.  {% include 'install_runit' %}
+h2(#restart-api). Restart the API server and controller
 
-The basic command to start Keep-web in the service run script is:
+After adding WebDAV to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 
 
-
    exec keep-web
+
    # systemctl restart nginx arvados-controller
 
    
 
 
+h2(#confirm-working). Confirm working installation
+
+Adjust for your configuration.
+
+
    +$ curl -H "Authorization: Bearer $system_root_token" https://download.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/_/hello.txt
+
    
+
+
    +$ curl -H "Authorization: Bearer $system_root_token" https://collections.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/_/hello.txt
+
    
+
+
    +$ curl -H "Authorization: Bearer $system_root_token" https://59389a8f9ee9d399be35462a0f92541c-53.collections.ClusterID.example.com/hello.txt
+
    
diff --git a/doc/install/install-keepproxy.html.textile.liquid b/doc/install/install-keepproxy.html.textile.liquid
index d3a60ad0f3..458ee9690a 100644
--- a/doc/install/install-keepproxy.html.textile.liquid
+++ b/doc/install/install-keepproxy.html.textile.liquid
@@ -9,8 +9,18 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+# "Introduction":#introduction
+# "Update config.yml":#update-config
+# "Update nginx configuration":#update-nginx
+# "Install keepproxy package":#install-packages
+# "Start the service":#start-service
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
+
+h2(#introduction). Introduction
+
 The Keepproxy server is a gateway into your Keep storage. Unlike the Keepstore servers, which are only accessible on the local LAN, Keepproxy is suitable for clients located elsewhere on the internet. Specifically, in contrast to Keepstore:
-* A client writing through Keepproxy generates less network traffic: the client sends a single copy of a data block, and Keepproxy sends copies to the appropriate Keepstore servers.
+* A client writing through Keepproxy sends a single copy of a data block, and Keepproxy distributes copies to the appropriate Keepstore servers.
 * A client can write through Keepproxy without precomputing content hashes. Notably, the browser-based upload feature in Workbench requires Keepproxy.
 * Keepproxy checks API token validity before processing requests. (Clients that can connect directly to Keepstore can use it as scratch space even without a valid API token.)
 
@@ -18,72 +28,38 @@ By convention, we use the following hostname for the Keepproxy server:
 
 
    
 table(table table-bordered table-condensed).
-|_Hostname_|
+|_. Hostname|
 |keep.@uuid_prefix@.your.domain|
 
    
 
 This hostname should resolve from anywhere on the internet.
 
-h2. Install Keepproxy
-
-On Debian-based systems:
-
-
-
    ~$ sudo apt-get install keepproxy
-
    
-    
-
-On Red Hat-based systems:
-
-
-
    ~$ sudo yum install keepproxy
-
    
-    
-
-Verify that Keepproxy is functional:
-
-
-
    ~$ keepproxy -h
-Usage of keepproxy:
-  -config file
-    	Site configuration file (default may be overridden by setting an ARVADOS_CONFIG environment variable) (default "/etc/arvados/config.yml")
-  -dump-config
-    	write current configuration to stdout and exit
-[...]
-  -version
-    	print version information and exit.
-
    
-    
-
-h3. Update the cluster config
+h2(#update-config). Update config.yml
 
-Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Keepproxy.ExternalURL@ and @Services.Keepproxy.InternalURLs@.  Replace @uuid_prefix@ with your cluster id.
+Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Keepproxy.ExternalURL@ and @Services.Keepproxy.InternalURLs@.
 
 
-
    Clusters:
-  uuid_prefix:
-    Services:
+
        Services:
       Keepproxy:
-        ExternalURL: https://keep.uuid_prefix.your.domain
+        ExternalURL: https://keep.ClusterID.example.com
         InternalURLs:
-	  "http://localhost:25107": {}
+	  "http://keep.ClusterID.example.com:25107": {}
 
    
 
 
-h3. Set up a reverse proxy with SSL support
+h2(#update-nginx). Update Nginx configuration
 
-Because the Keepproxy is intended for access from anywhere on the internet, it is recommended to use SSL for transport encryption.
+Put a reverse proxy with SSL support in front of Keepproxy. Keepproxy itself runs on the port 25107 (or whatever is specified in @Services.Keepproxy.InternalURL@) the reverse proxy runs on port 443 and forwards requests to Keepproxy.
 
-This is best achieved by putting a reverse proxy with SSL support in front of Keepproxy. Keepproxy itself runs on port 25107 by default; your reverse proxy can run on port 443 and pass requests to Keepproxy on port 25107.
+Use a text editor to create a new file @/etc/nginx/conf.d/keepproxy.conf@ with the following configuration. Options that need attention are marked with “TODO”.
 
-
    -upstream keepproxy {
+
    upstream keepproxy {
   server                127.0.0.1:25107;
 }
 
 server {
-  listen                  [your public IP address]:443 ssl;
-  server_name             keep.uuid_prefix.your.domain;
+  listen                  [TODO your public IP address]:443 ssl;
+  server_name             keep.ClusterID.example.com;
 
   proxy_connect_timeout   90s;
   proxy_read_timeout      300s;
@@ -91,9 +67,9 @@ server {
   proxy_http_version      1.1;
   proxy_request_buffering off;
 
-  ssl                     on;
-  ssl_certificate         /etc/nginx/keep.uuid_prefix.your.domain-ssl.crt;
-  ssl_certificate_key     /etc/nginx/keep.uuid_prefix.your.domain-ssl.key;
+  ssl on;
+  ssl_certificate     /TODO/YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key /TODO/YOUR/PATH/TO/cert.key;
 
   # Clients need to be able to upload blocks of data up to 64MiB in size.
   client_max_body_size    64m;
@@ -102,49 +78,35 @@ server {
     proxy_pass            http://keepproxy;
   }
 }
-
    
+
    
 
 Note: if the Web uploader is failing to upload data and there are no logs from keepproxy, be sure to check the nginx proxy logs.  In addition to "GET" and "PUT", The nginx proxy must pass "OPTIONS" requests to keepproxy, which should respond with appropriate Cross-origin resource sharing headers.  If the CORS headers are not present, brower security policy will cause the upload request to silently fail.  The CORS headers are generated by keepproxy and should not be set in nginx.
 
-h3. Tell the API server about the Keepproxy server
-
-The API server needs to be informed about the presence of your Keepproxy server.
-
-First, if you don't already have an admin token, create a superuser token.
+h2(#install-packages). Install Keepproxy package
 
-{% include 'create_superuser_token' %}
+h3. Centos 7
 
-Configure your environment to run @arv@ using the output of create_superuser_token.rb:
+
+
    # yum install keepproxy
+
    
+    
 
-
    -export ARVADOS_API_HOST=zzzzz.example.com
-export ARVADOS_API_TOKEN=zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-
    
+h3. Debian and Ubuntu
 
 
-
    ~$ uuid_prefix=`arv --format=uuid user current | cut -d- -f1`
-~$ echo "Site prefix is '$uuid_prefix'"
-~$ read -rd $'\000' keepservice <<EOF; arv keep_service create --keep-service "$keepservice"
-{
- "service_host":"keep.$uuid_prefix.your.domain",
- "service_port":443,
- "service_ssl_flag":true,
- "service_type":"proxy"
-}
-EOF
-
    
-
-h2. Run Keepproxy
+
    # apt-get install keepproxy
+
    
+
 
-h3. Start the service (option 1: systemd)
+h2(#start-service). Start the service
 
 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
 
 If your system uses systemd, the keepproxy service should already be set up. Start it and check its status:
 
 
-
    ~$ sudo systemctl restart keepproxy
-~$ sudo systemctl status keepproxy
+
    # systemctl restart keepproxy
+# systemctl status keepproxy
 ● keepproxy.service - Arvados Keep Proxy
    Loaded: loaded (/lib/systemd/system/keepproxy.service; enabled)
    Active: active (running) since Tue 2019-07-23 09:33:47 EDT; 3 weeks 1 days ago
@@ -156,13 +118,18 @@ If your system uses systemd, the keepproxy service should already be set up. Sta
 
    
 
 
-h3(#runit). Start the service (option 2: runit)
+h2(#restart-api). Restart the API server and controller
 
-Install runit to supervise the Keep-web daemon.  {% include 'install_runit' %}
+After adding keeproxy to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
+
+
+
    # systemctl restart nginx arvados-controller
+
    
+    
 
-h3. Testing keepproxy
+h2(#confirm-working). Confirm working installation
 
-Log into a host that is on an external network from your private Arvados network.  The host should be able to contact your keepproxy server (eg keep.$uuid_prefix.arvadosapi.com), but not your keepstore servers (eg keep[0-9].$uuid_prefix.arvadosapi.com).
+Log into a host that is on a network external to your private Arvados network.  The host should be able to contact your keepproxy server (eg @keep.ClusterID.example.com@), but not your keepstore servers (eg keep[0-9].ClusterID.example.com).
 
 Install the "Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html
 
diff --git a/doc/install/install-keepstore.html.textile.liquid b/doc/install/install-keepstore.html.textile.liquid
index 71c1cb639e..70c69c761d 100644
--- a/doc/install/install-keepstore.html.textile.liquid
+++ b/doc/install/install-keepstore.html.textile.liquid
@@ -9,6 +9,14 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+# "Introduction":#introduction
+# "Update config.yml":#update-config
+# "Install keepstore package":#install-packages
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
+
+h2. Introduction
+
 Keepstore provides access to underlying storage for reading and writing content-addressed blocks, with enforcement of Arvados permissions.  Keepstore supports a variety of cloud object storage and POSIX filesystems for its backing store.
 
 h3. Plan your storage layout
@@ -26,121 +34,66 @@ By convention, we use the following hostname pattern:
 
 
    
 table(table table-bordered table-condensed).
-|_Hostname_|
-|keep0.@uuid_prefix@.your.domain|
-|keep1.@uuid_prefix@.your.domain|
+|_. Hostname|
+|keep0.@ClusterID@.example.com|
+|keep1.@ClusterID@.example.com|
 
    
 
 Keepstore servers should not be directly accessible from the Internet (they are accessed via "keepproxy":install-keepproxy.html), so the hostnames only need to resolve on the private network.
 
-h2. Install Keepstore
-
-On Debian-based systems:
-
-
-
    ~$ sudo apt-get install keepstore
-
    
-    
-
-On Red Hat-based systems:
-
-
-
    ~$ sudo yum install keepstore
-
    
-    
-
-Verify that Keepstore is functional:
-
-
-
    ~$ keepstore --version
-
    
-    
+h2(#update-config). Update cluster config
 
-h3. Create a superuser token
+h3. Configure storage volumes
 
-If you haven't already done so, create a superuser token.
+Fill in the @Volumes@ section of @config.yml@ for each storage volume.  Available storage volume types include POSIX filesystems and cloud object storage.  It is possible to have different volume types in the same cluster.
 
-{% include 'create_superuser_token' %}
+* To use a POSIX filesystem, including both local filesystems (ext4, xfs) and network file system such as GPFS or Lustre, follow the setup instructions on "Filesystem storage":configure-fs-storage.html
+* If you are using S3-compatible object storage (including Amazon S3, Google Cloud Storage, and Ceph RADOS), follow the setup instructions on "S3 Object Storage":configure-s3-object-storage.html
+* If you are using Azure Blob Storage, follow the setup instructions on "Azure Blob Storage":configure-azure-blob-storage.html
 
-h3. Update cluster config file
+h3. List services
 
-Add or update the following sections of @/etc/arvados/config.yml@ as needed. Refer to the examples and comments in the "default config.yml file":{{site.baseurl}}/admin/config.html for more information.
+Add each keepstore server to the @Services.Keepstore@ section of @/etc/arvados/config.yml@ .
 
 
-
    Clusters:
-  uuid_prefix:
-    SystemRootToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-    Services:
+
        Services:
       Keepstore:
+        # No ExternalURL because they are only accessed by the internal subnet.
         InternalURLs:
-          "http://keep0.uuid_prefix.example.com:25107/": {}
-    API:
-      MaxKeepBlobBuffers: 128
+          "http://keep0.ClusterID.example.com:25107/": {}
+          "http://keep1.ClusterID.example.com:25107/": {}
+	  # and so forth
 
    
 
 
-h3. Note on storage management
+h2(#install-packages). Install keepstore package
 
-On its own, a keepstore server never deletes data. Instead, the keep-balance service determines which blocks are candidates for deletion and instructs the keepstore to move those blocks to the trash. Please see the "Balancing Keep servers":{{site.baseurl}}/admin/keep-balance.html for more details.
+On each host that will run keepstore, install the @keepstore@ package.
 
-h3. Configure storage volumes
-
-Available storage volume types include POSIX filesystems and cloud object storage.
-
-* To use a POSIX filesystem, including both local filesystems (ext4, xfs) and network file system such as GPFS or Lustre, follow the setup instructions on "Filesystem storage":configure-fs-storage.html
-* If you are using S3-compatible object storage (including Amazon S3, Google Cloud Storage, and Ceph RADOS), follow the setup instructions on "S3 Object Storage":configure-s3-object-storage.html
-* If you are using Azure Blob Storage, follow the setup instructions on "Azure Blob Storage":configure-azure-blob-storage.html
-
-h2. Run keepstore as a supervised service
-
-h3. Start the service (option 1: systemd)
-
-If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
-
-If your system uses systemd, the keepstore service should already be set up. Restart it to read the updated configuration, and check its status:
+h3. Centos 7
 
 
-
    ~$ sudo systemctl restart keepstore
-~$ sudo systemctl status keepstore
-● keepstore.service - Arvados Keep Storage Daemon
-   Loaded: loaded (/etc/systemd/system/keepstore.service; enabled; vendor preset: enabled)
-   Active: active (running) since Tue 2019-09-10 14:16:29 UTC; 1s ago
-     Docs: https://doc.arvados.org/
- Main PID: 25465 (keepstore)
-    Tasks: 9 (limit: 4915)
-   CGroup: /system.slice/keepstore.service
-           └─25465 /usr/bin/keepstore
-[...]
+
    # yum install keepstore
 
    
 
 
-h3(#runit). Start the service (option 2: runit)
-
-Install runit to supervise the keepstore daemon.  {% include 'install_runit' %}
-
-Install this script as the run script @/etc/sv/keepstore/run@ for the keepstore service:
+h3. Debian and Ubuntu
 
 
-
    #!/bin/sh
-
-exec 2>&1
-GOGC=10 exec keepstore
+
    # apt-get install keepstore
 
    
 
 
-h2. Set up additional servers
-
-Repeat the above sections to prepare volumes and bring up supervised services on each Keepstore server you are setting up.
-
-h2. Restart the API server and controller
+h2(#restart-api). Restart the API server and controller
 
 After adding all of your keepstore servers to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 
-
    -sudo systemctl restart nginx arvados-controller
-
    
+
+
    # systemctl restart nginx arvados-controller
+
    
+    
 
-h2(#testing). Testing keep
+h2(#confirm-working). Confirm working installation
 
 Install the "Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html
 
@@ -161,3 +114,7 @@ $ arv-put --portable-data-hash hello.txt
 $ arv-get 59389a8f9ee9d399be35462a0f92541c+53/hello.txt
 hello world!
 
    
+
+h3. Note on storage management
+
+On its own, a keepstore server never deletes data. Instead, the keep-balance service determines which blocks are candidates for deletion and instructs the keepstore to move those blocks to the trash. Please see the "Balancing Keep servers":{{site.baseurl}}/admin/keep-balance.html for more details.
diff --git a/doc/install/install-manual-prerequisites.html.textile.liquid b/doc/install/install-manual-prerequisites.html.textile.liquid
index 7e72990bfc..36298b832f 100644
--- a/doc/install/install-manual-prerequisites.html.textile.liquid
+++ b/doc/install/install-manual-prerequisites.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: installguide
-title: Prerequisites
+title: Planning and prerequisites
 ...
 {% comment %}
 Copyright (C) The Arvados Authors. All rights reserved.
@@ -9,28 +9,20 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-h2. Supported Cloud and HPC platforms
+Before attempting installation, you should begin by reviewing supported platforms, choosing backends for identity, storage, and scheduling, and decide how you will distribute Arvados services onto machines.  You should also choose an Arvados Cluster ID, choose your hostnames, and aquire TLS certificates.  It may be helpful to make notes as you go along.
 
-Arvados can run in a variety of configurations.  For compute scheduling, Arvados supports HPC clusters using @slurm@, and supports elastic cloud computing on AWS, Google and Azure.  For storage, Arvados can store blocks on regular file systems such as ext4 or xfs, on network file systems such as GPFS, or object storage such as Azure blob storage, Amazon S3, and other object storage that supports the S3 API including Google Cloud Storage and Ceph.
+The Arvados storage subsystem is called "keep".  The compute subsystem is called "crunch".
 
-h2. Hardware (or virtual machines)
+# "Supported GNU/Linux distributions":#supportedlinux
+# "Choosing which components to install":#components
+# "Identity provider":#identity
+# "Storage backend (Keep)":#storage
+# "Container compute scheduler (Crunch)":#scheduler
+# "Hardware or virtual machines":#machines
+# "Arvados Cluster ID":#clusterid
+# "DNS and TLS":#dnstls
 
-This guide assumes you have seven systems available in the same network subnet:
-
-
    
-table(table table-bordered table-condensed).
-|_. Function|_. Number of nodes|
-|Arvados API, Crunch dispatcher, Git, Websockets and Workbench|1|
-|Arvados Compute node|1|
-|Arvados Keepproxy and Keep-web server|1|
-|Arvados Keepstore servers|2|
-|Arvados Shell server|1|
-|Arvados SSO server|1|
-
    
-
-The number of Keepstore, shell and compute nodes listed above is a minimum. In a real production installation, you will likely run many more of each of those types of nodes. In such a scenario, you would probably also want to dedicate a node to the Workbench server and Crunch dispatcher, respectively. For performance reasons, you may want to run the database server on a separate node as well.
-
-h2. Supported GNU/Linux distributions
+h2(#supportedlinux). Supported GNU/Linux distributions
 
 table(table table-bordered table-condensed).
 |_. Distribution|_. State|_. Last supported version|
@@ -47,100 +39,119 @@ table(table table-bordered table-condensed).
 
 Arvados packages are published for current Debian releases (until the EOL date), current Ubuntu LTS releases (until the end of standard support), and the latest version of CentOS.
 
-h2(#repos). Arvados package repositories
-
-On any host where you install Arvados software, you'll need to set up an Arvados package repository.  They're available for several popular distributions.
-
-h3. CentOS
+h2(#components). Choosing which components to install
 
-Packages are available for CentOS 7. To install them with yum, save this configuration block in @/etc/yum.repos.d/arvados.repo@:
+Arvados consists of many components, some of which may be omitted (at the cost of reduced functionality.)  It may also be helpful to review the "Arvados Architecture":{{site.baseurl}}/architecture to understand how these components interact.
 
-
-
    [arvados]
-name=Arvados
-baseurl=http://rpm.arvados.org/CentOS/$releasever/os/$basearch/
-gpgcheck=1
-gpgkey=http://rpm.arvados.org/CentOS/RPM-GPG-KEY-curoverse
-
    
-    
+table(table table-bordered table-condensed).
+|\3=. *Core*|
+|"Postgres database":install-postgresql.html |Stores data for the API server.|Required.|
+|"API server":install-api-server.html |Core Arvados logic for managing users, groups, collections, containers, and enforcing permissions.|Required.|
+|\3=. *Keep (storage)*|
+|"Keepstore":install-keepstore.html |Stores content-addressed blocks in a variety of backends (local filesystem, cloud object storage).|Required.|
+|"Keepproxy":install-keepproxy.html |Gateway service to access keep servers from external networks.|Required to be able to use arv-put, arv-get, or arv-mount outside the private Arvados network.|
+|"Keep-web":install-keep-web.html |Gateway service providing read/write HTTP and WebDAV support on top of Keep.|Required to access files from Workbench.|
+|"Keep-balance":install-keep-balance.html |Storage cluster maintenance daemon responsible for moving blocks to their optimal server location, adjusting block replication levels, and trashing unreferenced blocks.|Required to free deleted data from underlying storage, and to ensure proper replication and block distribution (including support for storage classes).|
+|\3=. *User interface*|
+|"Single Sign On server":install-sso.html |Web based login to Workbench.|Depends on identity provider.  Not required for Google.  Required for LDAP or standalone database.|
+|"Workbench":install-workbench-app.html, "Workbench2":install-workbench2-app.html |Primary graphical user interface for working with file collections and running containers.|Optional.  Depends on API server, SSO server, keep-web, websockets server.|
+|"Workflow Composer":install-composer.html |Graphical user interface for editing Common Workflow Language workflows.|Optional.  Depends on git server (arv-git-httpd).|
+|\3=. *Additional services*|
+|"Websockets server":install-ws.html |Event distribution server.|Required to view streaming container logs in Workbench.|
+|"Shell server":install-shell-server.html |Synchronize (create/delete/configure) Unix shell accounts with Arvados users.|Optional.|
+|"Git server":install-arv-git-httpd.html |Arvados-hosted git repositories, with Arvados-token based authentication.|Optional, but required by Workflow Composer.|
+|\3=. *Crunch (running containers)*|
+|"crunch-dispatch-slurm":crunch2-slurm/install-prerequisites.html |Run analysis workflows using Docker containers distributed across a SLURM cluster.|Optional if you wish to use Arvados for data management only.|
+|"Node Manager":install-nodemanager.html |Allocate and free cloud VM instances on demand based on workload.|Optional, not needed for a static SLURM cluster (such as on-premise HPC).|
 
-{% include 'install_redhat_key' %}
+h2(#identity). Identity provider
 
-h3. Debian and Ubuntu
+Choose which backend you will use to authenticate users.
 
-Packages are available for Debian 9 ("stretch"), Ubuntu 16.04 ("xenial") and Ubuntu 18.04 ("bionic").
+* Google login to authenticate users with a Google account.  Note: if you only use Google, you can use @arvados-controller@ support for Google login, and do not need to install the Arvados Single Sign-On server (SSO).
+* LDAP login to authenticate users using the LDAP protocol, supported by many services such as OpenLDAP and Active Directory.  Supports username/password authentication.
+* Standalone SSO server user database.  Supports username/password authentication.  Supports new user sign-up.
 
-First, register the Curoverse signing key in apt's database:
+h2(#storage). Storage backend
 
-{% include 'install_debian_key' %}
+Choose which backend you will use for storing and retrieving content-addressed Keep blocks.
 
-Configure apt to retrieve packages from the Arvados package repository. This command depends on your OS vendor and version:
+* File systems storage, such as ext4 or xfs, or network file systems such as GPFS or Lustre
+* Amazon S3, or other object storage that supports the S3 API including Google Cloud Storage and Ceph.
+* Azure blob storage
 
-table(table table-bordered table-condensed).
-|_. OS version|_. Command|
-|Debian 9 ("stretch")|echo "deb http://apt.arvados.org/ stretch main" | sudo tee /etc/apt/sources.list.d/arvados.list|
-|Ubuntu 16.04 ("xenial")[1]|echo "deb http://apt.arvados.org/ xenial main" | sudo tee /etc/apt/sources.list.d/arvados.list|
-|Ubuntu 18.04 ("bionic")[1]|echo "deb http://apt.arvados.org/ bionic main" | sudo tee /etc/apt/sources.list.d/arvados.list|
+You should also determine the desired replication factor for your data.  A replication factor of 1 means only a single copy of a given data block is kept.  With a conventional file system backend and a replication factor of 1, a hard drive failure is likely to lose data.  For this reason the default replication factor is 2 (two copies are kept).
 
-{% include 'notebox_begin' %}
+A backend may have its own replication factor (such as durability guarantees of cloud buckets) and Arvados will take this into account when writing a new data block.
 
-fn1. Arvados packages for Ubuntu may depend on third-party packages in Ubuntu's "universe" repository.  If you're installing on Ubuntu, make sure you have the universe sources uncommented in @/etc/apt/sources.list@.
+h2(#scheduler). Container compute scheduler
 
-{% include 'notebox_end' %}
+Choose which backend you will use to schedule computation.
 
-Retrieve the package list:
+* On AWS EC2 and Azure, you probably want to use @crunch-dispatch-cloud@ to manage the full lifecycle of cloud compute nodes: starting up nodes sized to the container request, executing containers on those nodes, and shutting nodes down when no longer needed.
+* For on-premise HPC clusters using "slurm":https://slurm.schedmd.com/ use @crunch-dispatch-slurm@ to execute containers with slurm job submissions.
+* For single node demos, use @crunch-dispatch-local@ to execute containers directly.
 
-
-
    ~$ sudo apt-get update
-
    
-    
+h2(#machines). Hardware (or virtual machines)
 
-h2. A unique identifier
+Choose how to allocate Arvados services to machines.  We recommend that each machine start with a clean installation of your preferred Linux distribution.
 
-Each Arvados installation should have a globally unique identifier, which is a unique 5-character lowercase alphanumeric string. For testing purposes, here is one way to make a random 5-character string:
+For a production installation, this is a reasonable configuration:
 
-
-
    ~$ tr -dc 0-9a-z </dev/urandom | head -c5; echo
-
    
-    
-
-You may also use a different method to pick the unique identifier. The unique identifier will be part of the hostname of the services in your Arvados cluster. The rest of this documentation will refer to it as your @uuid_prefix@.
-
-
-h2. SSL certificates
+
    
+table(table table-bordered table-condensed).
+|_. Function|_. Number of nodes|_. Recommended specs|
+|Postgres database, Arvados API server, Arvados controller, Git, Websockets|1|16+ GiB RAM, 4+ cores, fast disk for database|
+|Single Sign-On (SSO) server ^1^|1|2 GiB RAM|
+|Workbench, Keepproxy, Keep-web, Keep-balance|1|8 GiB RAM, 2+ cores|
+|Keepstore servers ^2^|2+|4 GiB RAM|
+|Compute scheduler|1|2 GiB RAM|
+|Compute worker nodes ^2^|2+ |Depends on workload|
+|User shell nodes ^3^|0+|Depends on workload|
+
    
 
-There are six public-facing services that require an SSL certificate. If you do not have official SSL certificates, you can use self-signed certificates.
+^1^ May be omitted when using Google login support in @arvados-controller@
+^2^ Should be scaled up as needed
+^3^ Refers to shell nodes managed by Arvados, that provide ssh access for users to interact with Arvados at the command line.  Optional.
 
 {% include 'notebox_begin' %}
+For a small demo installation, it is possible to run all the Arvados services on a single node.  Special considerations for single-node installs will be noted in boxes like this.
+{% include 'notebox_end' %}
 
-Most Arvados clients and services will accept self-signed certificates when the @ARVADOS_API_HOST_INSECURE@ environment variable is set to @true@.  However, web browsers generally do not make it easy for users to accept self-signed certificates from Web sites.
+h2(#clusterid). Arvados Cluster ID
 
-Users who log in through Workbench will visit at least three sites: the SSO server, the API server, and Workbench itself.  When a browser visits each of these sites, it will warn the user if the site uses a self-signed certificate, and the user must accept it before continuing.  This procedure usually only needs to be done once in a browser.
+Each Arvados installation should have a cluster identifier, which is a unique 5-character lowercase alphanumeric string.   Here is one way to make a random 5-character string:
 
-After that's done, Workbench includes JavaScript clients for other Arvados services.  Users are usually not warned if these client connections are refused because the server uses a self-signed certificate, and it is especially difficult to accept those cerficiates:
+
+
    ~$ tr -dc 0-9a-z </dev/urandom | head -c5; echo
+
    
+    
 
-* JavaScript connects to the Websockets server to provide incremental page updates and view logs from running jobs.
-* JavaScript connects to the API and Keepproxy servers to upload local files to collections.
-* JavaScript connects to the Keep-web server to download log files.
+You may also use a different method to pick the cluster identifier. The cluster identifier will be part of the hostname of the services in your Arvados cluster. The rest of this documentation will refer to it as your @ClusterID@.  Whenever @ClusterID@ appears in a configuration example, replace it with your five-character cluster identifier.
 
-In sum, Workbench will be much less pleasant to use in a cluster that uses self-signed certificates.  You should avoid using self-signed certificates unless you plan to deploy a cluster without Workbench; you are deploying only to evaluate Arvados as an individual system administrator; or you can push configuration to users' browsers to trust your self-signed certificates.
+h2(#dnstls). DNS entries and TLS certificates
 
-{% include 'notebox_end' %}
+The following services are normally public-facing and require DNS entries and corresponding TLS certificates.  Get certificates from your preferred TLS certificate provider.  We recommend using "Let's Encrypt":https://letsencrypt.org/ .  You can run several services on same node, but each distinct hostname requires its own TLS certificate.
 
-By convention, we use the following hostname pattern:
+This guide uses the following hostname conventions.  A later part of this guide will describe how to set up Nginx virtual hosts.
 
 
    
 table(table table-bordered table-condensed).
 |_. Function|_. Hostname|
-|Arvados API|@uuid_prefix@.your.domain|
-|Arvados Git server|git.@uuid_prefix@.your.domain|
-|Arvados Keepproxy server|keep.@uuid_prefix@.your.domain|
-|Arvados Keep-web server|download.@uuid_prefix@.your.domain
+|Arvados API|@ClusterID@.example.com|
+|Arvados Git server|git.@ClusterID@.example.com|
+|Arvados Websockets endpoint|ws.@ClusterID@.example.com|
+|Arvados SSO Server|auth.example.com|
+|Arvados Workbench|workbench.@ClusterID@.example.com|
+|Arvados Workbench 2|workbench2.@ClusterID@.example.com|
+|Arvados Keepproxy server|keep.@ClusterID@.example.com|
+|Arvados Keep-web server|download.@ClusterID@.example.com
 _and_
-*.collections.@uuid_prefix@.your.domain or
-*--collections.@uuid_prefix@.your.domain or
-collections.@uuid_prefix@.your.domain (see the "keep-web install docs":install-keep-web.html)|
-|Arvados SSO Server|auth.your.domain|
-|Arvados Websockets endpoint|ws.@uuid_prefix@.your.domain|
-|Arvados Workbench|workbench.@uuid_prefix@.your.domain|
+*.collections.@ClusterID@.example.com or
+*--collections.@ClusterID@.example.com or
+collections.@ClusterID@.example.com (see the "keep-web install docs":install-keep-web.html)|
 
    
+
+{% include 'notebox_begin' %}
+It is also possible to create your own certificate authority, issue server certificates, and install a custom root certificate in the browser.  This is out of scope for this guide.
+{% include 'notebox_end' %}
diff --git a/doc/install/install-postgresql.html.textile.liquid b/doc/install/install-postgresql.html.textile.liquid
index 7324bb30ff..d7bf4c2d2d 100644
--- a/doc/install/install-postgresql.html.textile.liquid
+++ b/doc/install/install-postgresql.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: installguide
-title: Set up PostgreSQL databases
+title: Install PostgreSQL 9.4+
 ...
 {% comment %}
 Copyright (C) The Arvados Authors. All rights reserved.
@@ -9,35 +9,26 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-Two Arvados Rails servers store data in a PostgreSQL database: the SSO server, and the API server.  The API server requires at least version *9.4* of PostgreSQL.  Beyond that, you have the flexibility to deploy PostgreSQL any way that the Rails servers will be able to connect to it.  Our recommended deployment strategy is:
+Arvados requires at least version *9.4* of PostgreSQL.
 
-* Install PostgreSQL on the same host as the SSO server, and dedicate that install to hosting the SSO database.  This provides the best security for the SSO server, because the database does not have to accept any client connections over the network.  Typical load on the SSO server is light enough that deploying both it and its database on the same host does not compromise performance.
-* If you want to provide the most scalability for your Arvados cluster, install PostgreSQL for the API server on a dedicated host.  This gives you the most flexibility to avoid resource contention, and tune performance separately for the API server and its database.  If performance is less of a concern for your installation, you can install PostgreSQL on the API server host directly, as with the SSO server.
-
-Find the section for your distribution below, and follow it to install PostgreSQL on each host where you will deploy it.  Then follow the steps in the later section(s) to set up PostgreSQL for the Arvados service(s) that need it.
-
-It is important to make sure that autovacuum is enabled for the PostgreSQL database that backs the API server. Autovacuum is enabled by default since PostgreSQL 8.3.
-
-h2. Install PostgreSQL 9.4+
-
-The API server requires at least version *9.4* of PostgreSQL.
+* "CentOS 7":#centos7
+* "Debian or Ubuntu":#debian
 
 h3(#centos7). CentOS 7
 {% assign rh_version = "7" %}
 {% include 'note_python_sc' %}
 
-# Install PostgreSQL:
-  
    ~$ sudo yum install rh-postgresql95 rh-postgresql95-postgresql-contrib
+# Install PostgreSQL
+  
    # yum install rh-postgresql95 rh-postgresql95-postgresql-contrib
 ~$ scl enable rh-postgresql95 bash
    
-# Initialize the database:
-  
    ~$ sudo postgresql-setup initdb
    
-# Configure the database to accept password connections:
-  
    ~$ sudo sed -ri -e 's/^(host +all +all +(127\.0\.0\.1\/32|::1\/128) +)ident$/\1md5/' /var/lib/pgsql/data/pg_hba.conf
    
-# Configure the database to launch at boot:
-  
    ~$ sudo systemctl enable rh-postgresql95-postgresql
    
-# Start the database:
-  
    ~$ sudo systemctl start rh-postgresql95-postgresql
    
-# "Set up Arvados credentials and databases":#rails_setup for the services that will use this PostgreSQL install.
+# Initialize the database
+  
    # postgresql-setup initdb
    
+# Configure the database to accept password connections
+  
    # sed -ri -e 's/^(host +all +all +(127\.0\.0\.1\/32|::1\/128) +)ident$/\1md5/' /var/lib/pgsql/data/pg_hba.conf
    
+# Configure the database to launch at boot
+  
    # systemctl enable rh-postgresql95-postgresql
    
+# Start the database
+  
    # systemctl start rh-postgresql95-postgresql
    
 
 h3(#debian). Debian or Ubuntu
 
@@ -45,22 +36,9 @@ Debian 8 (Jessie) and Ubuntu 16.04 (Xenial) and later versions include a suffici
 
 Ubuntu 14.04 (Trusty) requires an updated PostgreSQL version, see "the PostgreSQL ubuntu repository":https://www.postgresql.org/download/linux/ubuntu/
 
-# Install PostgreSQL:
-  
    ~$ sudo apt-get install postgresql postgresql-contrib
    
-# "Set up Arvados credentials and databases":#rails_setup for the services that will use this PostgreSQL install.
-
-
-
-h2(#sso). Set up SSO server credentials and database
-
-{% assign service_role = "arvados_sso" %}
-{% assign service_database = "arvados_sso_production" %}
-{% assign use_contrib = false %}
-{% include 'install_postgres_database' %}
-
-h2(#api). Set up API server credentials and database
-
-{% assign service_role = "arvados" %}
-{% assign service_database = "arvados_production" %}
-{% assign use_contrib = true %}
-{% include 'install_postgres_database' %}
+# Install PostgreSQL
+  
    # apt-get --no-install-recommends install postgresql postgresql-contrib
    
+# Configure the database to launch at boot
+  
    # systemctl enable postgresql
    
+# Start PostgreSQL
+  
    # systemctl start postgresql
    
diff --git a/doc/install/install-shell-server.html.textile.liquid b/doc/install/install-shell-server.html.textile.liquid
index 1cbe749972..5b35aeb895 100644
--- a/doc/install/install-shell-server.html.textile.liquid
+++ b/doc/install/install-shell-server.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: installguide
-title: Install a shell server
+title: Install a shell node
 ...
 {% comment %}
 Copyright (C) The Arvados Authors. All rights reserved.
@@ -9,61 +9,14 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-There is nothing inherently special about an Arvados shell server. It is just a GNU/Linux machine with Arvados utilites and SDKs installed. For optimal performance, the Arvados shell server should be on the same LAN as the Arvados cluster, but that is not required.
+Arvados support for shell nodes enables using Arvados permissions to grant shell accounts to users.
 
-h2. Install API tokens
+A shell node runs the @arvados-login-sync@ service, and has some additional configuration to make it convenient for users to use Arvados utilites and SDKs.  Users are allowed to log in and run arbitrary programs.  For optimal performance, the Arvados shell server should be on the same LAN as the Arvados cluster.
 
-Please follow the "API token guide":../user/reference/api-tokens.html to get API tokens for your Arvados account and install them on your shell server. We will use those tokens to test the SDKs as we install them.
+h2. Install Dependecies and SDKs
 
-h2. Install the Ruby SDK and utilities
-
-First, install the curl development libraries necessary to build the Arvados Ruby SDK.  On Debian-based systems:
-
-
-
    ~$ sudo apt-get install libcurl4-openssl-dev
-
    
-    
-
-On Red Hat-based systems:
-
-
-
    ~$ sudo yum install libcurl-devel
-
    
-    
-
-Next, install the arvados-cli Ruby gem.  If you're using RVM:
-
-
-
    ~$ sudo /usr/local/rvm/bin/rvm-exec default gem install arvados-cli
-
    
-    
-
-If you're not using RVM:
-
-
-
    ~$ sudo -i gem install arvados-cli
-
    
-    
-
-h2. Install the Python SDK and utilities
-
-{% assign rh_version = "7" %}
-{% include 'note_python_sc' %}
-
-On Red Hat-based systems:
-
-
-
    ~$ echo 'exclude=python2-llfuse' | sudo tee -a /etc/yum.conf
-~$ sudo yum install python-arvados-python-client python-arvados-fuse crunchrunner
-
    
-    
-
-On Debian-based systems:
-
-
-
    ~$ sudo apt-get install python-arvados-python-client python-arvados-fuse crunchrunner
-
    
-    
+# "Install the CLI":{{site.baseurl}}/sdk/cli/install.html
+# "Install the R SDK":{{site.baseurl}}/sdk/R/index.html (optional)
 
 h2. Install Git and curl
 
@@ -80,7 +33,7 @@ Configure git to use the ARVADOS_API_TOKEN environment variable to authenticate
 
    
     
 
-h2. Install arvados-login-sync
+h2. Create database entry for VM
 
 This program makes it possible for Arvados users to log in to the shell server -- subject to permissions assigned by the Arvados administrator -- using the SSH keys they upload to Workbench. It sets up login accounts, updates group membership, and adds users' public keys to the appropriate @authorized_keys@ files.
 
@@ -93,7 +46,9 @@ zzzzz-2x53u-zzzzzzzzzzzzzzz    
 
    
     
 
-Create a token that is allowed to read login information for this VM.
+h2. Create token
+
+As an admin arvados user (such as the system root user), create a token that is allowed to read login information for this VM.
 
 
 
    @@ -108,62 +63,21 @@ Create a token that is allowed to read login information for this VM.
 
 Note the UUID and the API token output by the above commands: you will need them in a minute.
 
-Install the arvados-login-sync program.
-
-If you're using RVM:
-
-
-
    -shellserver:~$ sudo -i `which rvm-exec` default gem install arvados-login-sync
-
    
-    
+h2. Install arvados-login-sync
 
-If you're not using RVM:
+Install the arvados-login-sync program.
 
 
 
    -shellserver:~$ sudo -i gem install arvados-login-sync
+shellserver:# gem install arvados-login-sync
 
    
     
 
-Install cron.
-
-On Red Hat-based distributions:
-
-
-
    ~$ sudo yum install cronie
-~$ sudo systemctl enable crond
-~$ sudo systemctl start crond
-
    
-    
-
-On Debian-based systems:
-
-
-
    ~$ sudo apt-get install cron
-
    
-    
-
 Configure cron to run the @arvados-login-sync@ program every 2 minutes.
 
-If you're using RVM:
-
-
-
    -shellserver:~$ sudo bash -c 'umask 077; tee /etc/cron.d/arvados-login-sync' <<'EOF'
-ARVADOS_API_HOST="uuid_prefix.your.domain"
-ARVADOS_API_TOKEN="the_token_you_created_above"
-ARVADOS_VIRTUAL_MACHINE_UUID="zzzzz-2x53u-zzzzzzzzzzzzzzz"
-*/2 * * * * root /usr/local/rvm/bin/rvm-exec default arvados-login-sync
-EOF
-
    
-    
-
-If you're not using RVM:
-
 
 
    -shellserver:~$ sudo bash -c 'umask 077; tee /etc/cron.d/arvados-login-sync' <<'EOF'
+shellserver:# umask 077; tee /etc/cron.d/arvados-login-sync <<EOF
 ARVADOS_API_HOST="uuid_prefix.your.domain"
 ARVADOS_API_TOKEN="the_token_you_created_above"
 ARVADOS_VIRTUAL_MACHINE_UUID="zzzzz-2x53u-zzzzzzzzzzzzzzz"
@@ -176,3 +90,5 @@ A user should be able to log in to the shell server when the following condition
 * The user has uploaded an SSH public key: Workbench → Account menu → "SSH keys" item → "Add new SSH key" button.
 * As an admin user, you have given the user permission to log in: Workbench → Admin menu → "Users" item → "Show" button → "Admin" tab → "Setup shell account" button.
 * Two minutes have elapsed since the above conditions were satisfied, and the cron job has had a chance to run.
+
+
diff --git a/doc/install/install-sso.html.textile.liquid b/doc/install/install-sso.html.textile.liquid
index fbed12495b..3bc975ddd3 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -9,63 +9,79 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-h2(#dependencies). Install prerequisites
+# "Install dependencies":#dependencies
+# "Set up database":#database-setup
+# "Update config.yml":#update-config
+# "Configure the SSO server":#create-application-yml
+# "Update Nginx configuration":#update-nginx
+# "Install arvados-sso-server":#install-packages
+# "Create arvados-server client record":#client
+# "Restart the API server and controller":#restart-api
 
-The Arvados package repository includes an SSO server package that can help automate much of the deployment.
+h2(#dependencies). Install dependencies
 
-h3(#install_ruby_and_bundler). Install Ruby and Bundler
+# "Install PostgreSQL":install-postgresql.html
+# "Install Ruby and Bundler":ruby.html  Important!  The Single Sign On server only supports Ruby 2.3, to avoid version conflicts we recommend installing it on a different server from the API server.  When installing Ruby, ensure that you get the right version by installing the "ruby2.3" package, or by using RVM with @--ruby=2.3@
+# "Install nginx":nginx.html
+# "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html
 
-{% include 'install_ruby_and_bundler_sso' %}
+h2(#database-setup). Set up the database
 
-h3(#install_web_server). Set up a Web server
+{% assign service_role = "arvados_sso" %}
+{% assign service_database = "arvados_sso_production" %}
+{% assign use_contrib = false %}
+{% include 'install_postgres_database' %}
 
-For best performance, we recommend you use Nginx as your Web server frontend with a Passenger backend to serve the SSO server. The Passenger team provides "Nginx + Passenger installation instructions":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html.
+Now create @/etc/arvados/sso/database.yml@
 
-Follow the instructions until you see the section that says you are ready to deploy your Ruby application on the production server.
-
-h2(#install). Install the SSO server
+
    +production:
+  adapter: postgresql
+  encoding: utf8
+  database: arvados_sso_production
+  username: arvados_sso
+  password: $password
+  host: localhost
+  template: template0
+
    
 
-On a Debian-based system, install the following package:
+h2(#update-config). Update config.yml
 
-
-
    ~$ sudo apt-get install arvados-sso-server
-
    
-    
+
    +    Services:
+      SSO:
+        ExternalURL: auth.ClusterID.example.com
+    Login:
+      ProviderAppID: "arvados-server"
+      ProviderAppSecret: $app_secret
+
    
 
-On a Red Hat-based system, install the following package:
+Generate @ProviderAppSecret@:
 
 
-
    ~$ sudo yum install arvados-sso-server
-
    
-    
-
-h2(#configure). Configure the SSO server
-
-The package has installed three configuration files in @/etc/arvados/sso@:
+
    ~$ ruby -e 'puts rand(2**400).to_s(36)'
+zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+
    
 
-
-
    /etc/arvados/sso/application.yml
-/etc/arvados/sso/database.yml
-/etc/arvados/sso/production.rb
-
    
-    
+h2(#create-application-yml). Configure the SSO server
 
-The SSO server runs from the @/var/www/arvados-sso/current/@ directory. The files @/var/www/arvados-sso/current/config/application.yml@, @/var/www/arvados-sso/current/config/database.yml@ and @/var/www/arvados-sso/current/config/environments/production.rb@ are symlinked to the configuration files in @/etc/arvados/sso/@.
+The SSO server runs from the @/var/www/arvados-sso/current/@ directory. The files @/var/www/arvados-sso/current/config/application.yml@ and @/var/www/arvados-sso/current/config/database.yml@ will be symlinked to the configuration files in @/etc/arvados/sso/@.
 
 The SSO server reads the @config/application.yml@ file, as well as the @config/application.defaults.yml@ file. Values in @config/application.yml@ take precedence over the defaults that are defined in @config/application.defaults.yml@. The @config/application.yml.example@ file is not read by the SSO server and is provided for installation convenience only.
 
 Consult @config/application.default.yml@ for a full list of configuration options.  Local configuration goes in @/etc/arvados/sso/application.yml@, do not edit @config/application.default.yml@.
 
-h3(#uuid_prefix). uuid_prefix
+Create @/etc/arvados/sso/application.yml@ and add these keys:
 
-Generate a uuid prefix for the single sign on service.  This prefix is used to identify user records as originating from this site.  It must be exactly 5 lowercase ASCII letters and/or digits.  You may use the following snippet to generate a uuid prefix:
+
    +production:
+  uuid_prefix: xxxxx
+  secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+
    
 
-
-
    ~$ ruby -e 'puts "#{rand(2**64).to_s(36)[0,5]}"'
-abcde
-
    
+h3(#uuid_prefix). uuid_prefix
 
-Edit @/etc/arvados/sso/application.yml@ and set @uuid_prefix@ in the "common" section.
+Most of the time, you want this to be the same as your @ClusterID@.  If not, generate a new one from the command line listed previously.
 
 h3(#secret_token). secret_token
 
@@ -76,97 +92,11 @@ Generate a new secret token for signing cookies:
 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
 
    
 
-Edit @/etc/arvados/sso/application.yml@ and set @secret_token@ in the "common" section.
-
-There are other configuration options in @/etc/arvados/sso/application.yml@. See the "Authentication methods":install-sso.html#authentication_methods section below for more details.
-
-h2(#database). Set up the database
-
-Configure the SSO server to connect to your database by updating @/etc/arvados/sso/database.yml@. Replace the @xxxxxxxx@ database password placeholder with the "password you generated during database setup":install-postgresql.html#sso. Be sure to update the @production@ section.
-
-
-
    ~$ editor /etc/arvados/sso/database.yml
-
    
-
-h2(#reconfigure_package). Reconfigure the package
-
-{% assign railspkg = "arvados-sso-server" %}
-{% include 'install_rails_reconfigure' %}
-
-h2(#client). Create arvados-server client
-
-{% assign railshost = "" %}
-{% assign railsdir = "/var/www/arvados-sso/current" %}
-Use @rails console@ to create a @Client@ record that will be used by the Arvados API server.  {% include 'install_rails_command' %}
-
-Enter the following commands at the console.  The values that appear after you assign @app_id@ and @app_secret@ correspond to the values for @sso_app_id@ and @sso_app_secret@, respectively, in the "API server's SSO settings":install-api-server.html#omniauth.
-
-
-
    :001 > c = Client.new
-:002 > c.name = "joshid"
-:003 > c.app_id = "arvados-server"
-:004 > c.app_secret = rand(2**400).to_s(36)
-=> "save this string for your API server's sso_app_secret"
-:005 > c.save!
-:006 > quit
-
    
-    
-
-h2(#configure_web_server). Configure your web server
-
-Edit the http section of your Nginx configuration to run the Passenger server and act as a frontend for it. You might add a block like the following, adding SSL and logging parameters to taste:
-
-
-
    server {
-  listen 127.0.0.1:8900;
-  server_name localhost-sso;
-
-  root   /var/www/arvados-sso/current/public;
-  index  index.html;
-
-  passenger_enabled on;
-  # If you're not using RVM, comment out the line below.
-  passenger_ruby /usr/local/rvm/wrappers/default/ruby;
-}
-
-upstream sso {
-  server     127.0.0.1:8900  fail_timeout=10s;
-}
-
-proxy_http_version 1.1;
-
-server {
-  listen       [your public IP address]:443 ssl;
-  server_name  auth.your.domain;
-
-  ssl on;
-  ssl_certificate     /YOUR/PATH/TO/cert.pem;
-  ssl_certificate_key /YOUR/PATH/TO/cert.key;
+h3(#authentication_methods). Authentication methods
 
-  index  index.html;
+Authentication methods are configured in @application.yml@.  Currently three authentication methods are supported: local accounts, LDAP, and Google.  If neither Google nor LDAP are enabled, the SSO server defaults to local user accounts.   Only one authentication mechanism should be in use at a time.  Choose your authentication method and add the listed configuration items to the @production@ section.
 
-  location / {
-    proxy_pass            http://sso;
-    proxy_redirect        off;
-    proxy_connect_timeout 90s;
-    proxy_read_timeout    300s;
-
-    proxy_set_header      X-Forwarded-Proto https;
-    proxy_set_header      Host $http_host;
-    proxy_set_header      X-Real-IP $remote_addr;
-    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
-  }
-}
-
    
-    
-
-Finally, restart Nginx and your Arvados SSO server should be up and running. You can verify that by visiting the URL you configured your Nginx web server to listen on in the server section above (port 443). Read on if you want to configure your Arvados SSO server to use a different authentication backend.
-
-h2(#authentication_methods). Authentication methods
-
-Authentication methods are configured in @application.yml@.  Currently three authentication methods are supported: local accounts, LDAP, and Google+.  If neither Google+ nor LDAP are enabled, the SSO server defaults to local user accounts.   Only one authentication mechanism should be in use at a time.
-
-h3(#local_accounts). Local account authentication
+h4(#local_accounts). Local account authentication
 
 There are two configuration options for local accounts:
 
@@ -194,7 +124,7 @@ Enter the following commands at the console.
 
    
     
 
-h3(#ldap). LDAP authentication
+h4(#ldap). LDAP authentication
 
 The following options are available to configure LDAP authentication.  Note that you must preserve the indentation of the fields listed under @use_ldap@.
 
@@ -223,25 +153,81 @@ table(table).
 |bind_dn|If required by server, username to log with in before performing directory lookup|
 |password|If required by server, password to log with before performing directory lookup|
 
-h3(#google). Google+ authentication
+h4(#google). Google authentication
 
-In order to use Google+ authentication, you must use the Google Developers Console to create a set of client credentials.
+First, visit "Setting up Google auth.":google-auth.html
 
-# Go to the Google Developers Console and select or create a project; this will take you to the project page.
-# On the sidebar, click on *APIs & auth* then select *APIs*.
-## Search for *Contacts API* and click on *Enable API*.
-## Search for *Google+ API* and click on *Enable API*.
-# On the sidebar, click on *Credentials*; under *OAuth* click on *Create new Client ID* to bring up the *Create Client ID* dialog box.
-# Under *Application type* select *Web application*.
-# If the authorization origins are not displayed, clicking on *Create Client ID* will take you to *Consent screen* settings.
-## On consent screen settings, enter the appropriate details and click on *Save*.
-## This will return you to the *Create Client ID* dialog box.
-# You must set the authorization origins.  Edit @auth.your.domain@ to the appropriate hostname that you will use to access the SSO service:
-## JavaScript origin should be @https://auth.your.domain/@
-## Redirect URI should be @https://auth.your.domain/users/auth/google_oauth2/callback@
-# Copy the values of *Client ID* and *Client secret* from the Google Developers Console into the Google section of @config/application.yml@, like this:
+Next, copy the values of *Client ID* and *Client secret* from the Google Developers Console into the Google section of @config/application.yml@, like this:
 
 
 
      # Google API tokens required for OAuth2 login.
   google_oauth2_client_id: "---YOUR---CLIENT---ID---HERE--"-
   google_oauth2_client_secret: "---YOUR---CLIENT---SECRET---HERE--"-
    
+
+h2(#update-nginx). Update nginx configuration
+
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-sso.conf@ with the following configuration.  Options that need attention are marked with "TODO".
+
+
+
    server {
+  listen       auth.ClusterID.example.com:443 ssl;
+  server_name  auth.ClusterID.example.com;
+
+  ssl on;
+  ssl_certificate     /TODO/YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key /TODO/YOUR/PATH/TO/cert.key;
+
+  root   /var/www/arvados-sso/current/public;
+  index  index.html;
+
+  passenger_enabled on;
+
+  # TODO: If you are using RVM, uncomment the line below.
+  # If you're using system ruby, leave it commented out.
+  #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
+}
+
    
+    
+
+h2(#install-packages). Install arvados-sso-server package
+
+h3. Centos 7
+
+
+
    # yum install arvados-sso-server
+
    
+    
+
+h3. Debian and Ubuntu
+
+
+
    # apt-get --no-install-recommends arvados-sso-server
+
    
+    
+
+h2(#client). Create arvados-server client record
+
+{% assign railshost = "" %}
+{% assign railsdir = "/var/www/arvados-sso/current" %}
+Use @rails console@ to create a @Client@ record that will be used by the Arvados API server.  {% include 'install_rails_command' %}
+
+Enter the following commands at the console.  The values that appear after you assign @app_id@ and @app_secret@ will be copied to  @Login.ProviderAppID@ and @Login.ProviderAppSecret@ in @config.yml@.
+
+
+
    :001 > c = Client.new
+:002 > c.name = "joshid"
+:003 > c.app_id = "arvados-server"
+:004 > c.app_secret = "the value of Login.ProviderAppSecret"
+:005 > c.save!
+:006 > quit
+
    
+    
+
+h2(#restart-api). Restart the API server and controller
+
+After adding the SSO server to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
+
+
+
    # systemctl restart nginx arvados-controller
+
    
+    
diff --git a/doc/install/install-workbench-app.html.textile.liquid b/doc/install/install-workbench-app.html.textile.liquid
index 72a80fd834..cf33cca358 100644
--- a/doc/install/install-workbench-app.html.textile.liquid
+++ b/doc/install/install-workbench-app.html.textile.liquid
@@ -9,41 +9,35 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-h2. Install prerequisites
+# "Install dependencies":#dependencies
+# "Update config.yml":#update-config
+# "Update Nginx configuration":#update-nginx
+# "Install arvados-workbench":#install-packages
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
+# "Trusted client setting":#trusted_client
 
-The Arvados package repository includes a Workbench server package that can help automate much of the deployment.
+h2(#dependencies). Install dependencies
 
-h3(#install_ruby_and_bundler). Install Ruby and Bundler
+# "Install Ruby and Bundler":ruby.html
+# "Install nginx":nginx.html
+# "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html
 
-{% include 'install_ruby_and_bundler' %}
+h2(#configure). Update config.yml
 
-h2(#install_workbench). Install Workbench and dependencies
-
-Workbench doesn't need its own database, so it does not need to have PostgreSQL installed.
-
-{% assign rh_version = "7" %}
-{% include 'note_python_sc' %}
-
-On a Debian-based system, install the following packages:
+Edit @/etc/arvados/config.yml@ to set the keys below.  The full set of configuration options are in the "Workbench section of config.yml":{{site.baseurl}}/admin/config.html
 
 
-
    ~$ sudo apt-get install bison build-essential graphviz git python-arvados-python-client arvados-workbench
-
    
-    
-
-On a Red Hat-based system, install the following packages:
-
-
-
    ~$ sudo yum install bison make automake gcc gcc-c++ graphviz git python-arvados-python-client arvados-workbench
+
        Services:
+      Workbench:
+        ExternalURL: "https://workbench.ClustedID.example.com"
+    Workbench:
+      SecretKeyBase: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    Users:
+      AutoAdminFirstUser: true
 
    
 
 
-h2(#configure). Configure Workbench
-
-Edit @/etc/arvados/config.yml@ to set the keys below.  Only the most important configuration options are listed here.  The full set of configuration options are in the "Workbench section of config.yml":{{site.baseurl}}/admin/config.html
-
-h3. Workbench.SecretKeyBase
-
 This application needs a secret token. Generate a new secret:
 
 
@@ -54,72 +48,23 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 
 Then put that value in the @Workbench.SecretKeyBase@ field.
 
-
-
    Cluster:
-  zzzzz:
-    Workbench:
-      SecretKeyBase: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-
    
-    
-
-h3. Services.Controller.ExternalURL
-
-Ensure that @Services.Controller.ExternalURL@ is configured for "Arvados Controller":install-controller.html . For example like this:
-
-
-
    Cluster:
-  zzzzz:
-    Services:
-      Controller:
-        ExternalURL: https://prefix_uuid.your.domain
-
    
-    
-
-h3. Workbench.SiteName
-
-@Workbench.SiteName@ can be set to any arbitrary string. It is used to identify this Workbench to people visiting it.
-
-
-
-
    Cluster:
-  zzzzz:
-    Workbench:
-      SiteName: My Arvados
-
    
-    
-
-h3. TLS.Insecure
-
-For testing only.  Allows use of self-signed certificates.  If true, workbench will not verify the TLS certificate of Arvados Controller.
-
-
-
    Cluster:
-  zzzzz:
-    TLS:
-      Insecure: false
-
    
-    
-
-h2. Configure Piwik (optional)
+You probably want to enable @Users.AutoAdminFirstUser@ .  The first user to log in when no other admin user exists will automatically be made an admin.
 
-Piwik can be used to gather usage analytics.  In @/var/www/arvados-workbench/current/config@, copy @piwik.yml.example@ to @piwik.yml@ and edit to suit.
+h2(#update-nginx). Update nginx configuration
 
-h2. Set up Web server
-
-For best performance, we recommend you use Nginx as your Web server front-end, with a Passenger backend to serve Workbench.  To do that:
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-workbench.conf@ with the following configuration.  Options that need attention are marked with "TODO".
 
 
-
      
-
    1. Install Nginx and Phusion Passenger.
      2. 
-
-
    2. Edit the http section of your Nginx configuration to run the Passenger server, and act as a front-end for it.  You might add a block like the following, adding SSL and logging parameters to taste:
      
-
 
      server {
-  listen 127.0.0.1:9000;
-  server_name localhost-workbench;
+  listen       [your public IP address]:443 ssl;
+  server_name  workbench.ClusterID.example.com;
+
+  ssl on;
+  ssl_certificate     /YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key /YOUR/PATH/TO/cert.key;
 
   root /var/www/arvados-workbench/current/public;
-  index  index.html index.htm index.php;
+  index  index.html;
 
   passenger_enabled on;
   # If you're using RVM, uncomment the line below.
@@ -129,65 +74,39 @@ For best performance, we recommend you use Nginx as your Web server front-end, w
   # the API.MaxRequestSize and Controller's server's Nginx configuration.
   client_max_body_size 128m;
 }
+
      
+
 
-upstream workbench {
-  server     127.0.0.1:9000  fail_timeout=10s;
-}
-
-proxy_http_version 1.1;
-
-server {
-  listen       [your public IP address]:443 ssl;
-  server_name  workbench.uuid-prefix.your.domain;
-
-  ssl on;
-  ssl_certificate     /YOUR/PATH/TO/cert.pem;
-  ssl_certificate_key /YOUR/PATH/TO/cert.key;
+h2(#install-packages). Install arvados-workbench
 
-  index  index.html index.htm index.php;
-  # `client_max_body_size` should match the corresponding setting in
-  # the API.MaxRequestSize and Controller's server's Nginx configuration.
-  client_max_body_size 128m;
+h3. Centos 7
 
-  location / {
-    proxy_pass            http://workbench;
-    proxy_redirect        off;
-    proxy_connect_timeout 90s;
-    proxy_read_timeout    300s;
-
-    proxy_set_header      X-Forwarded-Proto https;
-    proxy_set_header      Host $http_host;
-    proxy_set_header      X-Real-IP $remote_addr;
-    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
-  }
-}
+
+
      # yum install arvados-workbench
 
      
-
      3. 
+
 
-
    3. Restart Nginx.
      4. 
+h3. Debian and Ubuntu
 
-
    
+
+
    # apt-get --no-install-recommends install arvados-workbench
+
    
     
 
-h2. Prepare the Workbench deployment
+h2(#restart-api). Restart the API server and controller
 
-{% assign railspkg = "arvados-workbench" %}
-{% include 'install_rails_reconfigure' %}
+After adding Workbench to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 
-{% include 'notebox_begin' %}
-You can safely ignore the following error message you may see when Ruby Gems are installed:
 
-
    themes_for_rails at /usr/local/rvm/gems/ruby-2.1.1/bundler/gems/themes_for_rails-1fd2d7897d75 did not have a valid gemspec.
-This prevents bundler from installing bins or native extensions, but that may not affect its functionality.
-The validation message from Rubygems was:
-  duplicate dependency on rails (= 3.0.11, development), (>= 3.0.0) use:
-    add_runtime_dependency 'rails', '= 3.0.11', '>= 3.0.0'
-Using themes_for_rails (0.5.1) from https://github.com/holtkampw/themes_for_rails (at 1fd2d78)
+
    # systemctl restart nginx arvados-controller
 
    
 
-{% include 'notebox_end' %}
 
-h2. Trusted client setting
+h2(#confirm-working). Confirm working installation
+
+Visit @https://workbench.ClusterID.example.com@ in a browser.  You should be able to log in using the login method you configured in the previous step.  If @Users.AutoAdminFirstUser@ is true, you will be an admin user.
+
+h2(#trusted_client). Trusted client flag
 
 Log in to Workbench once to ensure that the Arvados API server has a record of the Workbench client. (It's OK if Workbench says your account hasn't been activated yet. We'll deal with that next.)
 
@@ -204,17 +123,3 @@ irb(main):003:0> act_as_system_user do wb.update_attr
 
    
     
 
-h2(#admin-user). Add an admin user
-
-Next, we're going to use the Rails console on the API server to activate your account and give yourself admin privileges.  {% include 'install_rails_command' %}
-
-Enter the following commands at the console:
-
-
-
    irb(main):001:0> Thread.current[:user] = User.all.select(&:identity_url).last
-irb(main):002:0> Thread.current[:user].update_attributes is_admin: true, is_active: true
-irb(main):003:0> User.where(is_admin: true).collect &:email
-=> ["root", "your_address@example.com"]
-
    
-
-At this point, you should have a working Workbench login with administrator privileges. Revisit your Workbench URL in a browser and reload the page to access it.
diff --git a/doc/install/install-workbench2-app.html.textile.liquid b/doc/install/install-workbench2-app.html.textile.liquid
index b5bdcd42cc..566d878782 100644
--- a/doc/install/install-workbench2-app.html.textile.liquid
+++ b/doc/install/install-workbench2-app.html.textile.liquid
@@ -9,43 +9,44 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+# "Update config.yml":#update-config
+# "Update Nginx configuration":#update-nginx
+# "Install arvados-workbench2":#install-packages
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
+# "Trusted client setting":#trusted_client
+
 Workbench2 is the web-based user interface for Arvados.
 
 {% include 'notebox_begin' %}
 Workbench2 is the replacement for Arvados Workbench. Workbench2 is currently in beta, it is not yet feature complete.
 {% include 'notebox_end' %}
 
-h2(#install_workbench). Install Workbench2 and dependencies
-
-Workbench2 does not require its own database. It is a set of html, javascript and css files that are served as static files from a web server like Nginx or Apache2.
+h2(#configure). Update config.yml
 
-On a Debian-based system, install the following package:
+Edit @/etc/arvados/config.yml@ to set the keys below.  The full set of configuration options are in the "Workbench section of config.yml":{{site.baseurl}}/admin/config.html
 
 
-
    ~$ sudo apt-get install arvados-workbench2
+
        Services:
+      Workbench2:
+        ExternalURL: "https://workbench2.ClustedID.example.com"
 
    
 
 
-On a Red Hat-based system, install the following package:
-
-
-
    ~$ sudo yum install arvados-workbench2
-
    
-    
+h2. Vocabulary configuration (optional)
 
-h2. Set up Web server
+Workbench2 can load a vocabulary file which lists available metadata properties for groups and collections.  To configure the property vocabulary definition, please visit the "Workbench2 Vocabulary Format":{{site.baseurl}}/admin/workbench2-vocabulary.html page in the Admin section.
 
-For best performance, we recommend you use Nginx as your Web server to serve Workbench2. Workbench2 consists entirely of static files. To do that:
+h2(#update-nginx). Update Nginx configuration
 
-
-
      
-
    1. Install Nginx
      2. 
+Workbench2 does not require its own database. It is a set of html, javascript and css files that are served as static files from Nginx.
 
-
    2. Edit the http section of your Nginx configuration to serve Workbench2's files. You might add a block like the following, adding SSL and logging parameters to taste:
      
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-workbench2.conf@ with the following configuration.  Options that need attention are marked with "TODO".
 
+
 
      server {
   listen       [your public IP address]:443 ssl;
-  server_name  workbench2.uuid-prefix.your.domain;
+  server_name  workbench2.ClusterID.example.com;
 
   ssl on;
   ssl_certificate     /YOUR/PATH/TO/cert.pem;
@@ -55,7 +56,7 @@ For best performance, we recommend you use Nginx as your Web server to serve Wor
 
   # Workbench2 uses a call to /config.json to bootstrap itself and talk to the desired API server
   location /config.json {
-    return 200 '{ "API_HOST": "uuid-prefix.your.domain" }';
+    return 200 '{ "API_HOST": "ClusterID.example.com" }';
   }
 
   location / {
@@ -68,30 +69,50 @@ For best performance, we recommend you use Nginx as your Web server to serve Wor
   }
 }
 
      
-
      3. 
+
 
-
    3. Restart Nginx.
      4. 
+h2(#install-packages). Install arvados-workbench2
 
-
    
+h3. Centos 7
+
+
+
    # yum install arvados-workbench2
+
    
     
 
-h2. Trusted client setting
+h3. Debian and Ubuntu
 
-Log in to Workbench2 once to ensure that the Arvados API server has a record of the Workbench2 client.
+
+
    # apt-get --no-install-recommends install arvados-workbench2
+
    
+    
+
+h2(#restart-api). Restart the API server and controller
+
+After adding Workbench to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
+
+
+
    # systemctl restart nginx arvados-controller
+
    
+    
+
+h2(#confirm-working). Confirm working installation
+
+Visit @https://workbench2.ClusterID.example.com@ in a browser.  You should be able to log in using the login method you configured in the previous step.  If @Users.AutoAdminFirstUser@ is true, you will be an admin user.
+
+h2(#trusted_client). Trusted client flag
+
+Log in to Workbench once to ensure that the Arvados API server has a record of the Workbench client. (It's OK if Workbench says your account hasn't been activated yet. We'll deal with that next.)
 
 In the API server project root, start the Rails console.  {% include 'install_rails_command' %}
 
-At the console, enter the following commands to locate the ApiClient record for your Workbench2 installation (typically, while you're setting this up, the @last@ one in the database is the one you want), then set the @is_trusted@ flag for the appropriate client record:
+At the console, enter the following commands to locate the ApiClient record for your Workbench installation (typically, while you're setting this up, the @last@ one in the database is the one you want), then set the @is_trusted@ flag for the appropriate client record:
 
 
    irb(main):001:0> wb = ApiClient.all.last; [wb.url_prefix, wb.created_at]
-=> ["https://workbench2.uuid_prefix.your.domain/", Sat, 20 Apr 2019 01:23:45 UTC +00:00]
+=> ["https://workbench.example.com/", Sat, 19 Apr 2014 03:35:12 UTC +00:00]
 irb(main):002:0> include CurrentApiClient
 => true
 irb(main):003:0> act_as_system_user do wb.update_attributes!(is_trusted: true) end
 => true
 
    
     
-
-h2. Vocabulary configuration (optional)
-
-To configure the property vocabulary definition, please visit the "Workbench2 Vocabulary Format":{{site.baseurl}}/admin/workbench2-vocabulary.html page in the Admin section.
\ No newline at end of file
diff --git a/doc/install/install-ws.html.textile.liquid b/doc/install/install-ws.html.textile.liquid
index f6a4bb5faf..2a0baa7506 100644
--- a/doc/install/install-ws.html.textile.liquid
+++ b/doc/install/install-ws.html.textile.liquid
@@ -11,60 +11,75 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 
 The arvados-ws server provides event notifications to websocket clients. It can be installed anywhere with access to Postgres database and the Arvados API server, typically behind a web proxy that provides SSL support. See the "godoc page":http://godoc.org/github.com/curoverse/arvados/services/ws for additional information.
 
-By convention, we use the following hostname for the websocket service.
+# "Update config.yml":#update-config
+# "Update nginx configuration":#update-nginx
+# "Install arvados-ws package":#install-packages
+# "Start the service":#start-service
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
+
+h2(#configure). Update config.yml
+
+Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Websocket.ExternalURL@ and @Services.Websocket.InternalURLs@.  Replace @zzzzz@ with your cluster id.
 
 
-
    ws.uuid_prefix.your.domain
    
+
        Services:
+      Websocket:
+        InternalURLs:
+	  "http://ws.ClusterID.example.com:8005": {}      
+        ExternalURL: wss://ws.ClusterID.example.com/websocket
+
    
     
 
-The above hostname should resolve from anywhere on the internet.
+h2(#update-nginx). Update Nginx configuration
 
-h2. Install arvados-ws
+The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.
 
-Typically arvados-ws runs on the same host as the API server.
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-ws.conf@ with the following configuration.  Options that need attention are marked with "TODO".
 
-On Debian-based systems:
+
    +upstream arvados-ws {
+  server                127.0.0.1:8005;
+}
 
-
-
    ~$ sudo apt-get install arvados-ws
-
    
-    
+server {
+  listen                [your public IP address]:443 ssl;
+  server_name           ws.uuid_prefix.your.domain;
 
-On Red Hat-based systems:
+  proxy_connect_timeout 90s;
+  proxy_read_timeout    300s;
 
-
-
    ~$ sudo yum install arvados-ws
-
    
-    
+  ssl                   on;
+  ssl_certificate       YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key   YOUR/PATH/TO/cert.key;
 
-Verify that @arvados-ws@ is functional:
+  location / {
+    proxy_pass          http://arvados-ws;
+    proxy_set_header    Upgrade         $http_upgrade;
+    proxy_set_header    Connection      "upgrade";
+    proxy_set_header    Host            $host;
+    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
+  }
+}
+
    
+
+h2(#install-packages). Install arvados-ws
+
+h3. Centos 7
 
 
-
    ~$ arvados-ws -h
-Usage of arvados-ws:
-  -config path
-        path to config file (default "/etc/arvados/config.yml")
-  -dump-config
-        show current configuration and exit
+
    # yum install arvados-ws
 
    
 
 
-h3. Update cluster config
-
-Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Websocket.ExternalURL@ and @Services.Websocket.InternalURLs@.  Replace @zzzzz@ with your cluster id.
+h3. Debian and Ubuntu
 
 
-
    Clusters:
-  zzzzz:
-    Services:
-      Websocket:
-        ExternalURL: wss://ws.uuid_prefix.your.domain/websocket
-        InternalURLs:
-	  "http://localhost:9003": {}
-
    
+
    # apt-get --no-install-recommends install arvados-ws
+
    
     
 
-h3. Start the service (option 1: systemd)
+h3. Start the service
 
 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
 
@@ -98,100 +113,21 @@ Dec 06 11:12:48 zzzzz arvados-ws[8918]: {"error":"pq: password authentication fa
 
    
     
 
-Skip ahead to "confirm the service is working":#confirm.
-
-h3(#runit). Start the service (option 2: runit)
+h2(#restart-api). Restart the API server and controller
 
-Install runit to supervise the arvados-ws daemon.  {% include 'install_runit' %}
-
-Create a supervised service.
+After adding the SSO server to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 
 
-
    ~$ sudo mkdir /etc/service/arvados-ws
-~$ cd /etc/service/arvados-ws
-~$ sudo mkdir log log/main
-~$ printf '#!/bin/sh\nexec arvados-ws 2>&1\n' | sudo tee run
-~$ printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run
-~$ sudo chmod +x run log/run
-~$ sudo sv exit .
-~$ cd -
+
    # systemctl restart nginx arvados-controller
 
    
 
 
-Use @sv stat@ and check the log file to verify the service is running.
-
-
-
    ~$ sudo sv stat /etc/service/arvados-ws
-run: /etc/service/arvados-ws: (pid 12520) 2s; run: log: (pid 12519) 2s
-~$ tail /etc/service/arvados-ws/log/main/current
-{"level":"info","msg":"started","time":"2016-12-06T11:56:20.669171449-05:00"}
-{"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:56:20.708847627-05:00"}
-
    
-    
-
-h3(#confirm). Confirm the service is working
+h3(#confirm). Confirm working installation
 
 Confirm the service is listening on its assigned port and responding to requests.
 
 
-
    ~$ curl http://0.0.0.0:9003/status.json
+
    ~$ curl http://0.0.0.0:8005/status.json
 {"Clients":1}
 
    
 
-
-h3. Set up a reverse proxy with SSL support
-
-The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.
-
-This is best achieved by putting a reverse proxy with SSL support in front of arvados-ws, running on port 443 and passing requests to arvados-ws on port 9003 (or whatever port you chose in your configuration file).
-
-For example, using Nginx:
-
-
    -upstream arvados-ws {
-  server                127.0.0.1:9003;
-}
-
-server {
-  listen                [your public IP address]:443 ssl;
-  server_name           ws.uuid_prefix.your.domain;
-
-  proxy_connect_timeout 90s;
-  proxy_read_timeout    300s;
-
-  ssl                   on;
-  ssl_certificate       YOUR/PATH/TO/cert.pem;
-  ssl_certificate_key   YOUR/PATH/TO/cert.key;
-
-  location / {
-    proxy_pass          http://arvados-ws;
-    proxy_set_header    Upgrade         $http_upgrade;
-    proxy_set_header    Connection      "upgrade";
-    proxy_set_header    Host            $host;
-    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
-  }
-}
-
    
-
-{% include 'notebox_begin' %}
-If you are upgrading a cluster where Nginx is configured to proxy @ws@ requests to puma, change the @server_name@ value in the old configuration block so it doesn't conflict. When the new configuration is working, delete the old Nginx configuration sections (i.e., the "upstream websockets" block, and the "server" block that references @http://websockets@), and disable/remove the runit or systemd files for the puma server.
-{% include 'notebox_end' %}
-
-h3. Update API server configuration
-
-Restart Nginx to reload the API server configuration.
-
-
-
    $ sudo nginx -s reload
-
    
-    
-
-h3. Verify DNS and proxy setup
-
-Use a host elsewhere on the Internet to confirm that your DNS, proxy, and SSL are configured correctly.  For @Authorization: Bearer xxxx@ replace @xxxx@ with the value from @ManagementToken@ in @config.yml@.
-
-
-
    $ curl -H "Authorization: Bearer xxxx" https://ws.uuid_prefix.your.domain/_health/ping
-{"health":"OK"}
-
    
-    
diff --git a/doc/install/nginx.html.textile.liquid b/doc/install/nginx.html.textile.liquid
new file mode 100644
index 0000000000..364cc9c3f6
--- /dev/null
+++ b/doc/install/nginx.html.textile.liquid
@@ -0,0 +1,20 @@
+---
+layout: default
+navsection: installguide
+title: Install Nginx
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+h3. Centos 7
+
+???
+
+h3. Debian and Ubuntu
+
+
+
    # apt-get --no-install-recommends install nginx
    
+    
diff --git a/doc/install/packages.html.textile.liquid b/doc/install/packages.html.textile.liquid
new file mode 100644
index 0000000000..8507d02644
--- /dev/null
+++ b/doc/install/packages.html.textile.liquid
@@ -0,0 +1,61 @@
+---
+layout: default
+navsection: installguide
+title: Arvados package repositories
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+On any host where you install Arvados software, you'll need to add the Arvados package repository.  They're available for several popular distributions.
+
+* "Centos 7":#centos7
+* "Debian and Ubuntu":#debian
+
+h3(#centos7). CentOS
+
+Packages are available for CentOS 7. To install them with yum, save this configuration block in @/etc/yum.repos.d/arvados.repo@:
+
+
+
    [arvados]
+name=Arvados
+baseurl=http://rpm.arvados.org/CentOS/$releasever/os/$basearch/
+gpgcheck=1
+gpgkey=http://rpm.arvados.org/CentOS/RPM-GPG-KEY-curoverse
+
    
+    
+
+{% include 'install_redhat_key' %}
+
+h3(#debian). Debian and Ubuntu
+
+Packages are available for recent versions of Debian and Ubuntu.
+
+First, register the Curoverse signing key in apt's database:
+
+{% include 'install_debian_key' %}
+
+As root, add the Arvados package repository to your sources.  This command depends on your OS vendor and version:
+
+table(table table-bordered table-condensed).
+|_. OS version|_. Command|
+|Debian 10 ("buster")|echo "deb http://apt.arvados.org/ buster main" | tee /etc/apt/sources.list.d/arvados.list|
+|Debian 9 ("stretch")|echo "deb http://apt.arvados.org/ stretch main" | tee /etc/apt/sources.list.d/arvados.list|
+|Ubuntu 18.04 ("bionic")[1]|echo "deb http://apt.arvados.org/ bionic main" | tee /etc/apt/sources.list.d/arvados.list|
+|Ubuntu 16.04 ("xenial")[1]|echo "deb http://apt.arvados.org/ xenial main" | tee /etc/apt/sources.list.d/arvados.list|
+
+
+{% include 'notebox_begin' %}
+
+fn1. Arvados packages for Ubuntu may depend on third-party packages in Ubuntu's "universe" repository.  If you're installing on Ubuntu, make sure you have the universe sources uncommented in @/etc/apt/sources.list@.
+
+{% include 'notebox_end' %}
+
+Retrieve the package list:
+
+
+
    # apt-get update
+
    
+    
diff --git a/doc/install/proxy-chain.odg b/doc/install/proxy-chain.odg
new file mode 100644
index 0000000000..44c6993ad1
Binary files /dev/null and b/doc/install/proxy-chain.odg differ
diff --git a/doc/install/ruby.html.textile.liquid b/doc/install/ruby.html.textile.liquid
new file mode 100644
index 0000000000..fa8fcb3f58
--- /dev/null
+++ b/doc/install/ruby.html.textile.liquid
@@ -0,0 +1,12 @@
+---
+layout: default
+navsection: installguide
+title: Install Ruby and Bundler
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+{% include 'install_ruby_and_bundler' %}
diff --git a/doc/install/setup-login.html.textile.liquid b/doc/install/setup-login.html.textile.liquid
new file mode 100644
index 0000000000..46f168774d
--- /dev/null
+++ b/doc/install/setup-login.html.textile.liquid
@@ -0,0 +1,29 @@
+---
+layout: default
+navsection: installguide
+title: Set up web based login
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+# "Option 1: Google login through Arvados controller":#controller
+# "Option 2: Separate single-sign-on (SSO) server (Google, LDAP, local database)":#sso
+
+h2(#controller). Option 1: Google login through Arvados controller
+
+First, visit "Setting up Google auth.":google-auth.html
+
+Next, copy the values of *Client ID* and *Client secret* from the Google Developers Console into @Login.GoogleClientID@ and @Login.GoogleClientSecret@ of @config.yml@ :
+
+
    +    Login:
+      GoogleClientID: ""
+      GoogleClientSecret: ""
+
    
+
+h2(#sso). Option 2: Separate single-sign-on (SSO) server (supports Google, LDAP, local database)
+
+See "Install the Single Sign On (SSO) server":#install-sso.html
diff --git a/lib/config/config.default.yml b/lib/config/config.default.yml
index 98e6bd3720..77ac6e7dc7 100644
--- a/lib/config/config.default.yml
+++ b/lib/config/config.default.yml
@@ -882,7 +882,6 @@ Clusters:
           SAMPLE: true
         Driver: s3
         DriverParameters:
-
           # for s3 driver -- see
           # https://doc.arvados.org/install/configure-s3-object-storage.html
           IAMRole: aaaaa
@@ -896,6 +895,15 @@ Clusters:
           ConnectTimeout: 1m
           ReadTimeout: 10m
           RaceWindow: 24h
+
+          # For S3 driver, potentially unsafe tuning parameter,
+          # intentionally excluded from main documentation.
+          #
+          # Enable deletion (garbage collection) even when the
+          # configured BlobTrashLifetime is zero.  WARNING: eventual
+          # consistency may result in race conditions that can cause
+          # data loss.  Do not enable this unless you understand and
+          # accept the risk.
           UnsafeDelete: false
 
           # for azure driver -- see
@@ -914,6 +922,21 @@ Clusters:
           # for local directory driver -- see
           # https://doc.arvados.org/install/configure-fs-storage.html
           Root: /var/lib/arvados/keep-data
+
+          # For local directory driver, potentially confusing tuning
+          # parameter, intentionally excluded from main documentation.
+          #
+          # When true, read and write operations (for whole 64MiB
+          # blocks) on an individual volume will queued and issued
+          # serially.  When false, read and write operations will be
+          # issued concurrently.
+          #
+          # May possibly improve throughput if you have physical spinning disks
+          # and experience contention when there are multiple requests
+          # to the same volume.
+          #
+          # Otherwise, when using SSDs, RAID, or a shared network filesystem, you
+          # should leave this alone.
           Serialize: false
 
     Mail:
diff --git a/services/login-sync/Gemfile.lock b/services/login-sync/Gemfile.lock
index 5f163e87c3..1d89604ae1 100644
--- a/services/login-sync/Gemfile.lock
+++ b/services/login-sync/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    arvados-login-sync (1.4.1.20190930204434)
+    arvados-login-sync (1.3.1.pre20191210204053)
       arvados (~> 1.3.0, >= 1.3.0)
       faraday (< 0.16)
 
@@ -23,7 +23,7 @@ GEM
       i18n (~> 0)
       json (>= 1.7.7, < 3)
       jwt (>= 0.1.5, < 2)
-    arvados-google-api-client (0.8.7.2)
+    arvados-google-api-client (0.8.7.3)
       activesupport (>= 3.2, < 5.1)
       addressable (~> 2.3)
       autoparse (~> 0.3)
@@ -60,7 +60,7 @@ GEM
     minitest (5.11.3)
     mocha (1.8.0)
       metaclass (~> 0.0.1)
-    multi_json (1.13.1)
+    multi_json (1.14.1)
     multipart-post (2.1.1)
     os (1.0.1)
     public_suffix (4.0.1)
@@ -85,4 +85,4 @@ DEPENDENCIES
   rake
 
 BUNDLED WITH
-   1.17.3
+   2.0.2