chaste/release

Chaste Docker镜像文档

https://docs.docker.com/

https://github.com/Chaste/chaste-docker

TL;DR

1. https://docs.docker.com/get-docker/ 并分配至少4GB内存
2. docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 这是你在https://chaste.github.io/上的终端：
   `chaste@301291afbedf:~# Chaste Docker镜像文档

https://docs.docker.com/

https://github.com/Chaste/chaste-docker

TL;DR

1. https://docs.docker.com/get-docker/ 并分配至少4GB内存
2. docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 这是你在https://chaste.github.io/上的终端：

祝你使用愉快！;)

简介

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

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

Docker容器类比

Docker还提供镜像仓库存储预构建镜像：https://hub.docker.com/。用户可上传本地镜像（`docker push）或下载他人镜像（如docker pull`），包括官方容器化应用（如https://hub.docker.com/_/python、https://hub.docker.com/_/wordpress）及基础镜像（如https://hub.docker.com/_/ubuntu、https://hub.docker.com/_/alpine）。Docker架构和生态系统详见https://docs.docker.com/get-started/overview/#docker-architecture。

介绍Docker及本Chaste镜像使用的研讨会幻灯片见https://docs.google.com/presentation/d/1UqpN_9Jwfl-c1I9UpDGaIgm2GVSWffwk9rGkFhaq5_U/edit?usp=sharing。

快速开始

前提条件

安装https://www.docker.com/products/docker-desktop/，并配置至少4GB内存及尽可能多的CPU核心（超过4核需更多内存）。

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

[推荐] 使用预构建镜像

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

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

   如需特定版本，可在镜像名中指定https://hub.docker.com/repository/docker/chaste/release/tags，格式为`chaste/release:（如chaste/release:2024.1`），默认使用最新版本。

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

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

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

chaste@301291afbedf:~$

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

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

若无现有项目，可使用提供的new_project.sh脚本在~/projects中创建项目模板作为起点。项目教程见：https://chaste.cs.ox.ac.uk/trac/wiki/UserTutorials。

项目准备就绪后，使用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开发容器

若使用https://code.visualstudio.com/且已安装Docker，可克隆https://github.com/Chaste/Chaste并在VS Code中打开（如提示，安装https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack）。最后，在扩展提示时点击"在容器中重新打开"，将自动拉取、运行并挂载最新`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 https://docs.docker.com/storage/volumes/中，可在容器实例间持久化。但重置Docker后，所有卷及数据将丢失，因此需定期将项目推送到远程git仓库！

主机与容器间共享数据

本镜像使用https://docs.docker.com/storage/volumes/存储Chaste源代码、编译库和脚本，这是https://docs.docker.com/storage/，在多平台上具有最佳文件I/O性能。

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

Docker挂载选项的详细说明见https://docs.docker.com/storage/。

绑定挂载

可将主机目录（需绝对路径，如/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 docker.xuanyuan.run/chaste/release

数据复制

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

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

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

在容器中开发代码

推荐使用https://code.visualstudio.com/download及"https://code.visualstudio.com/docs/remote/remote-overview"扩展，可直接访问、编辑和搜索容器内文件，如同在主机上操作，同时保持卷中文件的高性能。

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

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

ℹ️ 如需从终端编辑代码，镜像中已安装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目录中https://chaste.cs.ox.ac.uk/trac/wiki/ChasteGuides/CmakeFirstRun#Testingstep：

bash
ctest -j$(nproc) -L Continuous

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

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

bash
ctest --verbose -R TestChasteBuildInfo$

测试详情见：https://chaste.cs.ox.ac.uk/trac/wiki/ChasteGuides/CmakeBuildGuide。

高级用法

构建自己的镜像

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

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

      bash
      docker build -t chaste:custom --build-arg GIT_TAG=develop https://github.com/chaste/chaste