运行 Docker 构建#

我们大部分基于 Linux 的持续集成任务都使用 Docker 和 Docker Compose 与公共 CI 服务解耦。保持 CI 配置最小化使得本地可复现成为可能。

用法#

有多种方法可以执行基于 Docker 的构建。推荐的方法是使用 Archery 工具。

示例#

列出可用的镜像

archery docker images

执行构建

archery docker run conda-python

Archery 调用以下 docker compose 命令

docker compose pull --ignore-pull-failures conda-cpp
docker compose pull --ignore-pull-failures conda-python
docker compose build conda-cpp
docker compose build conda-python
docker compose run --rm conda-python

显示 Docker Compose 命令而不是执行它们

archery docker --dry-run run conda-python

要禁用镜像拉取

archery docker run --no-cache conda-python

这相当于

docker compose build --no-cache conda-cpp
docker compose build --no-cache conda-python
docker compose run --rm conda-python

仅为叶子镜像禁用缓存

这对于强制构建依赖项的开发版本很有用。在下面的示例中，该命令构建了镜像树的 conda-cpp > conda-python > conda-python-pandas 分支，其中叶子镜像是 conda-python-pandas。

PANDAS=upstream_devel archery docker run --no-leaf-cache conda-python-pandas

这相当于

export PANDAS=upstream_devel
docker compose pull --ignore-pull-failures conda-cpp
docker compose pull --ignore-pull-failures conda-python
docker compose build conda-cpp
docker compose build conda-python
docker compose build --no-cache conda-python-pandas
docker compose run --rm conda-python-pandas

请注意，它不会拉取 conda-python-pandas 镜像，并在构建时禁用缓存。

PANDAS 是一个构建参数，请参阅 .env 文件中的默认值。

要完全跳过构建镜像

docker-compose 的层缓存机制可能不如 docker 的可靠，这取决于版本、cache_from 构建条目以及所使用的后端（docker-py、docker-cli、docker-cli 和 buildkit）。这可能导致不同的层哈希——即使重复执行相同的构建命令——最终导致缓存未命中和完整的镜像重建。

如果镜像已经构建但缓存无法正常工作，跳过构建阶段会很有用

# first run ensures that the image is built
archery docker run conda-python

# if the second run tries the build the image again and none of the files
# referenced in the relevant dockerfile have changed, then it indicates a
# cache miss caused by the issue described above
archery docker run conda-python

# since the image is properly built with the first command, there is no
# need to rebuild it, so manually disable the pull and build phases to
# spare the some time
archery docker run --no-pull --no-build conda-python

将环境变量传递给容器

容器中使用的多数构建脚本都可以通过环境变量进行配置。通过 --env 或 -e CLI 选项传递它们——类似于 docker run 和 docker compose run 接口。

archery docker run --env CMAKE_BUILD_TYPE=release ubuntu-cpp

有关 C++ 构建中可用的环境变量，请参阅 ci/scripts/cpp_build.sh 脚本。

使用自定义命令运行镜像

自定义 docker 命令可以作为第二个参数传递给 archery docker run。

以下示例在容器中启动一个交互式 bash 会话——这对于交互式调试构建很有用。

archery docker run ubuntu-cpp bash

构建镜像并增加调试输出

要启用额外的日志输出进行调试，请将 --debug 标志传递给 archery。

archery --debug docker run ubuntu-cpp

除了启用 DEBUG 级别日志记录之外，这还相当于将 --progress=plain 传递给 docker(-compose) build 命令。

Docker 卷缓存#

大多数 compose 容器都有从主机挂载的特定目录，以重用 ccache 和 maven 工件。这些 docker 卷放置在 .docker 目录中。

为了清理缓存，只需删除一个或多个目录（或整个 .docker 目录）。

开发#

Docker Compose 配置旨在利用分层镜像实现可重用的开发容器。例如，多种语言绑定都依赖于 C++ 实现，因此我们可以在构建 Glib、Ruby、R 和 Python 绑定时重用完全相同的 C++ 基础镜像，而不是在多个 Dockerfile 中重新定义 C++ 环境。这减少了重复并简化了维护，但也使 Docker Compose 配置更加复杂。

Docker 构建参数#

构建时参数被下推到 Dockerfile，以使镜像构建更加灵活。这些参数通常被称为 docker build args，但我们将这些值作为环境变量传递给 docker-compose.yml。构建参数广泛用于

  • 定义用于缓存的 docker 注册表

  • 平台架构

  • 操作系统和版本

  • 定义依赖项的各种版本

默认参数值存储在顶层 .env 文件中。有关详细示例，请参阅 docker-compose.yml。

构建脚本#

ci/scripts 目录下维护的脚本应保持参数化但合理最小化，以清晰地封装其负责的任务。例如：

  • cpp_build.sh：构建 C++ 实现而不运行测试。

  • cpp_test.sh：执行 C++ 测试。

  • python_build.sh：构建 Python 绑定而不运行测试。

  • python_test.sh：执行 Python 测试。

  • docs_build.sh：构建 Sphinx 文档。

  • integration_dask.sh：执行 dask 集成测试。

  • integration_pandas.sh：执行 pandas 集成测试。

  • install_minio.sh：为多个平台安装 minio 服务器。

  • install_conda.sh：为多个平台安装 miniconda。

  • install_gcs_testbench.sh：为多个平台安装 GCS testbench。

参数化（如 C++ CMake 选项）通过带有有用默认值的环境变量实现，以保持构建配置的声明性。

一个很好的例子是 cpp_build.sh 构建脚本，它将环境变量作为 CMake 选项转发——因此可以在各种配置中调用相同的脚本，而无需更改它。有关示例，请参阅 docker-compose.yml 的 C++ 镜像中如何传递环境变量。

添加新镜像#

请参阅 docker-compose.yml 文件中提供的内联注释。