執行 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 run --dry-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 建置參數，但我們將這些值作為環境變數傳遞給 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 測試平台。

參數化（例如 C++ CMake 選項）是透過環境變數實現的，並具有有用的預設值，以保持建置配置的宣告性。

一個很好的例子是 cpp_build.sh 建置腳本，它將環境變數作為 CMake 選項轉發 - 因此可以在各種配置中調用相同的腳本，而無需更改它。有關範例，請參閱環境變數如何在 docker-compose.yml 的 C++ 映像檔中傳遞。

新增映像檔#

請參閱 docker-compose.yml 檔案中提供的內嵌註解。