chaste/release Docker 镜像 - 轩辕镜像

Chaste Docker镜像文档

![Chaste logo]([***]

Chaste的Docker镜像

![Docker Pulls]([] ![MIT License]([] ![DOI]([] ![Build chaste/base]([]

TL;DR

1. 安装Docker 并分配至少4GB内存
2. docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 这是你在Chaste上的终端：
   chaste@301291afbedf:~$
   祝你使用愉快！;)

简介

Docker 是一种轻量级虚拟化技术，允许应用程序及其所有依赖以平台无关的方式快速、轻松地运行。本项目提供包含Chaste的镜像（及部分便捷脚本），可通过单条命令启动，为癌症、心脏和软组织模拟提供跨操作系统和硬件配置的便携、同构计算环境。

Docker允许从纯文本Dockerfile构建和运行计算环境，类似于从源代码编译可执行文件（相当于用docker build从Dockerfile生成镜像）并执行（相当于用docker run运行容器）。这一类比的步骤如图所示（源自Nüst et al. 2020）。

Docker容器类比

Docker还提供镜像仓库存储预构建镜像：[***]docker push）或下载他人镜像（如docker pull），包括官方容器化应用（如Python、WordPress）及基础镜像（如Ubuntu、Alpine）。Docker架构和生态系统详见此处。

介绍Docker及本Chaste镜像使用的研讨会幻灯片见此处。

快速开始

前提条件

安装Docker，并配置至少4GB内存及尽可能多的CPU核心（超过4核需更多内存）。

⚠️ 务必为Docker分配至少4GB内存，否则编译可能因异常错误失败！

[推荐] 使用预构建镜像

1. 若需快速启动最新版本（已完全编译就绪），安装并配置Docker后运行：

   bash
   docker run --init -it --rm -v chaste_data:/home/chaste chaste/release
   

   如需特定版本，可在镜像名中指定可用标签，格式为chaste/release:<tag>（如chaste/release:2024.1），默认使用最新版本。

2. 若需使用develop分支的最新开发代码，运行以下命令拉取并运行chaste/develop镜像：

   bash
   docker run --init -it --rm -v chaste_data:/home/chaste chaste/develop
   

容器成功启动后，将显示类似以下的命令提示符：

chaste@301291afbedf:~$

这是基于ubuntu的隔离Docker容器中的bash提示符，包含所有依赖和预编译代码，可直接构建自己的Chaste项目，且不影响主机系统。

ℹ️ 如需查看运行中容器的资源使用情况，打开另一个终端并运行docker stats。

若无现有项目，可使用提供的new_project.sh脚本在~/projects中创建项目模板作为起点。项目教程见：[***]

项目准备就绪后，使用build_project.sh <TestMyProject> c（将<TestMyProject>替换为项目名）构建，输出文件将在~/output中（仅当创建新文件时需c参数）。

ℹ️ 如需在Docker容器与主机间共享数据（如output目录），可添加绑定挂载参数：-v /主机/路径/to/output:/home/chaste/output。详见绑定挂载。

使用完毕后，输入exit或按Ctrl+D关闭容器（必要时先按Ctrl+C停止运行中的进程）。/home/chaste中的更改将在重启容器时保留，但删除容器后，其他内容（如已安装包、系统文件更改）将重置为镜像初始状态。

[替代] 使用VS Code开发容器

若使用VS Code且已安装Docker，可克隆Chaste代码仓库并在VS Code中打开（如提示，安装Remote Development扩展包）。最后，在扩展提示时点击"在容器中重新打开"，将自动拉取、运行并挂载最新chaste/develop镜像。

ℹ️ 此方式会将本地克隆的Chaste代码挂载到容器中，覆盖镜像内置代码。预编译二进制基于镜像内部代码构建，但重新编译本地代码后可快速同步。

高级使用场景详见构建自己的镜像。

容器目录结构

容器启动后，将在chaste用户的主目录/home/chaste中显示以下结构：

bash
.
|-- build
|-- projects -> /home/chaste/src/projects
|-- scripts
|-- src
`-- output

各文件夹功能：

• build：预编译的Chaste二进制文件和库
• projects：指向/home/chaste/src/projects的符号链接，用于用户项目
• scripts：创建、构建和测试项目的便捷脚本
• src：Chaste源代码
• output：项目测试框架的输出目录（由$CHASTE_TEST_OUTPUT指定）

环境变量设置如下：

• CHASTE_DIR="/home/chaste"
• CHASTE_BUILD_DIR="${CHASTE_DIR}/build"
• CHASTE_PROJECTS_DIR="${CHASTE_DIR}/src/projects"
• CHASTE_SOURCE_DIR="${CHASTE_DIR}/src"
• CHASTE_TEST_OUTPUT="${CHASTE_DIR}/output"

ℹ️ 若构建自己的镜像，可通过构建参数在构建时修改CHASTE_DIR路径，例如--build-arg CHASTE_DIR=/path/to/alternative，其他目录将相对此路径设置。

主目录（/home/chaste）被指定为VOLUME，因此其中的更改在容器重启后保留。可挂载特定文件夹覆盖这些子目录（如挂载测试输出目录以便用ParaView可视化，或挂载不同版本的Chaste源代码）。通常，数据应存储在（命名）卷中以获得最佳文件I/O性能，但绑定挂载主机目录（如访问输出文件）较便捷，下文将说明。

⚠️ Docker容器本质上是临时的，退出后除卷或绑定挂载的主机文件夹外，所有更改将丢失。容器主目录内容（包括Chaste源代码和二进制文件）存储在Docker VOLUME中，可在容器实例间持久化。但重置Docker后，所有卷及数据将丢失，因此需定期将项目推送到远程git仓库！

主机与容器间共享数据

本镜像使用Docker卷存储Chaste源代码、编译库和脚本，这是推荐的数据持久化机制，在多平台上具有最佳文件I/O性能。

此类挂载的缺点是主机难以直接访问内容。但可通过绑定挂载直接访问容器的output等目录，或与容器共享主机数据集（甚至覆盖卷中的目录）。

Docker挂载选项的详细说明见存储文档。

绑定挂载

可将主机目录（需绝对路径，如/path/to/output）挂载到容器中（如output目录）。也可导航到主机上包含这些目录的文件夹（如Windows的C:\Users\$USERNAME\chaste或Linux/macOS的~/chaste），使用$(pwd)/output，示例命令如下（为简洁，镜像名假设为chaste/release，也可替换为chaste/develop或chaste/release:2024.1等）：

bash
docker run -it --init --rm -v chaste_data:/home/chaste -v "${PWD}"/output:/home/chaste/output chaste/release

数据复制

在macOS和Windows上（Linux除外），主机绑定挂载的文件I/O性能低于Docker卷。若模拟中涉及大量文件I/O（如output目录），建议将文件留在卷中，使用docker cp在模拟结束后复制到主机（或复制修改后的文件到容器）。

例如，若容器命名为chaste（启动时添加--name <name>），复制整个src文件夹的命令如下：

bash
docker cp chaste:/home/chaste/src .  # 复制到主机
# 在主机修改源代码后
docker cp src/. chaste:/home/chaste/src  # 复制回容器

在容器中开发代码

推荐使用VS Code及"Remote Development"扩展，可直接访问、编辑和搜索容器内文件，如同在主机上操作，同时保持卷中文件的高性能。

ℹ️ 以下步骤适用于推荐的预构建镜像方法。若使用VS Code开发容器，这些步骤将自动完成。

1. 从终端启动容器
2. 在VS Code中选择"远程容器：附加到正在运行的容器..."
3. 选择chaste-docker容器（名称随机，除非启动时添加--name <name>指定）
4. 用VS Code的文件浏览器打开/home/chaste文件夹，即可访问上述文件和目录。

替代方法 [点击展开]

1. 虽然将代码留在卷中性能更佳，但也可通过绑定挂载用主机目录覆盖卷的~/src文件夹，例如-v /path/to/chaste_code:/home/chaste/src。可能需要在容器中用build_chaste.sh <branch/tag>重新编译Chaste；若主机目录中已有代码，可跳过克隆直接用build_chaste.sh .编译。此方式使源代码在主机和容器中均可访问，无需复制或使用VS Code，但可能降低I/O性能。macOS上可通过delegated选项改善：--mount type=bind,source="$(pwd)"/chaste_code,destination=/home/chaste/src,consistency=delegated。

2. 或使用工具docker-sync：[***]

ℹ️ 如需从终端编辑代码，镜像中已安装nano和git（用于推送更改）。

安装额外软件

如需安装镜像中未包含的包，可运行：

bash
sudo apt-get update && sudo apt-get install <包名>

将<包名>替换为实际包名。提示时输入密码：chaste。

注意，此类安装的包在删除容器后不会保留（因相关文件未存储在/home/chaste中）。可通过省略docker run命令中的--rm标志，并使用docker start <容器名>重启容器来避免此问题。若认为某包应永久添加到Docker镜像，可发送建议邮件或提交PR。

测试

如需检查Chaste是否编译正确，可在CHASTE_BUILD_DIR目录中运行持续测试包：

bash
ctest -j$(nproc) -L Continuous

用户路径中提供了便捷脚本test.sh（位于/home/chaste/scripts）。

可单独运行以下测试快速检查构建环境和依赖：

bash
ctest --verbose -R TestChasteBuildInfo$

测试详情见：[***]

高级用法

构建自己的镜像

高级开发者如需构建特定代码分支的镜像，确保Docker已运行，继续阅读！以下示例将镜像标记为chaste:custom，建议使用更具描述性的名称。

1. 构建Chaste镜像：
   1. 基于Chaste GitHub develop分支的最新提交：

      bash
      docker build -t chaste:custom --build-arg GIT_TAG=develop [***]