Run AiiDA via a Docker image#
The AiiDA team maintains a Docker image on Docker Hub. This image contains a fully pre-configured AiiDA environment which makes it particularly useful for learning and developing purposes.
Caution
All data stored in a container will persist only over the lifetime of that particular container (i.e., removing the container will also purge the data) unless you use volumes to persist the data, see Advanced usage for more details.
Docker is available for Windows, Mac and Linux and can be installed in different ways.
Colima is a new open-source project that makes it easy to run Docker on MacOS. It is a lightweight alternative to Docker Engine with a focus on simplicity and performance.
Colima is the recommended way. With colima, you can have multiple Docker environments running at the same time, each with its own Docker daemon and resource allocation thus avoiding conflicts.
To install the colima, on MacOS run:
$ brew install colima
Or check Check here for other installation options.
After installation, start the docker daemon by:
$ colima start
The bare minimum to run Docker on Linux is to install the Docker Engine. If you don’t need a graphical user interface, this is the recommended way to install Docker.
Note
You will need root privileges to perform the post-installation steps. Otherwise, you will need to use sudo for every Docker command.
Start the image with the docker command line interface (docker CLI).
There are differnt tags available for the AiiDA image, the latest tag is the image with the most recent stable version of aiida-core installed in the container.
You can replace the latest tag with the aiida-core or services version you want to use, check the Docker Hub for available tags.
Use the Docker CLI to run the AiiDA container.
$ docker run -it --name aiida-container-demo aiidateam/aiida-core-with-services:latest bash
The -it option is used to run the container in interactive mode and to allocate a pseudo-TTY.
You will be dropped into a bash shell inside the container.
You can specify a name for the container with the --name option for easier reference later on.
For the quick test, you can also use the --rm option to remove the container when it exits.
In the following examples, we will use the name aiida-container-demo for the container.
To exit and stop the container, type exit or press Ctrl+D.
Please note the run sub-command is used to both create and start a container.
In order to start a container which is already created, you should use start, by running:
$ docker start -i aiida-container-demo
If you need another shell inside the container, run:
$ docker exec -it aiida-container-demo bash
By default, an AiiDA profile is automatically set up inside the container.
To disable this default profile being created, set the SETUP_DEFAULT_AIIDA_PROFILE environment variable to false.
The following environment variables can be set to configure the default AiiDA profile:
AIIDA_PROFILE_NAME: the name of the profile to be created (default:default)AIIDA_USER_EMAIL: the email of the default user to be created (default:aiida@localhost)AIIDA_USER_FIRST_NAME: the first name of the default user to be created (default:Giuseppe)AIIDA_USER_LAST_NAME: the last name of the default user to be created (default:Verdi)AIIDA_USER_INSTITUTION: the institution of the default user to be created (default:Khedivial)AIIDA_CONFIG_FILE: the path to the AiiDA configuration file used for other profile configuration parameters (default:/aiida/assets/config-quick-setup.yaml).
These environment variables can be set when starting the container with the -e option.
Please note that the AIIDA_CONFIG_FILE variable points to a path inside the container.
Therefore, if you want to use a custom configuration file, it needs to be mounted from the host path to the container path.
The profile named default is created under the aiida user.
To check the status of AiiDA environment setup, execute the following command inside the container shell:
$ verdi status
✓ config dir: /home/aiida/.aiida
✓ profile: On profile default
✓ repository: /home/aiida/.aiida/repository/default
✓ postgres: Connected as aiida_qs_aiida_477d3dfc78a2042156110cb00ae3618f@localhost:5432
✓ rabbitmq: Connected as amqp://127.0.0.1?heartbeat=600
✓ daemon: Daemon is running as PID 1795 since 2020-05-20 02:54:00
Advanced usage#
Congratulations! You have a working AiiDA environment, and can start using it.
If you use the Docker image for development or production, you will likely need additional settings such as clone the repository and install aiida-core in the editable mode to make it work as expected. See development wiki for more details.
Copy files from your computer to the container
Use the docker cp command if you need to copy files from your computer to the container or vice versa.
For example, to copy a file named test.txt from your current working directory to the /home/aiida path in the container, run:
$ docker cp test.txt aiida-container-demo:/home/aiida
Persist data across different containers
The lifetime of the data stored in a container is limited to the lifetime of that particular container.
If you stop the container (docker stop or simply Ctrl+D from the container) and start it again, any data you created will persist.
However, if you remove the container, all data will be removed as well.
$ docker rm aiida-container-demo
The preferred way to persistently store data across Docker containers is to create a volume.
To create a simple volume, run:
$ docker volume create container-home-data
In this case, one needs to specifically mount the volume very first time that the container is being created:
$ docker run -it --name aiida-container-demo -v container-home-data:/home/aiida aiidateam/aiida-core-with-services:latest bash
Starting the container with the above command ensures that any data stored in the /home/aiida path within the container is stored in the container-home-data volume and therefore persists even if the container is removed.
When installing packages with pip, use the --user flag to store the Python packages installed in the mounted volume (if you mount the home specifically to a volume as mentioned above) permanently.
The packages will be installed in the /home/aiida/.local directory of the container, which is mounted on the container-home-data volume.
You can also mount a folder in container to a local directory, please refer to the Docker documentation for more information.
Backup the container
To backup the data of AiiDA, you can follow the instructions in the Backup and restore section. However, Docker provides a convenient way to backup the container data by taking a snapshot of the entire container or the mounted volume(s).
The following is adapted from the Docker documentation.
If you don’t have a volume mounted to the container, you can backup the whole container by committing the container to an image:
$ docker container commit aiida-container-demo aiida-container-backup
The above command will create a new image named aiida-container-backup containing all the data and modifications you made in the container.
Then, you can export the container to a local tarball and store it permanently:
$ docker save -o aiida-container-backup.tar aiida-container-backup
To restore the container, pull the image, or load from the tarball, run:
$ docker load -i aiida-container-backup.tar
You’ll find a container in the list and you can then start it with docker start.
If you used a named volume, you can backup the volume independently.
Please check Backup, restore, or migrate data volumes for more information.