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:
/var partition to store all user data and logs.crunch-dispatch-local dispatcher, which has a limit of eight concurrent jobs.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.
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 |
| AlmaLinux 8 (since 8.4) |
| Debian 12 (“bookworm”) |
| Debian 11 (“bullseye”) |
| Red Hat Enterprise Linux 9 |
| Red Hat Enterprise Linux 8 (since 8.4) |
| Rocky Linux 9 |
| Rocky Linux 8 (since 8.4) |
| Ubuntu 24.04 (“noble”) |
| Ubuntu 22.04 (“jammy”) |
| Ubuntu 20.04 (“focal”) |
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.
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
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
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:
$ cd arvados/tools/ansible
arvados/tools/ansible $ pipx install "$(grep -E '^ansible-core[^-_[:alnum:]]' requirements.txt)"
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! ✨ 🌟 ✨
arvados/tools/ansible $ pipx runpip ansible-core install -r requirements.txt
[…]
Successfully installed argcomplete-3.6.2 certifi-2025.6.15 charset_normalizer-3.4.2 docker-7.1.0 [… and other packages…]
arvados/tools/ansible $ ansible-galaxy install -r requirements.yml
[…]
ansible.posix:2.0.0 was installed successfully
community.docker:4.6.1 was installed successfully
community.general:10.7.1 was installed successfully
community.postgresql:4.1.0 was installed successfully
If you complete these steps successfully, skip the next section.
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.
$ cd arvados/tools/ansible
arvados/tools/ansible $ python3 -m venv ~/arvados-ansible
arvados/tools/ansible $ ~/arvados-ansible/bin/pip install -r requirements.txt
[…]
Successfully installed MarkupSafe-3.0.2 PyYAML-6.0.2 ansible-core-2.15.13 [… and other packages…]
arvados/tools/ansible $ ~/arvados-ansible/bin/ansible-galaxy install -r requirements.yml
[…]
ansible.posix:2.0.0 was installed successfully
community.docker:4.6.1 was installed successfully
community.general:10.7.1 was installed successfully
community.postgresql:4.1.0 was installed successfully
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.
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.
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:
hosts:, change hostname.example to the hostname or address of your cluster node.arvados_config_file to the path of the cluster configuration you created in the previous step.arvados_cluster_id to your chosen cluster ID.You may make other changes noted in comments, but the changes listed above are required.
With your cluster configuration and inventory complete, you can use them to run the installer playbook:
$cd arvados/tools/ansiblearvados/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
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.
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 ---
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.
arvados_tls.Default setting in your Ansible inventory.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.chrome://certificate-manager/ and open that.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.
ExternalURL in your cluster configuration for the Workbench2 service.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.
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.
When a new version of Arvados is released, the general process to upgrade the cluster is:
git fetch and then git switch to the branch or tag that corresponds to the release you want to use.See also Maintenance and upgrading for more information.
The content of this documentation is licensed under the
Creative
Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the
Apache License, Version 2.0.