从 GitLab 部署

在本教程中，我们将介绍如何通过 GitLab 进行部署。需要说明的是，GitHub 的流程也非常相似。如果你在过程中遇到任何问题，请告诉我们！

1- 创建 GitLab 仓库

如果你还没有 GitLab 账号，请先注册一个。

点击 “New Project” 创建一个新的仓库
点击 “Create blank project”
为项目命名并完成创建

2- 添加示例源代码

本教程我们使用一个非常简单的示例源代码，只包含一个文件：

index.php

 <?php echo 'PHP output: Hello World!'; ?>

将该文件添加、提交并推送到 GitLab 仓库。随后你应该能在 GitLab 的网页界面中看到这个文件。

3- 准备 Dockerfile

为了在第三方构建系统上进行构建，你需要提供一个 Dockerfile。如果你使用的是 CapRover 的 templateId，可以直接使用 CapRover 仓库里现成可用的 Dockerfiles。

在本教程中，我们使用 PHP 的 Dockerfile：

Dockerfile

FROM php:7.3-apache
COPY ./ /var/www/html/

重要请确保文件名严格为 Dockerfile（大小写也要一致）。

将该文件添加、提交并推送。

4- 为 CapRover 创建访问令牌（Access Token）

CapRover 需要从 GitLab 拉取构建好的镜像，因此我们需要创建一个访问令牌。进入 User settings > Personal access tokens 并创建一个 token。

请确保为该 token 授予 read_registry 和 write_registry 权限。

创建完成后，继续下一步：

5- 将 Token 添加到 CapRover

Username: your gitlab username
Password: your gitlab Token [From the previous step]
Domain: registry.gitlab.com
Image Prefix: again, your gitlab username

注意：Image Prefix 取决于你在 GitLab 中的项目组织方式。如果你的仓库属于某个 group，那么 image prefix 应该是你的 group。一般来说，image prefix 是 domain 与镜像名之间的那一段。例如，下方示例中 my-group-project 就是该项目的 Image Prefix：

registry.gitlab.com/my-group-project/test:latest

保存该 registry 配置。

6- 禁用 Default Push

添加 registry 之后，CapRover 默认会把构建产物推送到你的 registry。这个教程并不需要该功能，而且它可能会导致部署失败。因此请将 Default Push 禁用。

7- 创建一个 CapRover 应用

在 CapRover 控制台创建一个应用，我们命名为 my-test-gitlab-deploy。

8- 创建 CI/CD 变量

接下来进入 GitLab 的项目页面，导航到 Settings > CI/CD，然后在 Variables 下添加如下变量：

Key : CAPROVER_URL , Value : https://captain.root.domain.com [replace it with your domain]
Key : CAPROVER_PASSWORD , Value : mYpAsSwOrD [replace it with your password]
Key : CAPROVER_APP , Value : my-test-gitlab-deploy [replace it with your app name]

把这 3 个变量都添加上。为了更好的安全性，请确保它们是 protected。即使不 masked 也没关系，它们不会出现在日志里。

9- GitLab CI 文件

到目前为止，我们的目录里有两个文件：index.php 和 Dockerfile。现在我们添加 GitLab 专用的构建指令：

重要请确保文件名严格为 .gitlab-ci.yml（以点开头，且大小写一致）。

.gitlab-ci.yml

