aiidalab/full-stack

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，并预安装和启动所有服务。

支持的标签（在https://hub.docker.com/r/aiidalab%E5%8F%91%E5%B8%83%EF%BC%89

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

此外，镜像也在https://github.com/orgs/aiidalab/packages?ecosystem=container%E5%86%85%E9%83%A8%E5%8F%91%E5%B8%83%E3%80%82%E5%90%88%E5%B9%B6%E5%88%B0%E9%BB%98%E8%AE%A4%E5%88%86%E6%94%AF%E7%9A%84%E6%8B%89%E5%8F%96%E8%AF%B7%E6%B1%82%E4%BC%9A%E5%9C%A8ghcr.io%E4%B8%8A%E4%BB%A5%60pr-###%60%E6%A0%87%E7%AD%BE%E5%8F%91%E5%B8%83%EF%BC%8C%E4%BB%A5%E4%BE%BF%E7%AE%80%E5%8C%96%E5%BC%80%E5%8F%91%E7%89%88%E6%9C%AC%E7%9A%84%E6%B5%8B%E8%AF%95%E3%80%82

快速启动

您可以直接使用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

https://github.com/aiidalab/aiidalab-launch%E5%B7%A5%E5%85%B7%E6%8F%90%E4%BE%9B%E4%BE%BF%E6%8D%B7%E5%8F%AF%E9%9D%A0%E7%9A%84%E6%96%B9%E5%BC%8F%E5%9C%A8%E8%AE%A1%E7%AE%97%E6%9C%BA%E4%B8%8A%E5%90%AF%E5%8A%A8%E5%92%8C%E7%AE%A1%E7%90%86%E4%B8%80%E4%B8%AA%E6%88%96%E5%A4%9A%E4%B8%AAAiiDAlab%E5%AE%9E%E4%BE%8B%E3%80%82%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95%E5%A6%82%E4%B8%8B%EF%BC%9A

通过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