Docker#
The AiiDA team maintains a number of Docker images on Docker Hub. These images contain a fully pre-configured AiiDA environment which make it easy to get started using AiiDA if you are familiar with Docker.
Currently, there are three image variants:
This is the base image.
It comes just with the aiida-core
package installed.
It expects that the RabbitMQ and PostgreSQL services are provided.
This images builds on top of aiida-core-base
but also installs RabbitMQ and PostgreSQL as services inside the image.
This image is therefore complete and ready to be used.
This image builds on top of aiida-core-with-services
with the only difference that the aiida-core
package is installed from source in editable mode.
This makes this image suitable for development of the aiida-core
package.
Start a container#
To start a container from an image, run:
docker run -it --name aiida aiidateam/aiida-core-with-services:latest bash
In this example, the aiida-core-with-services
image is started where latest
refers to the latest tag.
The --name
option is optional but is recommended as it makes it easier to restart the same container at a later point in time.
The -it
option is used to run the container in interactive mode and to allocate a pseudo-TTY.
After the container start up has finished, a bash shell inside the container is opened.
An AiiDA profile is automatically created when the container is started.
By default the profile is created using the core.psql_dos
storage plugin and a default user is created.
See section container configuration how to customize certain parts of this setup.
To confirm that everything is up and running as required, run:
verdi status
which should show something like:
✔ version: AiiDA v2.5.1
✔ config: /home/aiida/.aiida
✔ profile: default
✔ storage: Storage for 'default' [open] @ postgresql://aiida:***@localhost:5432
✔ rabbitmq: Connected to RabbitMQ v3.10.18 as amqp://guest:guest@127.0.0.1:5672
✔ daemon: Daemon is running with PID 324
If all checks show green check marks, the container is ready to go.
The container can be shut down by typing exit
or pressing CTRL+d
.
The container can be restarted at a later time, see restarting a container for details.
Any data that was created in a previous session is still available.
Caution
When the container is not just stopped but deleted, any data stored in the container, including the data stored in the profile’s storage, is permanently localhost To ensure the data is not lost, it should be persisted on a volume that is mounted to the container. Refer to the section on persisting data for more details.
Restarting a container#
After shutting down a container, it can be restarted with:
docker start -i aiida
The name aiida
here is the reference given with the --name
option when the container was originally created.
To open an interactive bash shell inside the container, run:
docker exec -it aiida bash
Persisting data#
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 the very first time that the container is created:
docker run -it --name aiida -v container-home-data:/home/aiida aiidateam/aiida-core-with-services:latest bash
By mounting the volume, any data that gets 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 deleted.
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 the container to a local directory, please refer to the Docker documentation for more information.
Container configuration#
Upon container creation, the following environment variables can be set to configure the default profile that is created:
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
)
These environment variables can be set when starting the container with the -e
option.
Note
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.
Container backup#
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 aiida-container-backup
The above command will create from the container aiida
a new image named aiida-container-backup
, containing all the data and modifications made in the container.
The container can then be exported to a tarball and for it to be stored permanently:
docker save -o aiida-container-backup.tar aiida-container-backup
To restore the container, pull the image, or load from the tarball:
docker load -i aiida-container-backup.tar
This creates a container that can then be started with docker start
.
Any named volumes, can be backed up independently. Refer to Backup, restore, or migrate data volumes for more information.