build-docker-master:
  image: docker:19.03.1
  stage: build
  services:
    - docker:19.03.1-dind
  before_script:
    - export DOCKER_REGISTRY_USER=$CI_REGISTRY_USER # built-in GitLab Registry User
    - export DOCKER_REGISTRY_PASSWORD=$CI_REGISTRY_PASSWORD # built-in GitLab Registry Password
    - export DOCKER_REGISTRY_URL=$CI_REGISTRY # built-in GitLab Registry URL
    - export COMMIT_HASH=$CI_COMMIT_SHA # Your current commit sha
    - export IMAGE_NAME_WITH_REGISTRY_PREFIX=$CI_REGISTRY_IMAGE # Your repository prefixed with GitLab Registry URL
    - docker login -u "$DOCKER_REGISTRY_USER" -p "$DOCKER_REGISTRY_PASSWORD" $DOCKER_REGISTRY_URL # Instructs GitLab to login to its registry

  script:
    - echo "Building..." # MAKE SURE NO SPACE ON EITHER SIDE OF = IN THE FOLLOWING LINE
    - export CONTAINER_FULL_IMAGE_NAME_WITH_TAG=$IMAGE_NAME_WITH_REGISTRY_PREFIX/my-build-image:$COMMIT_HASH
    - docker build -f ./Dockerfile --pull -t built-image-name .
    - docker tag built-image-name "$CONTAINER_FULL_IMAGE_NAME_WITH_TAG"
    - docker push "$CONTAINER_FULL_IMAGE_NAME_WITH_TAG"
    - echo $CONTAINER_FULL_IMAGE_NAME_WITH_TAG
    - echo "Deploying on CapRover..."
    - docker run caprover/cli-caprover:v2.1.1 caprover deploy --caproverUrl $CAPROVER_URL --caproverPassword $CAPROVER_PASSWORD --caproverApp $CAPROVER_APP --imageName $CONTAINER_FULL_IMAGE_NAME_WITH_TAG
  only:
    - master

这份配置相当直观。最棒的是你不需要对这个文件做任何修改！ 无论你的仓库用什么语言、部署到哪里，它都可以保持一致。

这个文件里唯一会因项目不同而变化的，只有上一步设置的 3 个 CAPROVER_*** 变量值。

将该文件提交并推送到 GitLab 仓库。此时你的 GitLab 仓库至少应包含以下 3 个文件：

index.php
Dockerfile
.gitlab-ci.yml

等待一会儿，构建完成后会自动部署！几分钟后，你就可以在 CapRover 上看到已部署的应用了。

关于在私有 registry 中使用 `--imageName` 的说明

如果你在运行 caprover deploy --imageName 时遇到下面的错误，你可能需要让 Captain 实例对你的 registry 完成认证。因为本地登录并不代表 CapRover 也能访问该镜像。

Deploy failed!
Error: (HTTP code 404) unexpected - pull access denied for user_name/repo_name, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

在 CapRover 上登录你的私有 Docker 仓库：

进入 CLUSTER
点击 ADD REMOTE REGISTRY
填写相关信息并保存 registry
然后你就可以配合私有镜像仓库使用 caprover deploy --imageName

应用令牌

使用 CI/CD 时，很多情况下你会希望避免保存密码。你可以为每个应用创建专用的 token 来进行部署。

caprover deploy --appToken <YOUR_APP_TOKEN_HERE> --caproverUrl https://captain.domain.com --imageName YOUR_IMAGE_NAME --appName YOUR_APP_NAME

通常把 token 存在环境变量里更安全，CLI 会从 CAPROVER_APP_TOKEN 变量中读取它。

该功能从 CapRover 1.10 后端以及 2.2.0 版本的 CapRover CLI 开始可用。

替代方法

另外，你也可以使用 webhook 来替代 docker run caprover/cli-caprover:v2.1.1 caprover deploy....。这种方式会更复杂一些。

下面并不是一个可运行的示例，它只是用于提示 webhook 方案需要哪些步骤。

    - echo "Deploying on CapRover..."
    - export DEPLOY_BRANCH=deploy-caprover
    - cd ~
    - git clone your-repo
    - cd your-repo
    - git checkout $DEPLOY_BRANCH || git checkout -b $DEPLOY_BRANCH
    - git rm -rf .
    - git clean -fdx .
    - echo "{\"schemaVersion\":2,\"imageName\":\"$CONTAINER_FULL_IMAGE_NAME_WITH_TAG\"}" > captain-definition
    - git add .
    - git commit -m "Deploy $CONTAINER_FULL_IMAGE_NAME_WITH_TAG"
    - git push --set-upstream origin $DEPLOY_BRANCH
    - curl -X POST https://captain.rootdomain.com/your-webhook

On this page