From 8bcf52e06c1c7cfa156a9191bc9e6e678e5d67d7 Mon Sep 17 00:00:00 2001 From: Peter Amstutz Date: Fri, 30 Sep 2022 11:28:12 -0400 Subject: [PATCH] 19215: Make it so the manual install docs recommend using diagnostics. Arvados-DCO-1.1-Signed-off-by: Peter Amstutz --- doc/install/arvbox.html.textile.liquid | 1 + doc/install/diagnostics.html.textile.liquid | 5 +++++ .../install-keep-web.html.textile.liquid | 22 +++++++++++-------- .../install-keepproxy.html.textile.liquid | 4 ++++ .../install-keepstore.html.textile.liquid | 7 ++++-- .../install-webshell.html.textile.liquid | 4 ++++ doc/install/install-ws.html.textile.liquid | 4 ++++ .../salt-multi-host.html.textile.liquid | 2 ++ .../salt-single-host.html.textile.liquid | 21 ++++++++++++------ doc/user/copying/copying.html.textile.liquid | 8 ++++--- 10 files changed, 57 insertions(+), 21 deletions(-) diff --git a/doc/install/arvbox.html.textile.liquid b/doc/install/arvbox.html.textile.liquid index 52dec90671..20e1c48eee 100644 --- a/doc/install/arvbox.html.textile.liquid +++ b/doc/install/arvbox.html.textile.liquid @@ -29,6 +29,7 @@ $ ./arvbox start localdemo Arvados-in-a-box starting Waiting for workbench2 websockets workbench webshell keep-web controller keepproxy api keepstore1 arv-git-httpd keepstore0 sdk vm ... + ... Your Arvados-in-a-box is ready! diff --git a/doc/install/diagnostics.html.textile.liquid b/doc/install/diagnostics.html.textile.liquid index f139ff6795..7d03e8b0d2 100644 --- a/doc/install/diagnostics.html.textile.liquid +++ b/doc/install/diagnostics.html.textile.liquid @@ -12,6 +12,11 @@ SPDX-License-Identifier: CC-BY-SA-3.0 The @diagnostics@ subcommand of @arvados-client@ performs a variety of checks to help confirm that your Arvados installation has been properly configured. It is extremely helpful to validate that your install is successful. +Depending on where you are running the installer, you need to provide @-internal-client@ or @-external-client@. + +* If you are running the diagnostics from one of the Arvados machines inside the private network, you want @-internal-client@. +* If you running the diagnostics from your workstation outside of the private network, you should use @-external-client@. + Here is an example of it in action: 
diff --git a/doc/install/install-keep-web.html.textile.liquid b/doc/install/install-keep-web.html.textile.liquid
index 1ba9fc522f..b3c6386129 100644
--- a/doc/install/install-keep-web.html.textile.liquid
+++ b/doc/install/install-keep-web.html.textile.liquid
@@ -173,18 +173,22 @@ In such cases -- for example, a site which is not reachable from the internet, w
 
 h2(#confirm-working). Confirm working installation
 
-
-$ curl -H "Authorization: Bearer $system_root_token" https://download.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/_/hello.txt
-

+We recommend using the "Cluster diagnostics tool.":diagnostics.html
+
+Here are some other checks you can perform manually.
+
+
+
$ curl -H "Authorization: Bearer $system_root_token" https://download.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/_/hello.txt

+
 
 If wildcard collections domains are configured:
 
-
-$ curl -H "Authorization: Bearer $system_root_token" https://59389a8f9ee9d399be35462a0f92541c-53.collections.ClusterID.example.com/hello.txt
-

+
+
$ curl -H "Authorization: Bearer $system_root_token" https://59389a8f9ee9d399be35462a0f92541c-53.collections.ClusterID.example.com/hello.txt

+
 
 If using a single collections preview domain:
 
-
-$ curl https://collections.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/t=$system_root_token/_/hello.txt
-

+
+
$ curl https://collections.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/t=$system_root_token/_/hello.txt

+
diff --git a/doc/install/install-keepproxy.html.textile.liquid b/doc/install/install-keepproxy.html.textile.liquid
index 2d32a2455c..999883b658 100644
--- a/doc/install/install-keepproxy.html.textile.liquid
+++ b/doc/install/install-keepproxy.html.textile.liquid
@@ -92,6 +92,10 @@ Note: if the Web uploader is failing to upload data and there are no logs from k
 
 h2(#confirm-working). Confirm working installation
 
+We recommend using the "Cluster diagnostics tool.":diagnostics.html  Because Keepproxy is specifically a gateway used by outside clients, for this test you should run the diagnostics from a client machine outside the Arvados private network, and provide the @-external-client@ parameter.
+
+Here are some other checks you can perform manually.
+
 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).
 
 @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ must be set in the environment.
diff --git a/doc/install/install-keepstore.html.textile.liquid b/doc/install/install-keepstore.html.textile.liquid
index 3cb922642e..ff08b532d5 100644
--- a/doc/install/install-keepstore.html.textile.liquid
+++ b/doc/install/install-keepstore.html.textile.liquid
@@ -79,6 +79,10 @@ Add each keepstore server to the @Services.Keepstore@ section of @/etc/arvados/c
 
 h2(#confirm-working). Confirm working installation
 
+We recommend using the "Cluster diagnostics tool.":diagnostics.html
+
+Here are some other checks you can perform manually.
+
 Log into a host that is on your private Arvados network.  The host should be able to contact your your keepstore servers (eg keep[0-9].ClusterID.example.com).
 
 @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ must be set in the environment.
@@ -92,8 +96,7 @@ Install the "Command line SDK":{{site.baseurl}}/sdk/cli/install.html
 Check that the keepstore server is in the @keep_service@ "accessible" list:
 
 
-

-$ arv keep_service accessible
+
$ arv keep_service accessible
 [...]
 

 
diff --git a/doc/install/install-webshell.html.textile.liquid b/doc/install/install-webshell.html.textile.liquid
index 8275a2a831..95254abdea 100644
--- a/doc/install/install-webshell.html.textile.liquid
+++ b/doc/install/install-webshell.html.textile.liquid
@@ -183,4 +183,8 @@ session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux
 
 h2(#confirm-working). Confirm working installation
 
+We recommend using the "Cluster diagnostics tool.":diagnostics.html
+
+Here are some other checks you can perform manually.
+
 A user should now be able to log in to the shell server, using webshell via workbench. Please refer to "Accessing an Arvados VM with Webshell":{{site.baseurl}}/user/getting_started/vm-login-with-webshell.html
diff --git a/doc/install/install-ws.html.textile.liquid b/doc/install/install-ws.html.textile.liquid
index 2b982504f2..74c4cf3a92 100644
--- a/doc/install/install-ws.html.textile.liquid
+++ b/doc/install/install-ws.html.textile.liquid
@@ -73,6 +73,10 @@ server {
 
 h2(#confirm). Confirm working installation
 
+We recommend using the "Cluster diagnostics tool.":diagnostics.html
+
+Here are some other checks you can perform manually.
+
 Confirm the service is listening on its assigned port and responding to requests.
 
 
diff --git a/doc/install/salt-multi-host.html.textile.liquid b/doc/install/salt-multi-host.html.textile.liquid
index d4aa39b9f5..f5d359e3ca 100644
--- a/doc/install/salt-multi-host.html.textile.liquid
+++ b/doc/install/salt-multi-host.html.textile.liquid
@@ -104,6 +104,8 @@ You will need a DNS entry for each service.  In the default configuration these
 # @webshell.${CLUSTER}.${DOMAIN}@
 # @shell.${CLUSTER}.${DOMAIN}@
 
+This is described in more detail in "DNS entries and TLS certificates":install-manual-prerequisites.html#dnstls.
+
 h3. Additional prerequisites when preparing machines to run the installer
 
 # From the account where you are performing the install, passwordless @ssh@ to each machine
diff --git a/doc/install/salt-single-host.html.textile.liquid b/doc/install/salt-single-host.html.textile.liquid
index 968af24cce..e62b7baae7 100644
--- a/doc/install/salt-single-host.html.textile.liquid
+++ b/doc/install/salt-single-host.html.textile.liquid
@@ -41,13 +41,16 @@ h3. Cluster ID and base domain
 
 Choose a 5-character cluster identifier that will represent the cluster.  Here are "guidelines on choosing a cluster identifier":../architecture/federation.html#cluster_id .  Only lowercase letters and digits 0-9 are allowed.  Examples will use @xarv1@ or ${CLUSTER}, you should substitute the cluster id you have selected.
 
-Determine if you will use a single hostname, or multiple hostnames.  A single hostname is simpler (and can even be used without a hostname at all, just a bare IP address), however multiple hostnames may make it easier to migrate to a multi-host production configuration in the future.
+Determine if you will use a single hostname, or multiple hostnames.
 
-Determine if you are using multiple hostnames, determine the base domain for the cluster.  This will be referred to as ${DOMAIN}
+* Single hostname is simpler to set up and can even be used without a hostname at all, just a bare IP address.
+* Multiple hostnames is more similar to the recommended production configuration may make it easier to migrate to a multi-host production configuration in the future, but is more complicated as it requires adding a number of DNS entries.
+
+If you are using multiple hostnames, determine the base domain for the cluster.  This will be referred to as ${DOMAIN}
 
 For example, if CLUSTER is "xarv1" and DOMAIN is "example.com", then "controller.${CLUSTER}.${DOMAIN}" means "controller.xargv1.example.com".
 
-h3. Dedicated machine
+h3. Machine specification
 
 You will need a dedicated (virtual) machine for your Arvados server with at least 2 cores and 8 GiB of RAM (4+ cores / 16+ GiB recommended) running a supported Linux distribution:
 
@@ -55,7 +58,9 @@ You will need a dedicated (virtual) machine for your Arvados server with at leas
 
 h3(#DNS). DNS hostnames for each service
 
-If you are using the multi-hostname configuration, you will need a DNS entry for each service.  If you are using a single hostname for all services (they will be distingushed by listening port), you can skip this section.
+If you are using a single hostname for all services (they will be distingushed by listening port), you can skip this section.
+
+If you are using the multi-hostname configuration, you will need a DNS entry for each service.  If you are using "bring-your-own" TLS certificates, your certificate will need to include all of these hostnames.
 
 In the default configuration these are:
 
@@ -71,6 +76,8 @@ In the default configuration these are:
 # @webshell.${CLUSTER}.${DOMAIN}@
 # @shell.${CLUSTER}.${DOMAIN}@
 
+This is described in more detail in "DNS entries and TLS certificates":install-manual-prerequisites.html#dnstls.
+
 h3. Additional prerequisites
 
 # Passwordless @sudo@ access on the account where you are doing the install
@@ -80,7 +87,7 @@ this usually means adding the account to the @sudo@ group and having a rule like
 # Port 443 reachable by clients
 # For the single-host install, ports 8800-8805 also need to be reachable from your client (configurable in @local.params@, see below)
 # When using "Let's Encrypt":#lets-encrypt port 80 needs to be reachable from everywhere on the internet
-# When using "bring your own certificate":#bring-your-own)an SSL certificate matching the hostname in use
+# When using "bring your own certificate":#bring-your-own you need TLS certificate(s) covering the hostname(s) used by Arvados
 
 h2(#download). Download the installer
 
@@ -201,9 +208,9 @@ For this reason, the installer has the option to create its own a root certifica
 
 h2(#initial_user). Initial user and login
 
-At this point you should be able to log into the Arvados cluster. The initial URL for the single hostname install will be:
+At this point you should be able to log into the Arvados cluster. The initial URL for the single hostname install will use the hostname or IP address you put in @HOSTNAME_EXT@:
 
-https://@HOSTNAME_EXT@
+https://${HOSTNAME_EXT}
 
 For the multi-hostname install, it will be:
 
diff --git a/doc/user/copying/copying.html.textile.liquid b/doc/user/copying/copying.html.textile.liquid
index 3785ef5016..8d4201cef9 100644
--- a/doc/user/copying/copying.html.textile.liquid
+++ b/doc/user/copying/copying.html.textile.liquid
@@ -9,8 +9,10 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-Server-side components of Arvados contained in the apps/ and services/ directories, including the API Server, Workbench, Keep, and Crunch, are licenced under the "GNU Affero General Public License version 3":agpl-3.0.html.
+Every source file has @SPDX-License-Identifier@ header that identifies the exact copyright license that applies to that file.
 
-The Arvados client Software Development Kits contained in the sdk/ directory, example scripts in the crunch_scripts/ directory, and code samples in the Aravados documentation are licensed under the "Apache License, Version 2.0":LICENSE-2.0.html
+In general, Arvados server-side components and system administration tools contained in the @services/@, @lib/@, @apps/@, @cmd/@, and @tools/@ directories, including the API Server, Workbench, Keep, and Crunch, are licenced under the "GNU Affero General Public License version 3":agpl-3.0.html.
 
-The Arvados Documentation located in the doc/ directory is licensed under the "Creative Commons Attribution-Share Alike 3.0 United States":by-sa-3.0.html
+The Arvados client tools and Software Development Kits contained in the @sdk/@ directory and code samples in the Aravados documentation are licensed under the "Apache License, Version 2.0":LICENSE-2.0.html.
+
+The Arvados Documentation located in the @doc/@ directory is licensed under the "Creative Commons Attribution-Share Alike 3.0 United States":by-sa-3.0.html.
-- 
2.30.2