AiiDAlab Docker镜像栈

本仓库包含***AiiDAlab Docker镜像栈的Dockerfile。所有镜像均基于jupyter/minimal-notebook构建。

镜像变体

• base – 最小化镜像，预安装AiiDA并配置AiiDA环境。
• base-with-services – 基于base，额外在容器中安装AiiDA服务（PostgreSQL和RabbitMQ），并在启动时自动运行。
• lab – 基于base，使用AiiDAlab home应用作为主要界面（同时保留标准JupyterLab界面）。
• full-stack – 最全面的镜像，基于lab，并预安装和启动所有服务。

支持的标签（在Docker Hub发布）

• edge – 默认分支（main）的最新提交
• latest – 最新常规发布版本
• aiida-$AIIDA_VERSION – 指定AiiDA版本的最新常规发布（例如 aiida-2.0.0）
• python-$PYTHON_VERSION – 指定Python版本的最新常规发布（例如 python-3.9.13）
• $version – 特定发布版本（例如 2022.1001）

此外，镜像也在GitHub Container Registry (ghcr.io)内部发布。合并到默认分支的拉取请求会在ghcr.io上以pr-###标签发布，以便简化开发版本的测试。

快速启动

您可以直接使用Docker基于已发布的镜像启动容器，例如执行以下命令：

console
docker run -it -p 8888:8888 aiidalab/full-stack

不过，我们建议使用AiiDAlab Launch在本地生产环境中运行镜像。

注意：在最新版本的Mac OS-X上，您需要选择不同的端口，因为8888端口已被系统服务占用。

已知限制

• 通过NB_USER环境变量修改默认用户名（jovyan）及主目录位置目前不支持（#297）。

开发

开发环境

本仓库使用doit自动化工具自动化相关任务，包括构建、测试和使用docker-compose本地部署Docker镜像。

要使用此系统，请先设置构建和测试环境，并安装依赖：

console
pip install -r requirements.txt

本地构建镜像

构建镜像需运行doit build（已使用docker buildx v0.8.2测试）。

构建系统会自动检测本地架构并构建对应镜像（已测试amd64和arm64）。build、tests和up命令默认使用本地检测的平台，并基于本地git仓库状态生成版本标签。您也可以通过--platform和--version参数指定自定义平台或版本，例如：doit build --arch=arm64 --version=my-version。

默认会构建所有镜像变体。可使用-t/--target指定单个目标变体，例如：doit build --target base。

运行自动化测试

测试前需先按上一节所述构建镜像。然后使用doit tests --target <base|base-with-services|lab|full-stack>为指定镜像运行自动化测试。

提示：持续集成工作流会为所有合并到默认分支的拉取请求构建、发布（在ghcr.io上以pr-###标签）并测试镜像。

如需手动测试，可使用doit up --target full-stack启动镜像，但建议使用aiidalab-launch设置生产级本地部署。

持续集成

持续集成过程中，会为所有合并到默认分支的拉取请求构建linux/amd64和linux/arm64架构镜像，并推送到GitHub Container Registry（ghcr.io），标签为ghcr.io/aiidalab/*:pr-###。您可通过指定仓库和版本运行测试，例如：doit tests --registry=ghcr.io/ --version=pr-123。

创建发布

本项目使用日历版本控制（如v2022.1001），并通过bumpver自动化发布流程。创建发布前，请确保您在最新的main分支上，然后运行：

console
bumpver update

该命令会更新bumpver.toml中的版本，创建提交和标签，并推送到仓库以触发构建和发布流程。

使用AiiDAlab Launch部署AiiDAlab

aiidalab-launch工具提供便捷可靠的方式在计算机上启动和管理一个或多个AiiDAlab实例。使用方法如下：

通过pipx安装：

console
pipx install aiidalab-launch

然后启动AiiDAlab容器：

console
aiidalab-launch start

注意：AiiDAlab会持续运行，直到您使用aiidalab-launch stop显式停止或关闭/重启计算机。

完整命令和选项列表请参见aiidalab-launch --help。

云部署及其他部署方式

有关其他部署方式的信息，请参见AiiDAlab文档。

引用

AiiDAlab用户请在相关工作中引用以下文献：

A. V. Yakutovich et al., Comp. Mat. Sci. 188, *** (2021). DOI:10.1016/j.commatsci.2020.***

致谢

本工作得到MARVEL国家研究能力中心（由瑞士国家科学基金会资助）以及MaX欧洲卓越中心（由Horizon 2020 EINFRA-5计划资助，编号676598）的支持。

!MARVEL !MaX