通过 Docker 映像运行 AiiDA#

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.

小心

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.

Install Docker on your PC

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.

备注

You will need root privileges to perform the post-installation steps. Otherwise, you will need to use sudo for every Docker command.

Start/stop container and use AiiDA interactively

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

默认情况下,容器内会自动设置 AiiDA 配置文件。要禁用创建的默认配置文件,请将 SETUP_DEFAULT_AIIDA_PROFILE 环境变量设置为 false

可以设置以下环境变量来配置默认的 AiiDA 配置文件:

  • AIIDA_PROFILE_NAME :要创建的配置文件的名称(默认值: default )

  • AIIDA_USER_EMAIL :要创建的默认用户的电子邮件(默认值: aiida@localhost )

  • AIIDA_USER_FIRST_NAME :要创建的默认用户的名字(默认值: Giuseppe )

  • AIIDA_USER_LAST_NAME :要创建的默认用户的姓氏(默认值: Verdi )

  • AIIDA_USER_INSTITUTION :要创建的默认用户的机构(默认值: Khedivial )

  • AIIDA_CONFIG_FILE :用于其他配置文件配置参数的 AiiDA 配置文件的路径(默认值: /aiida/assets/config-quick-setup.yaml )。

可以在使用 -e 选项启动容器时设置这些环境变量。

请注意, AIIDA_CONFIG_FILE 变量指向容器内的路径。因此,如果要使用自定义配置文件,需要将其从主机路径加载到容器路径。

检查设置

aiida 用户下创建了名为 default 的配置文件。

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.

将电脑中的文件复制到容器中

Use the docker cp command if you need to copy files from your computer to the container or vice versa.

例如,要将名为 test.txt 的文件从当前工作目录复制到容器中的 /home/aiida 路径,请运行

$ docker cp test.txt aiida-container-demo:/home/aiida
在不同容器中持久保存数据

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.

要创建一个简单的加密卷,请运行

$ 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.

What’s next?