This repository contains the Dockerfiles for the official AiiDAlab docker image stack. All images are based on the jupyter/minimal-notebook.
Image variants:
base
– A minimal image that comes with AiiDA pre-installed and an AiiDA profile set up.base-with-services
– Likebase
, but AiiDA services (PostgreSQL and RabbitMQ) are installed on the container and automatically launched on startup.lab
– Likebase
, but uses the AiiDAlab home app as the primary interface (the standard JupyterLab interface is also available).full-stack
– Our most comprehensive image, likelab
, but also comes with services pre-installed and launched.
Supported tags (released on Docker Hub):
edge
– the latest commit on the default branchlatest
– the latest regular releaseaiida-$AIIDA_VERSION
– the latest regular release with that AiiDA version (ex.aiida-2.0.0
)python-$PYTHON_VERSION
– the latest regular release with that Python version (ex.python-3.9.2
)$version
– the version of a specific release (ex.2022.1001
)
In addition, edge
, latest
, and $version
are also released internally on the GitHub Container registry (ghcr.io).
Pull requests into the default branch are further released on ghcr.io with the pr-###
tag to simplify the testing of development versions.
You can launch a container based on one of our published images directly with Docker, by executing for example the following command:
docker run -it -p 8888:8888 aiidalab/full-stack
However, we recommend to use AiiDAlab Launch to run images locally for production environments.
Note: On recent versions of Mac OS-X you will have to select a different port, since port 8888 is already in use by one of the system services.
- Resetting the username and thus home directory location from the default (
jovyan
) via theNB_USER
environment variable is currently not supported (#297).
The repository uses the doit automation tool to automate tasks related to this repository, including building, testing, and locally deploying Docker images with docker-compose.
To use this system, setup a build end testing environment and install the dependencies with:
pip install -r requirements-dev.txt
To build the images, run doit build
(tested with docker buildx version v0.8.2).
The build system will attempt to detect the local architecture and automatically build images for it (tested with amd64 and arm64).
All commands build
, tests
, and up
will use the locally detected platform and use a version tag based on the state of the local git repository.
However, you can also specify a custom platform or version with the --platform
and --version
parameters, example: doit build --arch=arm64 --version=my-version
.
You can specify target stacks to build with --target
, example: doit build --target base --target full-stack
.
To run tests, first build the images as described in the previous section.
Then run the automated tests with doit tests
.
Tip: The continuous integration workflow will build, release (at ghcr.io/aiidalab/*:pr-###
), and test images for all pull requests into the default branch.
For manual testing, you can start the images with doit up
, however we recommend to use aiidalab-launch to setup a production-ready local deployment.
Images are built for linux/amd64
and linux/arm64
during continuous integration for all pull requests into the default branch and pushed to the GitHub Container Registry (ghcr.io) with tags ghcr.io/aiidalab/*:pr-###
.
You can run automated or manual tests against those images by specifying the registry and version for both the up
and tests
commands, example: doit up --registry=ghcr.io/ --version=pr-123
.
Note: You may have to log into the registry first.
We distinguish between regular releases and special releases, where the former follow the standard versioning scheme (v2022.1001
) and the latter would be specific to a certain use case, e.g., a workshop with dedicated requirements.
To create a regular release, set up a development environment, and then use bumpver
:
bumpver update
This will update the README.md file, make a commit, tag it, and then push both to the repository to kick off the build and release flow.
To create a special release, simply tag it with a tag name of your choice with the exception that it cannot start with the character v
.
The aiidalab-launch
tool provides a convenient and robust method of both launching and managing one or multiple AiiDAlab instances on your computer.
To use it, simply install it via pip
pip install aiidalab-launch
and then start AiiDAlab with
aiidalab-launch start
Note: AiiDAlab will keep running until you explicitly stop it or shutdown/restart your computer.
In that case, you will have to run the aiidalab-launch start
command again to restart AiiDAlab.
Please see aiidalab-launch --help
for a full list of available commands and options.
Please see the AiiDAlab documentation for information on how to use and deploy AiiDAlab docker images in alternative ways.
Users of AiiDAlab are kindly asked to cite the following publication in their own work:
A. V. Yakutovich et al., Comp. Mat. Sci. 188, 110165 (2021). DOI:10.1016/j.commatsci.2020.110165
This work is supported by the MARVEL National Centre for Competency in Research funded by the Swiss National Science Foundation, as well as by the MaX European Centre of Excellence funded by the Horizon 2020 EINFRA-5 program, Grant No. 676598.