Help us learn about your current experience with the documentation. Take the survey.

在 Docker 容器中安装 GitLab

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

您可以使用 Docker Compose、Docker Engine 或 Docker Swarm 模式在 Docker 容器中安装 GitLab。

先决条件：

必须安装可用的 Docker 安装（非 Docker for Windows）。Docker for Windows 不受官方支持，因为镜像与卷权限存在已知兼容性问题，可能还有其他未知问题。如果您尝试在 Docker for Windows 上运行，请参阅获取帮助页面。该页面包含社区资源（如 IRC 或论坛）的链接，您可以在其中寻求其他用户的帮助。
必须安装邮件传输代理（MTA），例如 Postfix 或 Sendmail。GitLab 镜像不包含 MTA。您可以在单独的容器中安装 MTA。虽然可以在与 GitLab 相同的容器中安装 MTA，但每次升级或重启后可能需要重新安装 MTA。
不应在 Kubernetes 中部署 GitLab Docker 镜像，因为它会创建单点故障。如果您想在 Kubernetes 中部署 GitLab，请改用 GitLab Helm Chart 或 GitLab Operator。
必须为 Docker 安装提供有效且可从外部访问的主机名。请勿使用 localhost。

配置 SSH 端口

默认情况下，GitLab 使用端口 22 通过 SSH 与 Git 交互。若使用端口 22，请跳过本节。

若使用其他端口，您可以：

现在更改服务器的 SSH 端口（推荐）。此时 SSH 克隆 URL 无需包含新端口号：
```
ssh://git@gitlab.example.com/user/project.git
```
安装后更改 GitLab Shell SSH 端口。此时 SSH 克隆 URL 将包含配置的端口号：
```
ssh://git@gitlab.example.com:<portNumber>/user/project.git
```

更改服务器 SSH 端口的步骤：

使用编辑器打开 /etc/ssh/sshd_config，修改 SSH 端口：

Port = 2424

保存文件并重启 SSH 服务：

sudo systemctl restart ssh

验证 SSH 连接是否成功。打开新的终端会话，使用新端口 SSH 到服务器。

创建卷目录

托管 Gitaly 数据的卷有特定建议。基于 NFS 的文件系统可能导致性能问题，因此不推荐使用 EFS。

为配置文件、日志和数据文件创建目录。目录可位于用户主目录（例如 ~/gitlab-docker），或 /srv/gitlab 等路径。

sudo mkdir -p /srv/gitlab

如果您使用非 root 用户运行 Docker，请为新目录授予该用户适当权限。
配置新环境变量 $GITLAB_HOME 设置目录路径：

export GITLAB_HOME=/srv/gitlab

可选：将 GITLAB_HOME 环境变量追加到 shell 配置文件，使其应用于所有未来终端会话：

Bash: ~/.bash_profile
ZSH: ~/.zshrc

GitLab 容器使用主机挂载卷存储持久数据：

本地位置	容器位置	用途
`$GITLAB_HOME/data`	`/var/opt/gitlab`	存储应用程序数据。
`$GITLAB_HOME/logs`	`/var/log/gitlab`	存储日志。
`$GITLAB_HOME/config`	`/etc/gitlab`	存储 GitLab 配置文件。

查找要使用的 GitLab 版本和版本

在生产环境中，应将部署固定到特定 GitLab 版本。查看可用版本并选择您要在 Docker 标签页面中使用的版本：

标签名称包含以下部分：

gitlab/gitlab-ee:<version>-ee.0

其中 <version> 是 GitLab 版本，例如 16.5.3。版本名称中始终包含 <major>.<minor>.<patch>。

用于测试时，可使用 latest 标签（如 gitlab/gitlab-ee:latest），它指向最新的稳定版本。

以下示例使用稳定的企业版。若要使用候选发布版（RC）或每日镜像，请改用 gitlab/gitlab-ee:rc 或 gitlab/gitlab-ee:nightly。

安装社区版时，将 ee 替换为 ce。

安装

您可以通过以下方式运行 GitLab Docker 镜像：

使用 Docker Compose 安装 GitLab

通过 Docker Compose 可配置、安装和升级基于 Docker 的 GitLab 安装：

安装 Docker Compose。
创建 docker-compose.yml 文件。例如：

services:
  gitlab:
    image: gitlab/gitlab-ee:<version>-ee.0
    container_name: gitlab
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        # 在此处添加其他 gitlab.rb 配置，每行一条
        external_url 'https://gitlab.example.com'
    ports:
      - '80:80'
      - '443:443'
      - '22:22'
    volumes:
      - '$GITLAB_HOME/config:/etc/gitlab'
      - '$GITLAB_HOME/logs:/var/log/gitlab'
      - '$GITLAB_HOME/data:/var/opt/gitlab'
    shm_size: '256m'

阅读预配置 Docker 容器部分，了解 GITLAB_OMNIBUS_CONFIG 变量的工作原理。

以下是另一个使用自定义 HTTP 和 SSH 端口运行 GitLab 的 docker-compose.yml 示例。注意 GITLAB_OMNIBUS_CONFIG 变量与 ports 部分匹配：

