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 testing 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 (see instructions below).
To install Docker, please refer to the official documentation.
Start the container with (replace latest with the version you want to use, check the Docker Hub for available tags/versions):
$ docker run -it aiidateam/aiida-core-with-services:latest bash
You can specify a name for the container with the --name option for easier reference later on:
$ docker run -it --name aiida-container aiidateam/aiida-core-with-services:latest 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.
For example, to check the verdi status, execute the following command inside the container:
$ 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
To copy files from your computer to the container, use the docker cp command.
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:/home/aiida
If you stop the container (docker stop or simply Ctrl+D from the container) and start it again, any data you created will persist.
$ docker start -i aiida-container
However, if you remove the container, all data will be removed as well.
$ docker stop aiida-container
$ docker rm aiida-container
The preferred way to persistently store data is to create a volume.
To create a simple volume, run:
$ docker volume create container-home-data
Then make sure to mount that volume when running the aiida container:
$ docker run -it --name aiida-container -v container-home-data:/home/aiida aiidateam/aiida-core:latest
Starting the container with the above command, ensures that any data stored in the /home/aiida path within the container is stored in the conatiner-home-data volume and therefore persists even if the container is removed.
To persistently store the Python packages installed in the container, use –user flag when installing packages with pip, the packages will be installed in the /home/aiida/.local path which is mounted to the container-home-data volume.
You can also mount a local directory instead of a volume and to other container paths, please refer to the Docker documentation for more information.