Single host Arvados

Limitations of the single host install
Prerequisites and planning
Download the installer
Install Ansible
Set up cluster configuration
Set up cluster inventory
Run the installer playbook
Test the cluster
Changing your configuration
Upgrading your Arvados cluster

Limitations of the single host install

NOTE: The single host installation is a good choice for evaluating Arvados, but it is not recommended for production use.

Using the default configuration, the single host install has scaling limitations compared to a production multi-host install:

It uses the local /var partition to store all user data and logs.
It uses the crunch-dispatch-local dispatcher, which has a limit of eight concurrent jobs.
Because jobs and Arvados services all run on the same machine, they will compete for CPU/RAM resources.

Prerequisites and planning

Cluster ID

Choose a 5-character cluster identifier that will represent the cluster. Refer to our guidelines on choosing a cluster identifier. Only lowercase letters and digits 0-9 are allowed. Our documentation uses xurid throughout. You should replace this each time it appears with your chosen cluster identifier.

Cluster host

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 if you are running workflows) running a supported Linux distribution:

Supported Linux Distributions
AlmaLinux 9 (since 9.2)
AlmaLinux 8 (since 8.8)
Debian 12 (“bookworm”)
Red Hat Enterprise Linux 9 (since 9.2)
Red Hat Enterprise Linux 8 (since 8.8)
Rocky Linux 9 (since 9.2)
Rocky Linux 8 (since 8.8)
Ubuntu 24.04 (“noble”)
Ubuntu 22.04 (“jammy”)

The single host install stores all user data and logs under /var. You should ensure that this partition has adequate storage for your planned usage. We suggest starting with at least 50GiB of free space.

You must be able to connect to this host via SSH. Your account must have permission to run arbitrary commands with sudo.

Download the installer

The Ansible installer is only available in the Arvados source tree. Clone a copy of the Arvados source for the version of Arvados you’re using in a directory convenient for you:

~$ git clone --depth=1 --branch=main git://git.arvados.org/arvados.git ~/arvados

Install Ansible

Option 1. Install Ansible with pipx

The pipx tool is packaged in many of our supported distributions. You can install it on Debian/Ubuntu by running:

# apt install pipx

Or install it on Red Hat/AlmaLinux/Rocky Linux by running:

# dnf install pipx

Note:

If the pipx package is not found, it is not available for your distribution. Instead install Ansible with virtualenv and pip.

After pipx is installed, install Ansible by running:

$ arvados/tools/ansible/install-ansible.sh
  installed package ansible-core 2.15.13, installed using Python 3.11.2
  These apps are now globally available
    - ansible
    - ansible-config
    - ansible-connection
    - ansible-console
    - ansible-doc
    - ansible-galaxy
    - ansible-inventory
    - ansible-playbook
    - ansible-pull
    - ansible-test
    - ansible-vault
done! ✨ 🌟 ✨

[…]

Ansible successfully installed!

If this script reports the final success message, skip the next section.

Option 2. Install Ansible in a virtualenv

This method works on all of our supported distributions, but requires you to configure a lot of paths manually. Install Python and virtualenv on Debian/Ubuntu by running:

# apt install python3-venv

Or install it on Red Hat/AlmaLinux/Rocky Linux by running:

# dnf install python3

Next, set up a virtualenv. If you want to install this somewhere other than ~/arvados-ansible, you may change that path each time it appears.

$ arvados/tools/ansible/install-ansible.sh ~/arvados-ansible
Collecting ansible-core~=2.15.13
[…]

Ansible successfully installed!

Finally, add all the Ansible tools to your executable path. If you keep personal executables somewhere other than ~/.local/bin, you may change that path.

$ ln -st ~/.local/bin ~/arvados-ansible/bin/ansible*

Alternatively, you may reconfigure your shell to add $HOME/arvados-ansible/bin to the end of your $PATH variable.

Set up cluster configuration

Copy the example cluster configuration from the Arvados source tree to a location outside it. We recommend you use your chosen cluster ID in the filename to help keep it unique. For example:

$ cp arvados/tools/ansible/examples/simple-cluster-config.yml ~/xurid-config.yml

Open the copy you created in your editor, and make changes following the instructions at the top of the file.

Set up cluster inventory

Copy the example cluster inventory from the Arvados source tree to a location outside it. We recommend you use your chosen cluster ID in the filename to help keep it unique. For example:

$ cp arvados/tools/ansible/examples/simple-cluster-inventory.yml ~/xurid-inventory.yml

Open the copy you created in your editor and make these changes noted in comments:

Under hosts:, change hostname.example to the hostname or address of your cluster node.
Change arvados_config_file to the path of the cluster configuration you created in the previous step.
Change arvados_cluster_id to your chosen cluster ID.

You may make other changes noted in comments, but the changes listed above are required.

Run the installer playbook

With your cluster configuration and inventory complete, you can use them to run the installer playbook:

