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!
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:
<pre>
h2(#confirm-working). Confirm working installation
-<notextile><code><pre>
-$ curl -H "Authorization: Bearer $system_root_token" https://<span class="userinput">download.ClusterID.example.com</span>/c=59389a8f9ee9d399be35462a0f92541c-53/_/hello.txt
-</code></pre></notextile>
+We recommend using the "Cluster diagnostics tool.":diagnostics.html
+
+Here are some other checks you can perform manually.
+
+<notextile>
+<pre><code>$ curl -H "Authorization: Bearer $system_root_token" https://<span class="userinput">download.ClusterID.example.com</span>/c=59389a8f9ee9d399be35462a0f92541c-53/_/hello.txt</code></pre>
+</notextile>
If wildcard collections domains are configured:
-<notextile><code><pre>
-$ curl -H "Authorization: Bearer $system_root_token" https://<span class="userinput">59389a8f9ee9d399be35462a0f92541c-53.collections.ClusterID.example.com</span>/hello.txt
-</code></pre></notextile>
+<notextile>
+<pre><code>$ curl -H "Authorization: Bearer $system_root_token" https://<span class="userinput">59389a8f9ee9d399be35462a0f92541c-53.collections.ClusterID.example.com</span>/hello.txt</code></pre>
+</notextile>
If using a single collections preview domain:
-<notextile><code><pre>
-$ curl https://<span class="userinput">collections.ClusterID.example.com</span>/c=59389a8f9ee9d399be35462a0f92541c-53/t=$system_root_token/_/hello.txt
-</code></pre></notextile>
+<notextile>
+<pre><code>$ curl https://<span class="userinput">collections.ClusterID.example.com</span>/c=59389a8f9ee9d399be35462a0f92541c-53/t=$system_root_token/_/hello.txt</code></pre>
+</notextile>
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.
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.
Check that the keepstore server is in the @keep_service@ "accessible" list:
<notextile>
-<pre><code>
-$ <span class="userinput">arv keep_service accessible</span>
+<pre><code>$ <span class="userinput">arv keep_service accessible</span>
[...]
</code></pre>
</notextile>
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
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.
<notextile>
# @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
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:
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:
# @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
# 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
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:
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.