From: Peter Amstutz Date: Mon, 30 Dec 2019 15:32:47 +0000 (-0500) Subject: Merge branch '15572-new-install-docs' refs #15572 X-Git-Tag: 2.0.0~72 X-Git-Url: https://git.arvados.org/arvados.git/commitdiff_plain/9f4a1c3767bfffed94e90fa6737e58fa13fb5a21?hp=949abe8b7922c2b8d74b40366f053fdab1a1d214 Merge branch '15572-new-install-docs' refs #15572 Arvados-DCO-1.1-Signed-off-by: Peter Amstutz --- diff --git a/doc/Rakefile b/doc/Rakefile index 63dc16d25d..71d86c32dc 100644 --- a/doc/Rakefile +++ b/doc/Rakefile @@ -43,6 +43,8 @@ file "sdk/R/arvados/index.html" do |t| tgt = Dir.pwd Dir.mkdir("sdk/R") Dir.mkdir("sdk/R/arvados") + puts("tgt", tgt) + cp('css/R.css', 'sdk/R/arvados') docfiles = [] Dir.chdir("../sdk/R/") do STDERR.puts `Rscript createDoc.R README.Rmd #{tgt}/sdk/R/README.md 2>&1` @@ -114,6 +116,8 @@ file "sdk/java-v2/javadoc/index.html" do |t| Dir.chdir("../sdk/java-v2") do STDERR.puts `gradle javadoc 2>&1` raise if $? != 0 + puts `sed -i "s/@import.*dejavu.css.*//g" build/docs/javadoc/stylesheet.css` + raise if $? != 0 end cp_r("../sdk/java-v2/build/docs/javadoc", "sdk/java-v2") raise if $? != 0 diff --git a/doc/_config.yml b/doc/_config.yml index bcb66fdb39..310f776f8c 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -88,9 +88,6 @@ navbar: - R: - sdk/R/index.html.md - sdk/R/arvados/index.html.textile.liquid - - Perl: - - sdk/perl/index.html.textile.liquid - - sdk/perl/example.html.textile.liquid - Ruby: - sdk/ruby/index.html.textile.liquid - sdk/ruby/example.html.textile.liquid @@ -101,6 +98,9 @@ navbar: - Java v1: - sdk/java/index.html.textile.liquid - sdk/java/example.html.textile.liquid + - Perl: + - sdk/perl/index.html.textile.liquid + - sdk/perl/example.html.textile.liquid api: - Concepts: - api/index.html.textile.liquid @@ -149,17 +149,12 @@ navbar: admin: - Topics: - admin/index.html.textile.liquid - - Configuration: - - admin/config.html.textile.liquid - - admin/federation.html.textile.liquid - - Upgrading and migrations: - - admin/upgrading.html.textile.liquid - - admin/config-migration.html.textile.liquid - Users and Groups: - admin/user-management.html.textile.liquid - admin/reassign-ownership.html.textile.liquid - admin/user-management-cli.html.textile.liquid - admin/group-management.html.textile.liquid + - admin/federation.html.textile.liquid - admin/merge-remote-account.html.textile.liquid - admin/migrating-providers.html.textile.liquid - user/topics/arvados-sync-groups.html.textile.liquid @@ -191,11 +186,14 @@ 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 + - admin/upgrading.html.textile.liquid + - Configuration: + - install/config.html.textile.liquid + - admin/config-migration.html.textile.liquid + - admin/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,21 +203,24 @@ 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 - - Containers API support on SLURM: - - install/crunch2-slurm/install-prerequisites.html.textile.liquid - - install/crunch2-slurm/install-slurm.html.textile.liquid + - install/install-shell-server.html.textile.liquid + - Containers API: - install/crunch2-slurm/install-compute-node.html.textile.liquid + - install/install-jobs-image.html.textile.liquid + - install/install-dispatch-cloud.html.textile.liquid - install/crunch2-slurm/install-dispatch.html.textile.liquid - install/crunch2-slurm/install-test.html.textile.liquid - - install/install-nodemanager.html.textile.liquid - - 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 + - install/install-docker.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_compute_docker.liquid b/doc/_includes/_install_compute_docker.liquid index 69b49e83cd..63c54aed72 100644 --- a/doc/_includes/_install_compute_docker.liquid +++ b/doc/_includes/_install_compute_docker.liquid @@ -4,76 +4,47 @@ Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} -h2. Install Docker +h2(#cgroups). Configure Linux cgroups accounting -Compute nodes must have Docker installed to run containers. This requires a relatively recent version of Linux (at least upstream version 3.10, or a distribution version with the appropriate patches backported). Follow the "Docker Engine installation documentation":https://docs.docker.com/ for your distribution. - -For Debian-based systems, the Arvados package repository includes a backported @docker.io@ package with a known-good version you can install. - -h2(#configure_docker_daemon). Configure the Docker daemon - -Crunch runs Docker containers with relatively little configuration. You may need to start the Docker daemon with specific options to make sure these jobs run smoothly in your environment. This section highlights options that are useful to most installations. Refer to the "Docker daemon reference":https://docs.docker.com/reference/commandline/daemon/ for complete information about all available options. - -The best way to configure these options varies by distribution. - -* If you're using our backported @docker.io@ package, you can list these options in the @DOCKER_OPTS@ setting in @/etc/default/docker.io@. -* If you're using another Debian-based package, you can list these options in the @DOCKER_OPTS@ setting in @/etc/default/docker@. -* On Red Hat-based distributions, you can list these options in the @other_args@ setting in @/etc/sysconfig/docker@. - -h3. Default ulimits - -Docker containers inherit ulimits from the Docker daemon. However, the ulimits for a single Unix daemon may not accommodate a long-running Crunch job. You may want to increase default limits for compute containers by passing @--default-ulimit@ options to the Docker daemon. For example, to allow containers to open 10,000 files, set @--default-ulimit nofile=10000:10000@. +Linux can report what compute resources are used by processes in a specific cgroup or Docker container. Crunch can use these reports to share that information with users running compute work. This can help pipeline authors debug and optimize their workflows. -h3. DNS +To enable cgroups accounting, you must boot Linux with the command line parameters @cgroup_enable=memory swapaccount=1@. -Your containers must be able to resolve the hostname of your API server and any hostnames returned in Keep service records. If these names are not in public DNS records, you may need to specify a DNS resolver for the containers by setting the @--dns@ address to an IP address of an appropriate nameserver. You may specify this option more than once to use multiple nameservers. +After making changes, reboot the system to make these changes effective. -h2. Configure Linux cgroups accounting +h3. Red Hat and CentOS -Linux can report what compute resources are used by processes in a specific cgroup or Docker container. Crunch can use these reports to share that information with users running compute work. This can help pipeline authors debug and optimize their workflows. + +
~$ sudo grubby --update-kernel=ALL --args='cgroup_enable=memory swapaccount=1'
+
+ -To enable cgroups accounting, you must boot Linux with the command line parameters @cgroup_enable=memory swapaccount=1@. +h3. Debian and Ubuntu -On Debian-based systems, open the file @/etc/default/grub@ in an editor. Find where the string @GRUB_CMDLINE_LINUX@ is set. Add @cgroup_enable=memory swapaccount=1@ to that string. Save the file and exit the editor. Then run: +Open the file @/etc/default/grub@ in an editor. Find where the string @GRUB_CMDLINE_LINUX@ is set. Add @cgroup_enable=memory swapaccount=1@ to that string. Save the file and exit the editor. Then run: 
~$ sudo update-grub
-On Red Hat-based systems, run: +h2(#install_docker). Install Docker + +Compute nodes must have Docker installed to run containers. This requires a relatively recent version of Linux (at least upstream version 3.10, or a distribution version with the appropriate patches backported). Follow the "Docker Engine installation documentation":https://docs.docker.com/install/ for your distribution. + +Make sure Docker is enabled to start on boot: -
~$ sudo grubby --update-kernel=ALL --args='cgroup_enable=memory swapaccount=1'
+
# systemctl enable --now docker
 

 
 
-Finally, reboot the system to make these changes effective.
-
-h2. Create a project for Docker images
+h2(#configure_docker_daemon). Configure the Docker daemon
 
-Here we create a default project for the standard Arvados Docker images, and give all users read access to it. The project is owned by the system user.
+Depending on your anticipated workload or cluster configuration, you may need to tweak Docker options.
 
-
-
~$ uuid_prefix=`arv --format=uuid user current | cut -d- -f1`
-~$ project_uuid=`arv --format=uuid group create --group "{\"owner_uuid\":\"$uuid_prefix-tpzed-000000000000000\", \"group_class\":\"project\", \"name\":\"Arvados Standard Docker Images\"}"`
-~$ echo "Arvados project uuid is '$project_uuid'"
-~$ read -rd $'\000' newlink <<EOF; arv link create --link "$newlink"
-{
- "tail_uuid":"$all_users_group_uuid",
- "head_uuid":"$project_uuid",
- "link_class":"permission",
- "name":"can_read"
-}
-EOF
-

-
-h2. Download and tag the latest arvados/jobs docker image
-
-In order to start workflows from workbench, there needs to be Docker image tagged @arvados/jobs:latest@. The following command downloads the latest arvados/jobs image from Docker Hub, loads it into Keep, and tags it as 'latest'.  In this example @$project_uuid@ should be the UUID of the "Arvados Standard Docker Images" project.
+For information about how to set configuration options for the Docker daemon, see https://docs.docker.com/config/daemon/systemd/
 
-
-
~$ arv-keepdocker --pull arvados/jobs latest --project-uuid $project_uuid
-

+h3. Changing ulimits
 
-If the image needs to be downloaded from Docker Hub, the command can take a few minutes to complete, depending on available network bandwidth.
+Docker containers inherit ulimits from the Docker daemon.  However, the ulimits for a single Unix daemon may not accommodate a long-running Crunch job.  You may want to increase default limits for compute containers by passing @--default-ulimit@ options to the Docker daemon.  For example, to allow containers to open 10,000 files, set @--default-ulimit nofile=10000:10000@.
diff --git a/doc/_includes/_install_compute_fuse.liquid b/doc/_includes/_install_compute_fuse.liquid
index 449c32c266..95679f3fa1 100644
--- a/doc/_includes/_install_compute_fuse.liquid
+++ b/doc/_includes/_install_compute_fuse.liquid
@@ -4,20 +4,14 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-h2. Configure FUSE
+h2(#fuse). Update fuse.conf
 
 FUSE must be configured with the @user_allow_other@ option enabled for Crunch to set up Keep mounts that are readable by containers.  Install this file as @/etc/fuse.conf@:
 
 
 
-# Set the maximum number of FUSE mounts allowed to non-root users.
-# The default is 1000.
-#
-#mount_max = 1000
-
 # Allow non-root users to specify the 'allow_other' or 'allow_root'
 # mount options.
-#
 user_allow_other
 

 
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_docker_cleaner.liquid b/doc/_includes/_install_docker_cleaner.liquid
index 5b0e1551ed..f8e9e049df 100644
--- a/doc/_includes/_install_docker_cleaner.liquid
+++ b/doc/_includes/_install_docker_cleaner.liquid
@@ -4,13 +4,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-h2. Configure the Docker cleaner
+h2(#docker-cleaner). Update docker-cleaner.json
 
-The arvados-docker-cleaner program removes least recently used Docker images as needed to keep disk usage below a configured limit.
-
-{% include 'notebox_begin' %}
-This also removes all containers as soon as they exit, as if they were run with @docker run --rm@. If you need to debug or inspect containers after they stop, temporarily stop arvados-docker-cleaner or configure it with @"RemoveStoppedContainers":"never"@.
-{% include 'notebox_end' %}
+The @arvados-docker-cleaner@ program removes least recently used Docker images as needed to keep disk usage below a configured limit.
 
 Create a file @/etc/arvados/docker-cleaner/docker-cleaner.json@ in an editor, with the following contents.
 
@@ -24,11 +20,6 @@ Create a file @/etc/arvados/docker-cleaner/docker-cleaner.json@ in an editor, wi
 
 *Choosing a quota:* Most deployments will want a quota that's at least 10G.  From there, a larger quota can help reduce compute overhead by preventing reloading the same Docker image repeatedly, but will leave less space for other files on the same storage (usually Docker volumes).  Make sure the quota is less than the total space available for Docker images.
 
-Restart the service after updating the configuration file.
-
-
-
~$ sudo systemctl restart arvados-docker-cleaner
-

-
-
-*If you are using a different daemon supervisor,* or if you want to test the daemon in a terminal window, run @arvados-docker-cleaner@. Run @arvados-docker-cleaner --help@ for more configuration options.
+{% include 'notebox_begin' %}
+This also removes all containers as soon as they exit, as if they were run with @docker run --rm@. If you need to debug or inspect containers after they stop, temporarily stop arvados-docker-cleaner or configure it with @"RemoveStoppedContainers":"never"@.
+{% include 'notebox_end' %}
diff --git a/doc/_includes/_install_git_curl.liquid b/doc/_includes/_install_git_curl.liquid
deleted file mode 100644
index 40b95d314d..0000000000
--- a/doc/_includes/_install_git_curl.liquid
+++ /dev/null
@@ -1,19 +0,0 @@
-{% comment %}
-Copyright (C) The Arvados Authors. All rights reserved.
-
-SPDX-License-Identifier: CC-BY-SA-3.0
-{% endcomment %}
-
-On a Debian-based system, install the following packages:
-
-
-
~$ sudo apt-get install git curl
-

-
-
-On a Red Hat-based system, install the following packages:
-
-
-
~$ sudo yum install git curl
-

-
diff --git a/doc/_includes/_install_packages.liquid b/doc/_includes/_install_packages.liquid
new file mode 100644
index 0000000000..bfac32d834
--- /dev/null
+++ b/doc/_includes/_install_packages.liquid
@@ -0,0 +1,24 @@
+{% comment %}
+packages_to_install should be a list
+fallback on arvados_component if not defined
+{% endcomment %}
+
+{% if package_to_install == nil %}
+  {% assign packages_to_install = arvados_component | split: " " %}
+{% endif %}
+
+h2(#install-packages). Install {{packages_to_install | join: " and " }}
+
+h3. Red Hat and Centos
+
+
+
# yum install {{packages_to_install | join: " "}}
+

+
+
+h3. Debian and Ubuntu
+
+
+
# apt-get install {{packages_to_install  | join " "}}
+

+
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..c9430515f1 100644
--- a/doc/_includes/_install_redhat_key.liquid
+++ b/doc/_includes/_install_redhat_key.liquid
@@ -4,12 +4,13 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-The Curoverse signing key fingerprint is
+The Arvados signing key fingerprint is
 
 
-
    
-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
+
    pub   rsa2048 2010-11-15 [SC]
+      B2DA 2991 656E B4A5 0314  CA2B 5716 5911 1078 ECD7
+uid           [ unknown] Arvados Automatic Signing Key 
+uid           [ unknown] Curoverse, Inc Automatic Signing Key 
+sub   rsa2048 2010-11-15 [E]
 
    
 
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/_includes/_mount_types.liquid b/doc/_includes/_mount_types.liquid
index de417e1488..86e05be866 100644
--- a/doc/_includes/_mount_types.liquid
+++ b/doc/_includes/_mount_types.liquid
@@ -34,7 +34,7 @@ At container startup, the target path will have the source tree indicated by the
 }
 
    |
 |Temporary directory|@tmp@|@"capacity"@: capacity (in bytes) of the storage device.
-@"device_type"@ (optional, default "network"): one of @{"ram", "ssd", "disk", "network"}@ indicating the acceptable level of performance.
+@"device_type"@ (optional, default "network"): one of @{"ram", "ssd", "disk", "network"}@ indicating the acceptable level of performance. (*note: not yet implemented as of v1.5*)
 At container startup, the target path will be empty. When the container finishes, the content will be discarded. This will be backed by a storage mechanism no slower than the specified type.|
    {
  "kind":"tmp",
  "capacity":100000000000
diff --git a/doc/_includes/_navbar_left.liquid b/doc/_includes/_navbar_left.liquid
index d3ac2932d3..2e18980f23 100644
--- a/doc/_includes/_navbar_left.liquid
+++ b/doc/_includes/_navbar_left.liquid
@@ -4,6 +4,32 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+{% assign highlighturl = "" %}
+{% for section in site.navbar[page.navsection] %}
+  {% for entry in section %}
+    {% comment %}
+    Want to highlight the current page on the left nav.
+    But some pages have been renamed with a symlink from the old page to the new one.
+    Then the URL won't match.
+    So if the URL doesn't match, as a fallback look for a page with a matching title.
+    {% endcomment %}
+
+    {% for item in entry[1] %}
+      {% if site.pages[item].url == page.url %}
+        {% assign highlighturl = site.pages[item].url %}
+      {% endif %}
+    {% endfor %}
+
+    {% if highlighturl == "" %}
+      {% for item in entry[1] %}
+        {% if site.pages[item].title == page.title %}
+          {% assign highlighturl = site.pages[item].url %}
+        {% endif %}
+      {% endfor %}
+    {% endif %}
+  {% endfor %}
+{% endfor %}
+
 
    
   
    
     
      
@@ -12,9 +38,9 @@ SPDX-License-Identifier: CC-BY-SA-3.0
       
    1. {{ entry[0] }}
 	
        
           {% for item in entry[1] %}
-          {% assign p = site.pages[item] %}
-          
      1. 
-            {{ p.title }}
        2. 
+            {% assign p = site.pages[item] %}
+            
      2. 
+              {{ p.title }}
        3. 
           {% endfor %}
         
      
         {% endfor %}
diff --git a/doc/_includes/_navbar_top.liquid b/doc/_includes/_navbar_top.liquid
index 39c70471a3..c69a2efbec 100644
--- a/doc/_includes/_navbar_top.liquid
+++ b/doc/_includes/_navbar_top.liquid
@@ -36,7 +36,7 @@ SPDX-License-Identifier: CC-BY-SA-3.0
         
    2. arvados.org »
      3. 
       
 
-      
      
+      
      
         
      
           
      
             
@@ -48,5 +48,24 @@ SPDX-License-Identifier: CC-BY-SA-3.0
         
       
      
     
      
+
+   
+
+   
+
   
      
 
    
diff --git a/doc/_includes/_restart_api.liquid b/doc/_includes/_restart_api.liquid
new file mode 100644
index 0000000000..c3e0330b87
--- /dev/null
+++ b/doc/_includes/_restart_api.liquid
@@ -0,0 +1,8 @@
+h2(#restart-api). Restart the API server and controller
+
+*Make sure the cluster config file is up to date on the API server host* then restart the API server and controller processes to ensure the configuration changes are visible to the whole cluster.
+
+
+
    # systemctl restart nginx arvados-controller
+
    
+    
diff --git a/doc/_includes/_start_service.liquid b/doc/_includes/_start_service.liquid
new file mode 100644
index 0000000000..27c42c94c9
--- /dev/null
+++ b/doc/_includes/_start_service.liquid
@@ -0,0 +1,15 @@
+h2(#start-service). Start the service
+
+
+
    # systemctl enable --now {{arvados_component}}
+# systemctl status {{arvados_component}}
+[...]
+
    
+    
+
+If @systemctl status@ indicates it is not running, use @journalctl@ to check logs for errors:
+
+
+
    # journalctl -n12 --unit {{arvados_component}}
+
    
+    
diff --git a/doc/_layouts/default.html.liquid b/doc/_layouts/default.html.liquid
index 7c6d36ec46..74b1a072a8 100644
--- a/doc/_layouts/default.html.liquid
+++ b/doc/_layouts/default.html.liquid
@@ -22,6 +22,8 @@ SPDX-License-Identifier: CC-BY-SA-3.0
     
     
     
+    
+    
     
 
     
@@ -81,7 +85,8 @@ SPDX-License-Identifier: CC-BY-SA-3.0
     {{ content }}
     {% else %}
 
-    
    
+    
    
+
       
    
         {% include 'navbar_left' %}
         
    
@@ -95,8 +100,6 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 
     
    
     {% endif %}
-    
-