From 96333dffe4b0aaf58c368ed590697fc3ed5e4b48 Mon Sep 17 00:00:00 2001
From: Ward Vandewege <ward@curii.com>
Date: Fri, 21 Jan 2022 15:16:32 -0500
Subject: [PATCH] Documentation tweaks for the Salt installer.

refs #18658

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <ward@curii.com>
---
 doc/_includes/_install_custom_certificates.liquid |  2 +-
 doc/install/salt-multi-host.html.textile.liquid   |  2 ++
 doc/install/salt-single-host.html.textile.liquid  |  2 ++
 ....params.example.single_host_multiple_hostnames | 15 +++++++++------
 ...cal.params.example.single_host_single_hostname | 15 +++++++++------
 5 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/doc/_includes/_install_custom_certificates.liquid b/doc/_includes/_install_custom_certificates.liquid
index 74bc009b89..4a4aff5cfb 100644
--- a/doc/_includes/_install_custom_certificates.liquid
+++ b/doc/_includes/_install_custom_certificates.liquid
@@ -17,7 +17,7 @@ The script expects cert/key files with these basenames (matching the role except
 * "collections"      # Part of keepweb
 * "keepproxy"
 
-Ie., for 'keepproxy', the script will lookup for
+Ie., for 'keepproxy', the script will look for
 
 <notextile>
 <pre><code>${CUSTOM_CERTS_DIR}/keepproxy.crt
diff --git a/doc/install/salt-multi-host.html.textile.liquid b/doc/install/salt-multi-host.html.textile.liquid
index 83a60c9fee..c3d6a92b5d 100644
--- a/doc/install/salt-multi-host.html.textile.liquid
+++ b/doc/install/salt-multi-host.html.textile.liquid
@@ -121,6 +121,8 @@ When you finished customizing the configuration, you are ready to copy the files
 
 <notextile>
 <pre><code>scp -r provision.sh local* user@host:
+# if you use custom certificates (not Let's Encrypt), make sure to copy those too:
+# scp -r certs user@host:
 ssh user@host sudo ./provision.sh --roles comma,separated,list,of,roles,to,apply
 </code></pre>
 </notextile>
diff --git a/doc/install/salt-single-host.html.textile.liquid b/doc/install/salt-single-host.html.textile.liquid
index 9147f25a19..ce70a30d46 100644
--- a/doc/install/salt-single-host.html.textile.liquid
+++ b/doc/install/salt-single-host.html.textile.liquid
@@ -80,6 +80,8 @@ When you finished customizing the configuration, you are ready to copy the files
 
 <notextile>
 <pre><code>scp -r provision.sh local* tests user@host:
+# if you use custom certificates (not Let's Encrypt), make sure to copy those too:
+# scp -r certs user@host:
 ssh user@host sudo ./provision.sh
 </code></pre>
 </notextile>
diff --git a/tools/salt-install/local.params.example.single_host_multiple_hostnames b/tools/salt-install/local.params.example.single_host_multiple_hostnames
index 11ebc119f7..76e88786bc 100644
--- a/tools/salt-install/local.params.example.single_host_multiple_hostnames
+++ b/tools/salt-install/local.params.example.single_host_multiple_hostnames
@@ -40,12 +40,15 @@ WORKBENCH_SECRET_KEY=workbenchsecretkeymushaveatleast32characters
 DATABASE_PASSWORD=please_set_this_to_some_secure_value
 
 # SSL CERTIFICATES
-# Arvados REQUIRES valid SSL to work correctly. Otherwise, some components will fail
-# to communicate and can silently drop traffic. You can try to use the Letsencrypt
-# salt formula (https://github.com/saltstack-formulas/letsencrypt-formula) to try to
-# automatically obtain and install SSL certificates for your instances or set this
-# variable to "no", provide and upload your own certificates to the instances and
-# modify the 'nginx_*' salt pillars accordingly (see CUSTOM_CERTS_DIR below)
+# Arvados REQUIRES valid SSL to work correctly. Otherwise, some components will
+# fail to communicate and can silently drop traffic. Set USE_LETSENCRYPT="yes"
+# to use the Let's Encrypt salt formula
+# (https://github.com/saltstack-formulas/letsencrypt-formula) to automatically
+# obtain and install SSL certificates for your hostname(s).
+#
+# Alternatively, set this variable to "no" and provide and upload your own
+# certificates to the instances and modify the 'nginx_*' salt pillars
+# accordingly
 USE_LETSENCRYPT="no"
 
 # If you going to provide your own certificates for Arvados, the provision script can
diff --git a/tools/salt-install/local.params.example.single_host_single_hostname b/tools/salt-install/local.params.example.single_host_single_hostname
index ae9804863f..fc2db58c01 100644
--- a/tools/salt-install/local.params.example.single_host_single_hostname
+++ b/tools/salt-install/local.params.example.single_host_single_hostname
@@ -49,12 +49,15 @@ WORKBENCH_SECRET_KEY=workbenchsecretkeymushaveatleast32characters
 DATABASE_PASSWORD=please_set_this_to_some_secure_value
 
 # SSL CERTIFICATES
-# Arvados REQUIRES valid SSL to work correctly. Otherwise, some components will fail
-# to communicate and can silently drop traffic. You can try to use the Letsencrypt
-# salt formula (https://github.com/saltstack-formulas/letsencrypt-formula) to try to
-# automatically obtain and install SSL certificates for your instances or set this
-# variable to "no", provide and upload your own certificates to the instances and
-# modify the 'nginx_*' salt pillars accordingly
+# Arvados REQUIRES valid SSL to work correctly. Otherwise, some components will
+# fail to communicate and can silently drop traffic. Set USE_LETSENCRYPT="yes"
+# to use the Let's Encrypt salt formula
+# (https://github.com/saltstack-formulas/letsencrypt-formula) to automatically
+# obtain and install SSL certificates for your hostname(s).
+#
+# Alternatively, set this variable to "no" and provide and upload your own
+# certificates to the instances and modify the 'nginx_*' salt pillars
+# accordingly
 USE_LETSENCRYPT="no"
 
 # The directory to check for the config files (pillars, states) you want to use.
-- 
2.30.2