dokku/ci-docker-image

ci-docker-image

用于CI/CD流水线的Docker镜像，旨在帮助将应用部署到Dokku服务器。

支持的CI系统

假设Docker镜像可作为CI任务运行并注入环境变量，以下CI系统的变量将被自动检测：

• circleci（CircleCI）
• cloudbees（CloudBees）
• drone（Drone CI）
• https://github.com/features/actions%EF%BC%88GitHub Actions）
• gitlab-ci（GitLab CI）
• semaphoreci（Semaphore CI）
• travisci（Travis CI）
• woodpecker ci（Woodpecker CI）

使用方法

该镜像提供两个供外部使用的二进制文件：

• dokku-deploy：触发配置的GIT_REMOTE_URL处的应用部署
• dokku-unlock：解锁配置的GIT_REMOTE_URL处应用的部署

要运行任一二进制文件，可在包含待部署仓库的非浅克隆目录中使用以下docker命令：

shell
# 其中.env文件包含GIT_REMOTE_URL和SSH_PRIVATE_KEY

# 部署
docker run --rm -v="$PWD:/app" --env-file=.env dokku/ci-docker-image dokku-deploy

# 解锁
docker run --rm -v="$PWD:/app" --env-file=.env dokku/ci-docker-image dokku-unlock

配置

支持以下环境变量：

• BRANCH：
  • 描述：推送到Dokku时部署的分支
  • 必填：否
  • 默认值：master
• CI_BRANCH_NAME：
  • 描述：触发部署的分支名称。若未提供则自动推断
  • 必填：否
  • 默认值：''
• CI_COMMIT：
  • 描述：将要推送的提交SHA。若未提供则自动推断
  • 必填：否
  • 默认值：''
• COMMAND：
  • 描述：执行操作的命令
  • 必填：否
  • 默认值：''
• DEPLOY_DOCKER_IMAGE：
  • 描述：通过git:from-image部署的Docker镜像
  • 必填：否
  • 默认值：''
• DEPLOY_USER_NAME：
  • 描述：部署Docker镜像时使用的用户名
  • 必填：否
  • 默认值：''
• DEPLOY_USER_EMAIL：
  • 描述：部署Docker镜像时使用的***
  • 必填：否
  • 默认值：''
• GIT_REMOTE_URL：
  • 描述：Dokku应用的Git仓库URL（SSH格式，见下文）
  • 必填：是
• GIT_PUSH_FLAGS：
  • 描述：推送时设置的标志字符串
  • 必填：否
• REVIEW_APP_NAME：
  • 描述：要创建或销毁的审查应用名称
  • 必填：否
  • 默认值：review-$APP_NAME-$CI_BRANCH_NAME
• SSH_HOST_KEY：
  • 描述：运行ssh-keyscan -t rsa $HOST的结果
  • 必填：否
  • 默认值：''
• SSH_PRIVATE_KEY：
  • 描述：具有Dokku实例推送权限的SSH私钥。优先级高于SSH_PRIVATE_KEY_BASE64
  • 必填：是
• SSH_PRIVATE_KEY_BASE64：
  • 描述：Base64编码的、具有Dokku实例推送权限的SSH私钥
  • 必填：是
• SSH_PASSPHRASE：
  • 描述：若SSH密钥有密码，则使用此密码
  • 必填：否
  • 默认值：''
• TRACE：
  • 描述：启用shell跟踪模式以调试操作执行过程
  • 必填：否
  • 默认值：''

GIT_REMOTE_URL SSH格式

GIT_REMOTE_URL值应指定为SSH格式，如下所示：

shell
# 未指定端口
ssh://dokku@dokku.me/node-js-app

# 指定可选端口
ssh://dokku@dokku.me:22/node-js-app

# 通用格式
ssh://dokku@HOSTNAME:PORT/APP_NAME

此格式模仿DSN格式，类似于常规git push dokku main命令使用的格式，但应用名称通过斜杠与主机名的其余部分分隔。端口为可选参数，允许根据需要将SSH服务器重新绑定到其他端口。

[!IMPORTANT] SSH密钥必须通过dokku ssh-keys:add命令添加到dokku用户，不能手动添加，否则应用名称将无法正确检测。

钩子

该镜像允许在应用部署过程中触发多种基于文件的钩子。这些钩子应为可执行文件，相对于dokku-deploy脚本执行的当前工作目录（通常是仓库根目录）。

脚本中可使用以下环境变量：

• APP_NAME：将要部署的远程应用名称。考虑了解析后的GIT_REMOTE_URL和REVIEW_APP_NAME。
• IS_REVIEW_APP：部署审查应用时为true，否则为false。
• SSH_REMOTE：解析后的SSH远程URL。

最简单的钩子是如下shell脚本：

shell
#!/bin/sh -l

echo "你好，世界"

[!NOTE] 本仓库使用的Docker镜像目前仅支持sh作为解释器。若需要其他解释器，应手动添加到环境中。

要执行远程dokku命令，可如下执行ssh二进制文件：

shell
#!/bin/sh -l

ssh "$SSH_REMOTE" -- version

此外，若Dokku命令仅需对审查应用执行，可检查IS_REVIEW_APP变量是否为true以包装审查应用特定逻辑：

shell
#!/bin/sh -l
if [ "$IS_REVIEW_APP" = "true" ]; then
  ssh "$SSH_REMOTE" -- config:set "$APP_NAME" "DOMAIN=$APP_NAME.dokku.me"
  echo "已配置审查应用域名"
fi

可用的钩子如下：

• bin/ci-pre-deploy：在任何应用设置之后、应用部署之前触发
• bin/ci-post-deploy：在应用部署之后触发
• bin/ci-pre-review-app-destroy：在审查应用销毁之前触发
• bin/ci-post-review-app-destroy：在审查应用销毁之后触发

构建

text
docker build -t dokku/ci-docker-image .