$ cd arvados/tools/ansible
arvados/tools/ansible $ ansible-playbook -Ki ~/xurid-inventory.yml install-arvados-cluster.yml

This will prompt you for a BECOME password:. Enter your sudo password on the cluster node. Ansible will use this to perform privileged system configuration. You will see it start to log tasks like:

PLAY [Bootstrap nodes] *********************************************************

TASK [Load Arvados configuration file] *****************************************
ok: [hostname.example -> localhost]

TASK [Load Arvados cluster configuration] **************************************
ok: [hostname.example]

TASK [ansible.builtin.include_role : distro_bootstrap] *************************

TASK [distro_bootstrap : Get distribution IDs] *********************************
changed: [hostname.example]

If all goes well, it will log finish with a PLAY RECAP reporting failed=0, which indicates all tasks were successful:

PLAY RECAP *********************************************************************
hostname.example : ok=161  changed=34   unreachable=0    failed=0    skipped=23   rescued=0    ignored=0

Diagnosing problems with the playbook run

If the PLAY RECAP indicates that a task failed, that will typically be logged with a message like this:

TASK [arvados_controller : Start and enable arvados-controller.service] ********
fatal: [hostname.example]: FAILED! => {"changed": false, "msg": "Unable to restart service arvados-controller.service: Job for arvados-controller.service failed because the control process exited with error code.\nSee \"systemctl status arvados-controller.service\" and \"journalctl -xeu arvados-controller.service\" for details.\n"}

The TASK line gives you some context for what failed. The first part (arvados_controller in this example) describes generally what Arvados service it was configuring. The rest of the line describes the specific step it was taking (starting arvados-controller.service in this example). This context can suggest where you might check your configuration for problems or look on the cluster node for additional information. This example problem was caused by the Controller service in the cluster configuration trying to use an already-claimed port in one of the InternalURLs.

Test the cluster

Run diagnostics

The arvados-client diagnostics command can check all services on a cluster to identify problems with inconsistent configuration. On your cluster node, install and run it like this:

$ sudo apt install arvados-client
$ sudo arvados-client sudo diagnostics -internal-client
INFO       5: running health check (same as `arvados-server check`)
INFO      10: getting discovery document from https://hostname.example:8443/discovery/v1/apis/arvados/v1/rest
INFO      20: getting exported config from https://hostname.example:8443/arvados/v1/config
[…]
INFO     160: running a container
INFO      ... container request uuid = xurid-xvhdp-12345abcde67890
INFO      ... container request submitted, waiting up to 10m for container to run
INFO    9990: deleting temporary collection
INFO    --- no errors ---

Access Workbench

The default Ansible inventory deploys Arvados with a self-signed certificate. If you deployed this way, you will have the best Workbench experience if you configure your browser to trust that certificate for it and supporting services. Follow the instructions for your specific browser below.

If you configured the inventory with a different certificate that is already trusted by your browser, you can skip these steps. You should be able to open the URL from Services.Workbench2.ExternalURL from your cluster configuration in your browser.

Trusting self-signed certificates in Chrome

Find the arvados_tls.Default setting in your Ansible inventory.
If those options specify remote: true, copy the cert path from your cluster host to the host where you’re running the browser. Note you only need the cert file, not the key file.
In the URL bar, enter chrome://certificate-manager/ and open that.
Under the “Custom” header, open “Installed by you.”
Next to “Trusted Cerficates,” press the “Import” button.
In the file picker dialog, open your copy of the arvados_tls.Default.cert file.

Now you should be able to open the URL from Services.Workbench2.ExternalURL from your cluster configuration in your browser. You can skip the next section unless you also want to set up Firefox.

Trusting self-signed certificates in Firefox

Open the “Edit” menu and select “Settings.”
Find and press the “View Certificates…” button to open the Certificate Manager.
Open the “Servers” tab.
Press the “Add Exception…” button.
Enter the ExternalURL in your cluster configuration for the Workbench2 service.
Press the “Get Certificate” button.
Press the “Confirm Security Exception” button.
Repeat the process from step 4 with your configured URLs for the Controller, Keepproxy, WebDAV, and WebDAVDownload services.

Now you should be able to open the URL from Services.Workbench2.ExternalURL from your cluster configuration in your browser.

Changing your configuration

In the future, if you want to make changes to your Arvados cluster or Ansible inventory configuration, simply edit those files and run the playbook again. The playbook will deploy your changes to all the component services.

Upgrading your Arvados cluster

When a new version of Arvados is released, the general process to upgrade the cluster is:

In your Arvados checkout directory, git fetch and then git switch to the branch or tag that corresponds to the release you want to use.
Consult the Arvados upgrade notes to see if you need or want to make change to your cluster configuration file.
Run the playbook again with your cluster inventory.

See also Maintenance and upgrading for more information.

Previous: Installation options Next: Multi-Host Arvados