tutum/builder

tutum/builder

镜像概述和主要用途

tutum/builder是一个用于从代码仓库构建、测试和推送Docker镜像的Docker镜像。它被Tutum平台用于自动化构建和测试流程。实现细节可参考博客文章。

核心功能和特性

• 支持从本地文件夹、Git仓库或压缩tarball构建Docker镜像
• 集成自动化测试流程，通过指定测试服务验证构建前的应用
• 提供钩子机制，允许在构建各阶段执行自定义脚本
• 支持多种认证方式，包括Docker配置文件、用户名密码及SSH密钥
• 可缓存镜像层以加速构建过程，支持复用已下载的镜像层

使用场景和适用范围

• CI/CD流程中的自动化构建、测试和推送环节
• 需要在隔离环境中进行Docker镜像构建的场景
• 从不同代码源（本地目录、Git仓库、压缩包）构建镜像的需求
• 需要自定义构建流程（如添加前置/后置操作）的场景

使用方法和配置说明

从本地文件夹构建

在需要构建和推送的文件夹中运行以下Docker命令：

bash
docker run --rm -it --privileged -v $HOME/.docker:/.docker:ro -v $(pwd):/app tutum/builder $IMAGE_NAME

参数说明：

• $IMAGE_NAME（可选）：要构建和推送的镜像名称，可包含标签，如tutum/hello-world:latest。若未指定，仅构建和测试，不推送。也可通过环境变量-e IMAGE_NAME=$IMAGE_NAME传入
• 容器会使用主机的~/.docker/config.json文件（通过docker login <registry>预先配置凭据），也可使用下文所述的$USERNAME、$PASSWORD和$EMAIL环境变量

从Git仓库构建

运行以下Docker命令：

bash
docker run --rm -it --privileged -v $HOME/.docker:/.docker:ro -e GIT_REPO=$GIT_REPO -e USERNAME=$USERNAME -e PASSWORD=$PASSWORD -e EMAIL=$EMAIL -e DOCKERFILE_PATH=$DOCKERFILE_PATH tutum/builder $IMAGE_NAME

参数说明：

• $GIT_REPO：要克隆和构建的Git仓库地址，如https://github.com/tutumcloud/quickstart-python.git
• $GIT_TAG（可选，默认master）：克隆后检出的标签/分支/提交，如master
• $DOCKERFILE_PATH（可选，默认/）：仓库根目录下Dockerfile的相对路径，如/
• $IMAGE_NAME：要创建的镜像名称（含可选标签），如tutum/quickstart-python:latest
• $USERNAME：用于登录镜像仓库的用户名
• $PASSWORD：用于登录镜像仓库的密码
• $EMAIL（可选）：用于登录镜像仓库的***

若使用SSH密钥克隆仓库，可将私钥挂载到容器内/root/.ssh/id_rsa，命令中添加-v ~/.ssh/id_rsa:/root/.ssh/id_rsa；或使用环境变量：

• $GIT_ID_RSA（可选）：用于克隆Git仓库的私钥，如-e GIT_ID_RSA="$(awk 1 ORS='\\n' ~/.ssh/id_rsa)"

从压缩tarball构建

运行以下Docker命令：

bash
docker run --rm -it --privileged -v $HOME/.docker:/.docker:ro -e TGZ_URL=$TGZ_URL -e DOCKERFILE_PATH=$DOCKERFILE_PATH -e USERNAME=$USERNAME -e PASSWORD=$PASSWORD -e EMAIL=$EMAIL tutum/builder $IMAGE_NAME

参数说明：

• $TGZ_URL：压缩tarball（.tgz）的下载URL，如https://github.com/tutumcloud/docker-hello-world/archive/v1.0.tar.gz
• $DOCKERFILE_PATH（可选，默认/）：tarball根目录下Dockerfile的相对路径，如/docker-hello-world-1.0
• $IMAGE_NAME：要创建的镜像名称（含可选标签），如tutum/hello-world:latest
• $USERNAME：用于登录镜像仓库的用户名
• $PASSWORD：用于登录镜像仓库的密码
• $EMAIL（可选）：用于登录镜像仓库的***

测试配置

若需在构建前测试应用，在仓库根目录创建docker-compose.test.yml文件，包含名为sut的服务（用于测试）。可通过$TEST_FILENAME指定其他文件名。若该容器成功退出（exit code 0），构建继续；否则构建失败，镜像不被构建或推送。

Django应用示例（依赖Redis缓存）：

yaml
sut:
  build: .
  links:
    - redis
  command: python manage.py test
redis:
  image: tutum/redis
  environment:
    - REDIS_PASS=password

为加速测试，可将sut服务中的build: .替换为image: this（引用测试前刚构建的镜像），避免重复构建。

钩子脚本

支持在构建各阶段执行自定义脚本，按以下顺序触发：

• hooks/post_checkout（挂载/app时不执行）
• hooks/pre_build
• hooks/build（覆盖默认构建步骤）
• hooks/post_build
• hooks/pre_test
• hooks/test（覆盖默认测试步骤）
• hooks/post_test
• hooks/pre_push
• hooks/push（覆盖默认推送步骤）
• hooks/post_push

在仓库中创建hooks文件夹，添加上述名称的脚本文件即可自动执行。

环境变量

执行docker-compose.test.yml和钩子脚本时可用以下环境变量：

• $GIT_BRANCH：当前测试的分支名称
• $GIT_TAG：当前测试的分支/标签/提交
• $GIT_SHA1：当前测试标签的提交哈希
• $IMAGE_NAME：正在构建的Docker仓库名称（启动容器时定义）
• $GIT_CLONE_OPTS：传递给git clone的选项，默认--recursive

注意事项

缓存镜像加速构建

如需缓存构建和测试所用镜像，先运行：

bash
docker run --name builder_cache --entrypoint /bin/true tutum/builder

后续构建时添加--volumes-from builder_cache以复用已下载的镜像层。

添加仓库凭证

若测试依赖私有镜像，可通过以下方式提供凭证：

• 挂载本地.docker文件夹：-v $HOME/.docker:/.docker:ro
• 通过环境变量传递Docker配置文件内容：-e DOCKER_CONFIG="$(cat $HOME/.docker/config.json)"

使用主机Docker守护进程

如需使用主机Docker守护进程而非容器内的Docker-in-Docker，添加挂载：-v /var/run/docker.sock:/var/run/docker.sock:rw

禁用git clone递归策略

若git clone --recursive因子模块凭据问题失败，可通过-e GIT_CLONE_OPTS=""禁用默认递归策略，然后在hooks/post_checkout或hooks/pre_build中手动执行git submodule init & git submodule update。