services:
  gitlab:
    image: gitlab/gitlab-ee:<version>-ee.0
    container_name: gitlab
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://gitlab.example.com:8929'
        gitlab_rails['gitlab_shell_ssh_port'] = 2424
    ports:
      - '8929:8929'
      - '443:443'
      - '2424:22'
    volumes:
      - '$GITLAB_HOME/config:/etc/gitlab'
      - '$GITLAB_HOME/logs:/var/log/gitlab'
      - '$GITLAB_HOME/data:/var/opt/gitlab'
    shm_size: '256m'

此配置等同于使用 --publish 8929:8929 --publish 2424:22。

在与 docker-compose.yml 相同的目录中启动 GitLab：

docker compose up -d

使用 Docker Engine 安装 GitLab

或者，您可以使用 Docker Engine 安装 GitLab。

如果已设置 GITLAB_HOME 变量，请调整目录以满足需求并运行镜像：

如果不在 SELinux 环境中，运行以下命令：

sudo docker run --detach \
  --hostname gitlab.example.com \
  --env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com'" \
  --publish 443:443 --publish 80:80 --publish 22:22 \
  --name gitlab \
  --restart always \
  --volume $GITLAB_HOME/config:/etc/gitlab \
  --volume $GITLAB_HOME/logs:/var/log/gitlab \
  --volume $GITLAB_HOME/data:/var/opt/gitlab \
  --shm-size 256m \
  gitlab/gitlab-ee:<version>-ee.0

此命令下载并启动 GitLab 容器，并发布端口以访问 SSH、HTTP 和 HTTPS。所有 GitLab 数据存储为 $GITLAB_HOME 的子目录。容器在系统重启后自动重启。

如果在 SELinux 环境中，请改用以下命令：

sudo docker run --detach \
  --hostname gitlab.example.com \
  --env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com'" \
  --publish 443:443 --publish 80:80 --publish 22:22 \
  --name gitlab \
  --restart always \
  --volume $GITLAB_HOME/config:/etc/gitlab:Z \
  --volume $GITLAB_HOME/logs:/var/log/gitlab:Z \
  --volume $GITLAB_HOME/data:/var/opt/gitlab:Z \
  --shm-size 256m \
  gitlab/gitlab-ee:<version>-ee.0

此命令确保 Docker 进程有足够权限在挂载卷中创建配置文件。

如果您使用 Kerberos 集成，还必须发布您的 Kerberos 端口（例如 --publish 8443:8443）。否则将阻止使用 Kerberos 的 Git 操作。初始化过程可能需要很长时间。您可以通过以下命令跟踪该过程：

sudo docker logs -f gitlab

启动容器后，您可以访问 gitlab.example.com。Docker 容器可能需要一段时间才开始响应查询。

访问 GitLab URL，使用用户名 root 和以下命令中的密码登录：

sudo docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password

密码文件在容器首次重启后 24 小时内自动删除。

使用 Docker Swarm 模式安装 GitLab

通过 Docker Swarm 模式，您可以在 swarm 集群中使用 Docker 配置和部署 GitLab 安装。

在 Swarm 模式下，您可以使用 Docker secrets 和 Docker configurations 高效安全地部署 GitLab 实例。Secrets 可用于安全传递初始 root 密码，而无需将其作为环境变量暴露。Configurations 可帮助您保持 GitLab 镜像的通用性。

以下示例使用四个 runner 部署 GitLab 作为 stack，并使用 secrets 和 configurations：

设置 Docker swarm。
创建 docker-compose.yml 文件：

services:
  gitlab:
    image: gitlab/gitlab-ee:<version>-ee.0
    container_name: gitlab
    restart: always
    hostname: 'gitlab.example.com'
    ports:
      - "22:22"
      - "80:80"
      - "443:443"
    volumes:
      - $GITLAB_HOME/data:/var/opt/gitlab
      - $GITLAB_HOME/logs:/var/log/gitlab
      - $GITLAB_HOME/config:/etc/gitlab
    shm_size: '256m'
    environment:
      GITLAB_OMNIBUS_CONFIG: "from_file('/omnibus_config.rb')"
    configs:
      - source: gitlab
        target: /omnibus_config.rb
    secrets:
      - gitlab_root_password
  gitlab-runner:
    image: gitlab/gitlab-runner:alpine
    deploy:
      mode: replicated
      replicas: 4
configs:
  gitlab:
    file: ./gitlab.rb
secrets:
  gitlab_root_password:
    file: ./root_password.txt

为降低复杂性，上述示例排除了 network 配置。更多信息请参阅官方 Compose 文件参考。

创建 gitlab.rb 文件：

external_url 'https://my.domain.com/'
gitlab_rails['initial_root_password'] = File.read('/run/secrets/gitlab_root_password').gsub("\n", "")

创建名为 root_password.txt 的文件并包含密码：

MySuperSecretAndSecurePassw0rd!

确保您位于 docker-compose.yml 相同目录，然后运行：

docker stack deploy --compose-file docker-compose.yml mystack

安装 Docker 后，您需要配置 GitLab 实例。