chaste/release

Chaste Docker镜像文档

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


TL;DR

1. 安装Docker 并分配至少4GB内存
2. docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 这是你在https://chaste.github.io/%E4%B8%8A%E7%9A%84%E7%BB%88%E7%AB%AF%EF%BC%9A
   `chaste@301291afbedf:~# Chaste Docker镜像文档

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


TL;DR

1. 安装Docker 并分配至少4GB内存
2. docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 这是你在https://chaste.github.io/%E4%B8%8A%E7%9A%84%E7%BB%88%E7%AB%AF%EF%BC%9A

祝你使用愉快！;)

简介

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

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

Docker容器类比

Docker还提供镜像仓库存储预构建镜像：https://hub.docker.com/%E3%80%82%E7%94%A8%E6%88%B7%E5%8F%AF%E4%B8%8A%E4%BC%A0%E6%9C%AC%E5%9C%B0%E9%95%9C%E5%83%8F%EF%BC%88%60docker push）或下载他人镜像（如docker pull`），包括官方容器化应用（如https://hub.docker.com/_/python%E3%80%81https://hub.docker.com/_/wordpress%EF%BC%89%E5%8F%8A%E5%9F%BA%E7%A1%80%E9%95%9C%E5%83%8F%EF%BC%88%E5%A6%82https://hub.docker.com/_/ubuntu%E3%80%81https://hub.docker.com/_/alpine%EF%BC%89%E3%80%82Docker%E6%9E%B6%E6%9E%84%E5%92%8C%E7%94%9F%E6%80%81%E7%B3%BB%E7%BB%9F%E8%AF%A6%E8%A7%81%E6%AD%A4%E5%A4%84%E3%80%82

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

快速开始

前提条件

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

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

[推荐] 使用预构建镜像

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

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

   如需特定版本，可在镜像名中指定https://hub.docker.com/repository/docker/chaste/release/tags%EF%BC%8C%E6%A0%BC%E5%BC%8F%E4%B8%BA%60chaste/release:（如chaste/release:2024.1`），默认使用最新版本。

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

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

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

chaste@301291afbedf:~$

这是基于https://hub.docker.com/_/ubuntu%E7%9A%84%E9%9A%94%E7%A6%BBDocker%E5%AE%B9%E5%99%A8%E4%B8%AD%E7%9A%84bash%E6%8F%90%E7%A4%BA%E7%AC%A6%EF%BC%8C%E5%8C%85%E5%90%AB%E6%89%80%E6%9C%89%E4%BE%9D%E8%B5%96%E5%92%8C%E9%A2%84%E7%BC%96%E8%AF%91%E4%BB%A3%E7%A0%81%EF%BC%8C%E5%8F%AF%E7%9B%B4%E6%8E%A5%E6%9E%84%E5%BB%BA%E8%87%AA%E5%B7%B1%E7%9A%84Chaste%E9%A1%B9%E7%9B%AE%EF%BC%8C%E4%B8%94%E4%B8%8D%E5%BD%B1%E5%93%8D%E4%B8%BB%E6%9C%BA%E7%B3%BB%E7%BB%9F%E3%80%82

ℹ️ 如需查看运行中容器的资源使用情况，打开另一个终端并运行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，可克隆https://github.com/Chaste/Chaste%E5%B9%B6%E5%9C%A8VS 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文件夹，即可访问上述文件和目录。

ℹ️ 如需从终端编辑代码，镜像中已安装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 https://github.com/chaste/chaste