SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-The Curoverse signing key fingerprint is
+The Arvados signing key fingerprint is
<notextile>
-<pre><code>pub 2048R/1078ECD7 2010-11-15 Curoverse, Inc Automatic Signing Key <sysadmin@curoverse.com>
- Key fingerprint = B2DA 2991 656E B4A5 0314 CA2B 5716 5911 1078 ECD7
-sub 2048R/5A8C5A93 2010-11-15
+<pre><code>pub rsa2048 2010-11-15 [SC]
+ B2DA 2991 656E B4A5 0314 CA2B 5716 5911 1078 ECD7
+uid [ unknown] Arvados Automatic Signing Key <sysadmin@arvados.org>
+uid [ unknown] Curoverse, Inc Automatic Signing Key <sysadmin@curoverse.com>
+sub rsa2048 2010-11-15 [E]
</code></pre>
</notextile>
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
+{% include 'notebox_begin_warning' %}
_New installations of Arvados 1.5+ can skip this section_
+{% include 'notebox_end' %}
Arvados 1.5 migrates to a centralized configuration file for all components. The centralized Arvados configuration is @/etc/arvados/config.yml@. Components that support the new centralized configuration are listed below. During the migration period, legacy configuration files are still loaded and take precedence over the centralized configuration file.
h2. keepstore, keep-web, crunch-dispatch-slurm, arvados-ws, keepproxy, arv-git-httpd, keep-balance
-The legacy config for each component (loaded from @/etc/arvados/component/component.yml@ or a different location specified via -legacy-component-config command line argument) takes precedence over the centralized config. After you migrate everything from the legacy config to the centralized config, you should delete @/etc/arvados/component/component.yml@ and/or stop using the corresponding -legacy-component-config argument.
+The legacy config for each component (loaded from @/etc/arvados/component/component.yml@ or a different location specified via the -legacy-component-config command line argument) takes precedence over the centralized config. After you migrate everything from the legacy config to the centralized config, you should delete @/etc/arvados/component/component.yml@ and/or stop using the corresponding -legacy-component-config argument.
To migrate a component configuration, do this on each node that runs an Arvados service:
After migrating and removing all legacy config files, make sure the @/etc/arvados/config.yml@ file is identical across all system nodes -- API server, keepstore, etc. -- and restart all services to make sure they are using the latest configuration.
-h2. Node manager
+h2. Cloud installations only: node manager
Node manager is deprecated and replaced by @arvados-dispatch-cloud@. No automated config migration is available. Follow the instructions to "install the cloud dispatcher":../install/install-dispatch-cloud.html
<notextile>
<pre><code>Clusters:
- <span class="userinput">uuid_prefix</span>:
+ <span class="userinput">ClusterID</span>:
# Token to be included in all healthcheck requests. Disabled by default.
# Server expects request header of the format "Authorization: Bearer xxx"
ManagementToken: xxx
<pre>
Clusters:
- uuid_prefix:
+ ClusterID:
Containers:
UsePreemptibleInstances: true
InstanceTypes:
When @UsePreemptibleInstances@ is enabled, child containers (workflow steps) will automatically be made preemptible. Note that because preempting the workflow runner would cancel the entire workflow, the workflow runner runs in a reserved (non-preemptible) instance.
-If you are using "crunch-dispatch-cloud":{{site.baseurl}}/install/install-dispatch-cloud.html no additional configuration is required.
+If you are using "arvados-dispatch-cloud":{{site.baseurl}}/install/install-dispatch-cloud.html no additional configuration is required.
If you are using the legacy Nodemanager, "see below":#nodemanager .
See "Migrating Configuration":config-migration.html for notes on migrating legacy per-component configuration files to the new centralized @/etc/arvados/config.yml@. To ensure a smooth transition, the per-component config files continue to be read, and take precedence over the centralized configuration.
-h4. Node manager replaced by arvados-dispatch-cloud
+h4. Cloud installations only: node manager replaced by arvados-dispatch-cloud
Node manager is deprecated and replaced by @arvados-dispatch-cloud@. No automated config migration is available. Follow the instructions to "install the cloud dispatcher":../install/install-dispatch-cloud.html
Commit "1e2ace5":https://dev.arvados.org/projects/arvados/repository/revisions/1e2ace5 changes recommended config for keep-web (see "#5824":https://dev.arvados.org/issues/5824)
-* proxy/dns/ssl config should be updated to route "https://download.uuid_prefix.arvadosapi.com/" requests to keep-web (alongside the existing "collections" routing)
-* keep-web command line adds @-attachment-only-host download.uuid_prefix.arvadosapi.com@
+* proxy/dns/ssl config should be updated to route "https://download.ClusterID.example.com/" requests to keep-web (alongside the existing "collections" routing)
+* keep-web command line adds @-attachment-only-host download.ClusterID.example.com@
* Workbench config adds @keep_web_download_url@
* More info on the (still beta/non-TOC-linked) "keep-web doc page":http://doc.arvados.org/install/install-keep-web.html
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 @#@ .
+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 follows 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@.
# If the AccessViaHosts section is empty or omitted, all
# keepstore servers will have read/write access to the
# volume.
- "http://<span class="userinput">keep0.uuid_prefix.example.com</span>:25107/": {}
- "http://<span class="userinput">keep1.uuid_prefix.example.com</span>:25107/": {ReadOnly: true}
+ "http://<span class="userinput">keep0.ClusterID.example.com</span>:25107/": {}
+ "http://<span class="userinput">keep1.ClusterID.example.com</span>:25107/": {ReadOnly: true}
Driver: <span class="userinput">Azure</span>
DriverParameters:
<span class="userinput">ClusterID</span>-nyw5e-<span class="userinput">000000000000001</span>:
AccessViaHosts:
- "http://keep1.<span class="userinput">ClusterID</span>.example.com:25107": {}
+ "http://<span class="userinput">keep1.ClusterID.example.com</span>:25107": {}
Driver: <span class="userinput">Directory</span>
DriverParameters:
Root: <span class="userinput">/mnt/local-disk</span>
# If the AccessViaHosts section is empty or omitted, all
# keepstore servers will have read/write access to the
# volume.
- "http://<span class="userinput">keep0.uuid_prefix.example.com</span>:25107/": {}
- "http://<span class="userinput">keep1.uuid_prefix.example.com</span>:25107/": {ReadOnly: true}
+ "http://<span class="userinput">keep0.ClusterID.example.com</span>:25107/": {}
+ "http://<span class="userinput">keep1.ClusterID.example.com</span>:25107/": {ReadOnly: true}
Driver: <span class="userinput">S3</span>
DriverParameters:
</code></pre>
</notextile>
-You can now copy the pipeline template from *qr1hi* to *your cluster*. Replace *dst_cluster* with the *uuid_prefix* of your cluster.
+You can now copy the pipeline template from *qr1hi* to *your cluster*. Replace *dst_cluster* with the *ClusterID* of your cluster.
<notextile>
<pre><code>~$ <span class="userinput"> arv-copy --no-recursive --src qr1hi --dst dst_cluster qr1hi-p5p6p-9pkaxt6qjnkxhhu</span>
If you already have an account in the Arvados Playground, you can follow the instructions in the "*Using arv-copy*":http://doc.arvados.org/user/topics/arv-copy.html user guide to get your *Current token* for source and destination clusters, and use them to create the source *qr1hi.conf* and dst_cluster.conf configuration files.
-You can now copy the pipeline template from *qr1hi* to *your cluster* with or without recursion. Replace *dst_cluster* with the *uuid_prefix* of your cluster.
+You can now copy the pipeline template from *qr1hi* to *your cluster* with or without recursion. Replace *dst_cluster* with the *ClusterID* of your cluster.
*Non-recursive copy:*
<notextile>
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
+{% include 'notebox_begin_warning' %}
+crunch-dispatch-slurm is only relevant for on premise clusters that will spool jobs to Slurm. Skip this section if you are installing a cloud cluster.
+{% include 'notebox_end' %}
+
# "Introduction":#introduction
# "Update config.yml":#update-config
# "Install crunch-dispatch-slurm":#install-packages
h2(#introduction). Introduction
-This assumes you already have a SLURM cluster, and have "set up all of your compute nodes":install-compute-node.html . For information on installing SLURM, see https://slurm.schedmd.com/quickstart_admin.html
+This assumes you already have a SLURM cluster, and have "set up all of your compute nodes":install-compute-node.html . For information on installing SLURM, see "this install guide":https://slurm.schedmd.com/quickstart_admin.html
The Arvados SLURM dispatcher can run on any node that can submit requests to both the Arvados API server and the SLURM controller (via @sbatch@). It is not resource-intensive, so you can run it on the API server node.
h2(#update-config). Update config.yml (optional)
-Crunch-dispatch-slurm reads the common configuration file at @/etc/arvados/config.yml@.
+Crunch-dispatch-slurm reads the common configuration file at @config.yml@.
The following configuration parameters are optional.
Now we need to give SLURM a configuration file. On Debian-based systems, this is installed at @/etc/slurm-llnl/slurm.conf@. On Red Hat-based systems, this is installed at @/etc/slurm/slurm.conf@. Here's an example @slurm.conf@:
<notextile>
-<pre>
-ControlMachine=uuid_prefix.your.domain
+<pre><code>
+ControlMachine=<span class="userinput">ClusterID.example.com</class>
SlurmctldPort=6817
SlurmdPort=6818
AuthType=auth/munge
NodeName=compute[0-255]
PartitionName=compute Nodes=compute[0-255] Default=YES Shared=YES
-</pre>
+</code></pre>
</notextile>
h3. SLURM configuration essentials
Each hostname in @slurm.conf@ must also resolve correctly on all SLURM worker nodes as well as the controller itself. Furthermore, the hostnames used in the configuration file must match the hostnames reported by @hostname@ or @hostname -s@ on the nodes themselves. This applies to the ControlMachine as well as the worker nodes.
For example:
-* In @slurm.conf@ on control and worker nodes: @ControlMachine=uuid_prefix.your.domain@
+* In @slurm.conf@ on control and worker nodes: @ControlMachine=ClusterID.example.com@
* In @slurm.conf@ on control and worker nodes: @NodeName=compute[0-255]@
-* In @/etc/resolv.conf@ on control and worker nodes: @search uuid_prefix.your.domain@
-* On the control node: @hostname@ reports @uuid_prefix.your.domain@
-* On worker node 123: @hostname@ reports @compute123.uuid_prefix.your.domain@
+* In @/etc/resolv.conf@ on control and worker nodes: @search ClusterID.example.com@
+* On the control node: @hostname@ reports @ClusterID.example.com@
+* On worker node 123: @hostname@ reports @compute123.ClusterID.example.com@
h3. Automatic hostname assignment
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
+{% include 'notebox_begin_warning' %}
+crunch-dispatch-slurm is only relevant for on premise clusters that will spool jobs to Slurm. Skip this section if you are installing a cloud cluster.
+{% include 'notebox_end' %}
+
h2. Test compute node setup
You should now be able to submit SLURM jobs that run in Docker containers. On the node where you're running the dispatcher, you can test this by running:
# Navigate back to the main "APIs & Services" page
# On the sidebar, click on *OAuth consent screen*
## On consent screen settings, enter your identifying details
-## Under *Authorized domains* add @yourdomain.com@
+## Under *Authorized domains* add @example.com@
## Click on *Save*.
# On the sidebar, click on *Credentials*; then click on *Create credentials*→*OAuth Client ID*
# Under *Application type* select *Web application*.
-# 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://ClusterID.yourdomain.com/@ (using Arvados-controller based login) or @https://auth.yourdomain.com/@ (for the SSO server)
-## Redirect URI should be @https://ClusterID.yourdomain.com/login@ (using Arvados-controller based login) or @https://auth.yourdomain.com/users/auth/google_oauth2/callback@ (for the SSO server)
+# You must set the authorization origins. Edit @auth.example.com@ to the appropriate hostname that you will use to access the SSO service:
+## JavaScript origin should be @https://ClusterID.example.com/@ (using Arvados-controller based login) or @https://auth.example.com/@ (for the SSO server)
+## Redirect URI should be @https://ClusterID.example.com/login@ (using Arvados-controller based login) or @https://auth.example.com/users/auth/google_oauth2/callback@ (for the SSO server)
# Copy the values of *Client ID* and *Client secret* from the Google Developers Console and add them to the appropriate configuration.
<notextile>
<pre><code> Services:
Controller:
- ExternalURL: <span class="userinput">"https://xxxxx.example.com"</span>
+ ExternalURL: <span class="userinput">"https://ClusterID.example.com"</span>
InternalURLs:
<span class="userinput">"http://localhost:8003": {}</span>
RailsAPI:
</code></pre>
</notextile>
-Replace @xxxxx.example.com@ with the hostname that you previously selected for the API server.
+Replace @ClusterID.example.com@ with the hostname that you previously selected for the API server.
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.
h2(#update-nginx). Update nginx configuration
-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".
+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 in <span class="userinput">red</span>.
<notextile>
<pre><code>proxy_http_version 1.1;
# "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 10.20.30.0/24 netmask
-# to match your private subnet.
-# TODO: Update 1.2.3.4 and add lines as necessary with the public IP
-# address of all servers that can also access the private network to
-# ensure they are not considered 'external'.
+# <span class="userinput">Following the example here, update the 10.20.30.0/24 netmask</span>
+# <span class="userinput">to match your private subnet.</span>
+# <span class="userinput">Update 1.2.3.4 and add lines as necessary with the public IP</span>
+# <span class="userinput">address of all servers that can also access the private network to</span>
+# <span class="userinput">ensure they are not considered 'external'.</span>
geo $external_client {
default 1;
server_name <span class="userinput">xxxxx.example.com</span>;
ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
# Refer to the comment about this setting in the passenger (arvados
# api server) section of your Nginx configuration.
passenger_enabled on;
- # TODO: If you are using RVM, uncomment the line below.
- # If you're using system ruby, leave it commented out.
+ # <span class="userinput">If you are using RVM, uncomment the line below.</span>
+ # <span class="userinput">If you're using system ruby, leave it commented out.</span>
#passenger_ruby /usr/local/rvm/wrappers/default/ruby;
# This value effectively limits the size of API objects users can
Confirm working controller:
-<pre>
-$ curl https://ClusterID.example.com/arvados/v1/config
-</pre>
+<notextile><pre><code>$ curl https://<span class="userinput">ClusterID.example.com</span>/arvados/v1/config
+</code></pre></notextile>
Confirm working Rails API server:
-<pre>
-$ curl https://ClusterID.example.com/discovery/v1/apis/arvados/v1/rest
-</pre>
+<notextile><pre><code>$ curl https://<span class="userinput">ClusterID.example.com</span>/discovery/v1/apis/arvados/v1/rest
+</code></pre></notextile>
Confirm that you can use the system root token to act as the system root user:
-<pre>
-$ curl -H "Authorization: Bearer $system_root_token" https://xxxxx.example.com/arvados/v1/users/current
-</pre>
+<notextile><pre><code>
+$ curl -H "Authorization: Bearer $system_root_token" https://<span class="userinput">ClusterID.example.com</span>/arvados/v1/users/current
+</code></pre></notextile>
h3. Troubleshooting
h2(#update-config). Update config.yml
-Edit the cluster config at @/etc/arvados/config.yml@ .
+Edit the cluster config at @config.yml@ .
<notextile>
<pre><code> Services:
h2(#update-nginx). Update 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".
+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 in <span class="userinput">red</span>.
<notextile>
<pre><code>upstream arvados-git-httpd {
proxy_read_timeout 300s;
ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
# The server needs to accept potentially large refpacks from push clients.
client_max_body_size 128m;
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
+{% include 'notebox_begin_warning' %}
+arvados-dispatch-cloud is only relevant for cloud installations. Skip this section if you are installing a on premise cluster that will spool jobs to Slurm.
+{% include 'notebox_end' %}
+
# "Introduction":#introduction
# "Create compute node VM image":#create-image
# "Update config.yml":#update-config
On the compute VM image, add the API server's internal IP address to @/etc/hosts@, this will ensure that it contacts the API server on the private network and not through the public interface. For example:
-<pre>
-10.20.30.40 ClusterID.example.com
-</pre>
+<notextile><pre><code>10.20.30.40 <span class="userinput">ClusterID.example.com</span>
+</code></pre></notextile>
h2(#update-config). Update config.yml
h3. Configure CloudVMs
-Add or update the following portions of your cluster configuration file, @/etc/arvados/config.yml@. Refer to "config.defaults.yml":{{site.baseurl}}/admin/config.html for information about additional configuration options.
+Add or update the following portions of your cluster configuration file, @config.yml@. Refer to "config.defaults.yml":{{site.baseurl}}/admin/config.html for information about additional configuration options.
<notextile>
<pre><code> Services:
You will need to create a "service principal" to use as a delegated authority for API access.
-<pre>
-$ az ad app create --display-name "Arvados Dispatch Cloud (ClusterID)" --homepage "https://arvados.org" --identifier-uris "https://ClusterID.example.com" --end-date 2299-12-31 --password <Your_Password>
-$ az ad sp create "<appId>"
+<notextile><pre><code>$ az ad app create --display-name "Arvados Dispatch Cloud (<span class="userinput">ClusterID</span>)" --homepage "https://arvados.org" --identifier-uris "https://<span class="userinput">ClusterID.example.com</span>" --end-date 2299-12-31 --password <span class="userinput">Your_Password</span>
+$ az ad sp create "<span class="userinput">appId</span>"
(appId is part of the response of the previous command)
-$ az role assignment create --assignee "<objectId>" --role Owner --scope /subscriptions/{subscriptionId}/
+$ az role assignment create --assignee "<span class="userinput">objectId</span>" --role Owner --scope /subscriptions/{subscriptionId}/
(objectId is part of the response of the previous command)
-</pre>
+</code></pre></notextile>
+
+Now update your @config.yml@ file:
@ClientID@ is the 'appId' value.
-@ClientSecret@ is what was provided as <Your_Password>.
+@ClientSecret@ is what was provided as <span class="userinput">Your_Password</span>.
h3. Test your configuration
h2(#update-config). Update the cluster config
-Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Keepbalance.InternalURLs@. This port is only used to publish metrics.
+Edit the cluster config at @config.yml@ and set @Services.Keepbalance.InternalURLs@. This port is only used to publish metrics.
<notextile>
<pre><code> Services:
Keepbalance:
InternalURLs:
- "http://keep.ClusterID.example.com:9005/": {}
+ "http://<span class="userinput">keep.ClusterID.example.com</span>:9005/": {}
</code></pre>
</notextile>
<notextile>
<pre><code> Services:
WebDAVDownload:
- ExternalURL: <span class="userinput">https://download.ClusterID.example.com</span>
+ ExternalURL: https://<span class="userinput">download.ClusterID.example.com</span>
</code></pre>
</notextile>
<notextile>
<pre><code> Services:
WebDAV:
- ExternalURL: <span class="userinput">https://*.collections.ClusterID.example.com/</span>
+ ExternalURL: https://<span class="userinput">*.collections.ClusterID.example.com/</span>
</code></pre>
</notextile>
<notextile>
<pre><code> Services:
WebDAV:
- ExternalURL: <span class="userinput">https://*--collections.ClusterID.example.com/</span>
+ ExternalURL: https://<span class="userinput">*--collections.ClusterID.example.com/</span>
</code></pre>
</notextile>
<notextile>
<pre><code> Services:
WebDAV:
- ExternalURL: <span class="userinput">https://collections.ClusterID.example.com/</span>
+ ExternalURL: https://<span class="userinput">collections.ClusterID.example.com/</span>
</code></pre>
</notextile>
<pre><code> Services:
WebDAV:
InternalURLs:
- <span class="userinput">"http://localhost:9002"</span>: {}
+ http://"<span class="userinput">localhost:9002</span>": {}
</code></pre>
</notextile>
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.
-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”.
+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 in <span class="userinput">red</span>.
<notextile><pre>
upstream keep-web {
server {
listen *:443 ssl;
- server_name download.<span class="userinput">ClusterID</span>.example.com
- collections.<span class="userinput">ClusterID</span>.example.com
- *.collections.<span class="userinput">ClusterID</span>.example.com
- ~.*--collections.<span class="userinput">ClusterID</span>.example.com;
+ server_name <span class="userinput">download.ClusterID.example.com</span>
+ <span class="userinput">collections.ClusterID.example.com</span>
+ <span class="userinput">*.collections.ClusterID.example.com</span>
+ <span class="userinput">~.*--collections.ClusterID.example.com</span>;
proxy_connect_timeout 90s;
proxy_read_timeout 300s;
ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
location / {
proxy_pass http://keep-web;
h2(#confirm-working). Confirm working installation
-<pre>
-$ curl -H "Authorization: Bearer $system_root_token" https://download.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/_/hello.txt
-</pre>
+<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>
If wildcard collections domains are configured:
-<pre>
-$ curl -H "Authorization: Bearer $system_root_token" https://59389a8f9ee9d399be35462a0f92541c-53.collections.ClusterID.example.com/hello.txt
-</pre>
+<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>
If using a single collections preview domain:
-<pre>
-$ curl https://collections.ClusterID.example.com/c=59389a8f9ee9d399be35462a0f92541c-53/t=$system_root_token/_/hello.txt
-</pre>
+<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>
<div class="offset1">
table(table table-bordered table-condensed).
|_. Hostname|
-|keep.@ClusterID@.your.domain|
+|@keep.ClusterID.example.com@|
</div>
This hostname should resolve from anywhere on the internet.
h2(#update-config). Update config.yml
-Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Keepproxy.ExternalURL@ and @Services.Keepproxy.InternalURLs@.
+Edit the cluster config at @config.yml@ and set @Services.Keepproxy.ExternalURL@ and @Services.Keepproxy.InternalURLs@.
<notextile>
<pre><code> Services:
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.
-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”.
+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 in <span class="userinput">red</span>.
<notextile><pre><code>upstream keepproxy {
server 127.0.0.1:<span class="userinput">25107</span>;
server {
listen *:443 ssl;
- server_name keep.<span class="userinput">ClusterID</span>.example.com;
+ server_name <span class="userinput">keep.ClusterID.example.com</span>;
proxy_connect_timeout 90s;
proxy_read_timeout 300s;
proxy_request_buffering off;
ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
# Clients need to be able to upload blocks of data up to 64MiB in size.
client_max_body_size 64m;
<div class="offset1">
table(table table-bordered table-condensed).
|_. Hostname|
-|keep0.@ClusterID@.example.com|
-|keep1.@ClusterID@.example.com|
+|@keep0.ClusterID.example.com@|
+|@keep1.ClusterID.example.com@|
</div>
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.
|"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).|
+|"Node Manager":install-nodemanager.html, "arvados-dispatch-cloud":install-dispatch-cloud.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).|
h2(#identity). Identity provider
Choose which backend you will use to authenticate users.
-* 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).
+* Google login to authenticate users with a Google account. Note: if you only use this identity provider, login can be handled by @arvados-controller@ (recommended), and you 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.
Choose which backend you will use to schedule computation.
-* 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.
+* On AWS EC2 and Azure, you probably want to use @arvados-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.
h2(#machines). Hardware (or virtual machines)
-Choose how to allocate Arvados services to machines. We recommend that each machine start with a clean installation of your preferred Linux distribution.
+Choose how to allocate Arvados services to machines. We recommend that each machine start with a clean installation of a supported GNU/Linux distribution.
-For a production installation, this is a reasonable configuration:
+For a production installation, this is a reasonable starting point:
<div class="offset1">
table(table table-bordered table-condensed).
|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 worker nodes ^2^|2+ |Depends on workload|
+|Compute worker nodes ^2^|0+ |Depends on workload; scaled dynamically in the cloud|
|User shell nodes ^3^|0+|Depends on workload|
</div>
h2(#dnstls). DNS entries and TLS certificates
-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.
+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.
This guide uses the following hostname conventions. A later part of this guide will describe how to set up Nginx virtual hosts.
<div class="offset1">
table(table table-bordered table-condensed).
|_. Function|_. Hostname|
-|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
+|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.@ClusterID@.example.com or
-*<notextile>--</notextile>collections.@ClusterID@.example.com or
-collections.@ClusterID@.example.com (see the "keep-web install docs":install-keep-web.html)|
+*.collections.@ClusterID.example.com@ or
+*<notextile>--</notextile>collections.@ClusterID.example.com@ or
+collections.@ClusterID.example.com@ (see the "keep-web install docs":install-keep-web.html)|
</div>
{% include 'notebox_begin' %}
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
+{% include 'notebox_begin_warning' %}
+Skip this section if you are using Google login via @arvados-controller@.
+{% include 'notebox_end' %}
+
# "Install dependencies":#dependencies
# "Set up database":#database-setup
# "Update config.yml":#update-config
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".
+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 in <span class="userinput">red</span>.
<notextile>
<pre><code>server {
server_name <span class="userinput">auth.ClusterID.example.com</span>;
ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
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.
+ # <span class="userinput">If you are using RVM, uncomment the line below.</span>
+ # <span class="userinput">If you're using system ruby, leave it commented out.</span>
#passenger_ruby /usr/local/rvm/wrappers/default/ruby;
}
</code></pre>
h2(#configure). Update config.yml
-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
+Edit @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
<notextile>
<pre><code> Services:
h2(#update-nginx). Update nginx configuration
-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".
+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 in <span class="userinput">red</span>.
<notextile>
<pre><code>server {
h2(#configure). Update config.yml
-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
+Edit @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
<notextile>
<pre><code> Services:
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.
-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".
+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 in <span class="userinput">red</span>.
<notextile>
<pre><code>server {
server_name workbench2.<span class="userinput">ClusterID.example.com</span>;
ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
index index.html;
- # TODO: Workbench2 uses a call to /config.json to bootstrap itself
- # and find out where to contact the API server.
+ # <span class="userinput">Workbench2 uses a call to /config.json to bootstrap itself</span>
+ # <span class="userinput">and find out where to contact the API server.</span>
location /config.json {
return 200 '{ "API_HOST": "<span class="userinput">ClusterID.example.com</span>" }';
}
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.
+Edit the cluster config at @config.yml@ and set @Services.Websocket.ExternalURL@ and @Services.Websocket.InternalURLs@. Replace @zzzzz@ with your cluster id.
<notextile>
<pre><code> Services:
The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.
-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".
+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 in <span class="userinput">red</span>.
<notextile><pre>
upstream arvados-ws {
proxy_read_timeout 300s;
ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
location / {
proxy_pass http://arvados-ws;
Confirm the service is listening on its assigned port and responding to requests.
<notextile>
-<pre><code>~$ <span class="userinput">curl https://ws.ClusterID.example.com/status.json</span>
+<pre><code>~$ <span class="userinput">curl https://<span class="userinput">ws.ClusterID.example.com</span>/status.json</span>
{"Clients":1}
</code></pre>
</notextile>
h3. Centos 7
-???
+<notextile>
+<pre><code># <span class="userinput">yum install epel-release</span></code>
+<code># <span class="userinput">yum install nginx</span></code></pre>
+</notextile>
h3. Debian and Ubuntu
Packages are available for recent versions of Debian and Ubuntu.
-First, register the Curoverse signing key in apt's database:
+First, register the Arvados signing key in apt's database:
{% include 'install_debian_key' %}
For example, let's copy from the <a href="https://playground.arvados.org/">Arvados playground</a>, also known as *qr1hi*, to *dst_cluster*. The names *qr1hi* and *dst_cluster* are interchangable with any cluster name. You can find the cluster name from the prefix of the uuid of the object you want to copy. For example, in *qr1hi*-4zz18-tci4vn4fa95w0zx, the cluster name is qr1hi.
-In order to communicate with both clusters, you must create custom configuration files for each cluster. In the Arvados Workbench, click on the dropdown menu icon <span class="fa fa-lg fa-user"></span> <span class="caret"></span> in the upper right corner of the top navigation menu to access the user settings menu, and click on the menu item *Current token*. Copy the @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ in both of your clusters. Then, create two configuration files, one for each cluster. The names of the files must have the format of *uuid_prefix.conf*. In our example, let's make two files, one for *qr1hi* and one for *dst_cluster*. From your *Current token* page in *qr1hi* and *dst_cluster*, copy the @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@.
+In order to communicate with both clusters, you must create custom configuration files for each cluster. In the Arvados Workbench, click on the dropdown menu icon <span class="fa fa-lg fa-user"></span> <span class="caret"></span> in the upper right corner of the top navigation menu to access the user settings menu, and click on the menu item *Current token*. Copy the @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ in both of your clusters. Then, create two configuration files, one for each cluster. The names of the files must have the format of *ClusterID.conf*. In our example, let's make two files, one for *qr1hi* and one for *dst_cluster*. From your *Current token* page in *qr1hi* and *dst_cluster*, copy the @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@.
!{display: block;margin-left: 25px;margin-right: auto;}{{ site.baseurl }}/images/api-token-host.png!
h3. Browsing Keep (read-only)
-In Finder, use "Connect to Server..." under the "Go" menu and enter @https://collections.uuid_prefix.your.domain/@ in popup dialog. When prompted for credentials, put a valid Arvados token in the @Password@ field and anything in the Name field (it will be ignored by Arvados).
+In Finder, use "Connect to Server..." under the "Go" menu and enter @https://collections.ClusterID.example.com/@ in popup dialog. When prompted for credentials, put a valid Arvados token in the @Password@ field and anything in the Name field (it will be ignored by Arvados).
This mount is read-only. Write support for the @/users/@ directory is planned for a future release.
h3. Accessing a specific collection in Keep (read-write)
-In Finder, use "Connect to Server..." under the "Go" menu and enter @https://collections.uuid_prefix.your.domain/@ in popup dialog. When prompted for credentials, put a valid Arvados token in the @Password@ field and anything in the Name field (it will be ignored by Arvados).
+In Finder, use "Connect to Server..." under the "Go" menu and enter @https://collections.ClusterID.example.com/@ in popup dialog. When prompted for credentials, put a valid Arvados token in the @Password@ field and anything in the Name field (it will be ignored by Arvados).
This collection is now accessible read/write.
h3. Browsing Keep (read-only)
-Use the 'Map network drive' functionality, and enter @https://collections.uuid_prefix.your.domain/@ in the Folder field. When prompted for credentials, you can fill in an arbitrary string for @Username@, it is ignored by Arvados. Windows will not accept an empty @Username@. Put a valid Arvados token in the @Password@ field.
+Use the 'Map network drive' functionality, and enter @https://collections.ClusterID.example.com/@ in the Folder field. When prompted for credentials, you can fill in an arbitrary string for @Username@, it is ignored by Arvados. Windows will not accept an empty @Username@. Put a valid Arvados token in the @Password@ field.
This mount is read-only. Write support for the @/users/@ directory is planned for a future release.
h3. Accessing a specific collection in Keep (read-write)
-Use the 'Map network drive' functionality, and enter @https://collections.uuid_prefix.your.domain/c=your-collection-uuid@ in the Folder field. When prompted for credentials, you can fill in an arbitrary string for @Username@, it is ignored by Arvados. Windows will not accept an empty @Username@. Put a valid token in the @Password@ field.
+Use the 'Map network drive' functionality, and enter @https://collections.ClusterID.example.com/c=your-collection-uuid@ in the Folder field. When prompted for credentials, you can fill in an arbitrary string for @Username@, it is ignored by Arvados. Windows will not accept an empty @Username@. Put a valid token in the @Password@ field.
This collection is now accessible read/write.
projects / arvados.git / commitdiff