Установка GitLab Server с помощью Docker на Ubuntu 22.04

Важно: в примерах используются FQDN и порты по умолчанию. Замените gitlab.example.com и учетные данные на свои значения перед запуском.

Основные варианты запросов и цели статьи

• Основная цель: Установить GitLab CE в Docker на Ubuntu 22.04.
• Варианты связанных запросов: установка GitLab Docker Ubuntu, GitLab Docker Compose, резервное копирование GitLab Docker, восстановление GitLab из бэкапа, настройка SMTP в GitLab.

О чём это руководство

Это подробная практическая инструкция по развертыванию GitLab Community Edition в Docker-контейнере на сервере с Ubuntu 22.04. Руководство охватывает: подготовку сервера, настройку брандмауэра, установку Docker и Docker Compose (плагин v2), создание томов для хранения данных, файл docker-compose.yml, первичную настройку GitLab, добавление SSH-ключей и создание первого проекта, управление контейнером, резервное копирование, восстановление и обновление.

Краткий план действий

1. Подготовка сервера и зависимости
2. Настройка UFW (HTTP/HTTPS/SMTP/SSH)
3. Установка Docker и Docker Compose (плагин v2)
4. Подготовка томов и docker-compose
5. Запуск контейнера и первичная настройка (root-пароль, доступ по HTTPS)
6. Настройка профиля, безопасность и отключение Prometheus при необходимости
7. Создание проекта, добавление SSH-ключа, пуш коммита
8. Резервное копирование, восстановление, обновление

H2: Требования и предпосылки

• Сервер с Ubuntu 22.04 LTS.
• Непривилегированный пользователь с правами sudo.
• UFW (Uncomplicated Firewall) включён и работает.
• Полностью квалифицированное доменное имя (FQDN), указывающее на этот сервер, например gitlab.example.com.
• Система обновлена: выполните sudo apt update && sudo apt upgrade перед началом.

Примечание: если вы используете облачного провайдера, убедитесь, что публичный IP и DNS-запись корректно настроены.

H2: Фактические элементы, которые нужно знать

Факт-бокс (ключевые элементы):

• Важные порты: 80 (HTTP), 443 (HTTPS), 22 (SSH внутри контейнера), 587 (SMTP для отправки почты).
• Директории для персистентных данных: /srv/gitlab/{config,logs,data} (в примере используется $GITLAB_HOME=/srv/gitlab).
• Образ Docker: gitlab/gitlab-ee:latest (в примере используется EE-образ; для Community замените на gitlab/gitlab-ce:latest при желании).
• Рекомендуемый shm_size: минимум 256m, если вы хотите использовать Prometheus-метрики.

H2: Шаг 1 — Настройка брандмауэра (UFW)

Разрешите доступ по HTTP и HTTPS перед установкой.

Проверка статуса UFW:

$ sudo ufw status

Если UFW активен, разрешите HTTP и HTTPS:

$ sudo ufw allow http
$ sudo ufw allow https

Откройте порт для отправки почты (пример 587, ваш SMTP-порт может отличаться):

$ sudo ufw allow 587

Если вы меняете системный SSH-порт (рекомендуется, см. ниже), разрешите и его:

$ sudo ufw allow 2425

Проверьте статус после изменений:

$ sudo ufw status

H2: Шаг 2 — Установка зависимостей

Установите пакеты, которые понадобятся при установке Docker и работе GitLab:

$ sudo apt install ca-certificates curl openssh-server apt-transport-https gnupg lsb-release -y

Некоторые пакеты могут быть уже установлены по умолчанию.

H2: Шаг 3 — Изменение системного SSH-порта (опционально, но рекомендуется)

GitLab использует SSH внутри контейнера; чтобы избежать конфликта с системным SSH, смените системный SSH-порт.

Откройте /etc/ssh/sshd_config для редактирования:

$ sudo nano /etc/ssh/sshd_config

Найдите строку

#Port 22

удалите решётку и укажите другой порт, например 2425:

Port 2425

Сохраните файл и перезапустите службу SSH:

$ sudo systemctl restart sshd

Откройте этот порт в UFW:

$ sudo ufw allow 2425

Затем завершите текущую SSH-сессию и подключитесь снова с указанием нового порта:

$ ssh username@ -p 2425

Внимание: перед закрытием текущей сессии убедитесь, что новый порт действительно работает.

H2: Шаг 4 — Установка Docker и Docker Compose (плагин v2)

Добавьте официальный GPG-ключ Docker:

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg

Добавьте репозиторий Docker:

$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Обновите индекс пакетов и установите Docker Engine с плагином compose:

$ sudo apt update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

Плагин Docker Compose v2 используется как встроенная команда docker compose (без дефиса).

Добавьте своего пользователя в группу docker, чтобы не использовать sudo для каждой команды docker:

$ sudo usermod -aG docker ${USER}

Примените изменения (перезайдите в сессию или выполните):

$ su - ${USER}

H2: Шаг 5 — Подготовка Docker-томов и переменных окружения

Создайте основную директорию для данных GitLab и рабочую папку для compose:

$ sudo mkdir -p /srv/gitlab
$ mkdir -p ~/gitlab-docker
$ cd ~/gitlab-docker

Создайте файл .env с переменными окружения:

$ nano .env

Вставьте:

GITLAB_HOME=/srv/gitlab

Таблица соответствий томов (локальный → контейнер → назначение):

H2: Шаг 6 — Создание docker-compose.yml и запуск GitLab

Создайте файл docker-compose.yml:

$ nano docker-compose.yml

Вставьте (пример настроек, сохраните с нужными значениями):

version: '3.6'
services:
  web:
    image: 'gitlab/gitlab-ee:latest'
    container_name: 'gitlab-howtoforge'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
        gitlab_rails['smtp_enable'] = true
        gitlab_rails['smtp_address'] = "email-smtp.us-west-2.amazonaws.com"
        gitlab_rails['smtp_user_name'] = "SESUsername"
        gitlab_rails['smtp_password'] = "SESKey"
        gitlab_rails['smtp_domain'] = "example.com"
        gitlab_rails['smtp_enable_starttls_auto'] = true
        gitlab_rails['smtp_port'] = 587
        gitlab_rails['smtp_authentication'] = "login"
        gitlab_rails['gitlab_email_from'] = '[email protected]'
        gitlab_rails['gitlab_email_reply_to'] = '[email protected]'
        # Add any other gitlab.rb configuration here, each on its own line
    ports:
      - '80:80'
      - '443:443'
      - '22:22'
      - '587:587'
    volumes:
      - '$GITLAB_HOME/config:/etc/gitlab'
      - '$GITLAB_HOME/logs:/var/log/gitlab'
      - '$GITLAB_HOME/data:/var/opt/gitlab'
    shm_size: '256m'

Объяснение ключевых опций:

• image: образ GitLab в Docker Hub.
• container_name: удобная метка контейнера.
• restart: always — контейнер будет перезапущен автоматически при падении.
• hostname и external_url — указывают внешний адрес установки; при https GitLab попытается получить Let’s Encrypt сертификат по умолчанию.
• SMTP-настройки: нужны для отправки уведомлений, восстановления паролей и т. п.
• порты: хост:контейнер. При конфликте портов укажите другой хост-порт, например 3333:22 и добавьте соответствующую настройку gitlab_shell_ssh_port.

Запустите контейнеры в фоновом режиме:

$ docker compose up -d

Следите за логами:

$ docker logs gitlab-howtoforge -f

Найдите автоматически сгенерированный root-пароль (начиная с GitLab 14.0) в файле initial_root_password:

$ sudo cat /srv/gitlab/config/initial_root_password

Скопируйте пароль и сохраните в защищённом месте; файл будет удалён после первой перезагрузки конфигурации.

H2: Шаг 7 — Первичная настройка GitLab через веб-интерфейс

Откройте https://gitlab.example.com в браузере.

Используйте логин root и пароль из файла initial_root_password.

После входа выполните минимум настроек безопасности:

1. Отключите публичную регистрацию, если вы не хотите, чтобы любой мог зарегистрироваться.
2. Замените пароль root на собственный.
3. Измените имя пользователя root на более подходящее (или создайте отдельную учётную запись администратора).
4. Включите двухфакторную аутентификацию для аккаунтов администраторов и критичных пользователей.

Изображения интерфейса (вставлены для наглядности):

Ограничение регистрации пользователей

Отключение регистрации:

• На стартовом экране может появиться подсказка — нажмите Turn off (Выключить).
• Если подсказка не показалась, перейдите в Admin Panel → Settings → General → Sign-up restrictions и снимите галочку Sign-up enabled.

Настройка профиля и смена пароля root

• Edit profile → обновите имя, e‑mail и другие данные.

• Password → смените пароль root и подтвердите; после смены вы будете выведены из сессии.

Отключение Prometheus и повышение приватности

Если вы не используете встроенные метрики Prometheus, можно отключить их, чтобы сэкономить память и пространство /dev/shm.

• Admin Panel → Settings → Metrics and profiling → Metrics - Prometheus → Снимите Enable health and performance metrics endpoint.

Для приватности отключите Service Ping:

• Metrics and profiling → Usage statistics → снимите Enable Service Ping.

H2: Шаг 8 — Создание первого проекта и добавление SSH-ключа

Генерация SSH-ключа (если ещё нет)

На клиентской машине создайте ключ ed25519:

$ ssh-keygen -t ed25519 -C "gitlab.example.com"

Добавьте агенту SSH приватный ключ:

Linux/macOS:

$ eval $(ssh-agent -s)
$ ssh-add ~/.ssh/id_ed25519

Windows (PowerShell):

$ ssh-add C:\Users\\.ssh\id_ed25519

Добавьте в ~/.ssh/config запись:

Host gitlab.example.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/id_ed25519

Скопируйте содержимое публичного ключа:

$ cat ~/.ssh/id_ed25519.pub

Добавьте ключ в GitLab: Profile → SSH Keys → вставьте ключ и нажмите Add Key.

Проверьте подключение по SSH:

$ ssh -T [email protected]

Вы получите приветственное сообщение при успешном подключении.

H2: Шаг 9 — Создание проекта, клонирование и первый коммит

Создайте новый проект через веб-интерфейс → New project → Create blank project.

Клонируйте репозиторий по SSH и добавьте файл:

$ git clone [email protected]:user/howtoforge-test.git
$ cd howtoforge-test
$ touch CHANGELOG
$ git add CHANGELOG
$ git commit -m "add Changelog"
$ git push -u origin main

После пуша вы увидите файл в веб-интерфейсе проекта.

H2: Шаг 10 — Управление контейнером GitLab

Остановка контейнеров (из директории с docker-compose.yml):

$ docker compose down

Запуск в фоне:

$ docker compose up -d

Перезапуск контейнера (без учёта изменений в compose):

$ docker compose restart

Если вы изменили docker-compose.yml или переменные окружения, примените изменения так:

$ docker compose down --remove-orphans
$ docker compose up -d

Доступ в контейнер:

$ docker exec -it  bash

H2: Шаг 11 — Резервное копирование GitLab

Создание резервной копии (в контейнере gitlab-howtoforge):

$ docker exec -t gitlab-howtoforge gitlab-backup create

Файл бэкапа сохраняется в /srv/gitlab/data/backups.

Важно: gitlab-secrets.json находится в /srv/gitlab/config и не включается в этот бэкап, его нужно сохранять отдельно. Если вы управляете настройками через GITLAB_OMNIBUS_CONFIG в docker-compose, сохраните также docker-compose.yml и .env.

Рекомендуется автоматизировать резервное копирование cron‑задачей, копируя бэкапы на удалённый хранилище.

H2: Шаг 12 — Восстановление из резервной копии

На восстановительной машине подготовьте установленный GitLab и соответствующие директории (/srv/gitlab/{config,data,logs}).

Остановите сервисы puma и sidekiq внутри контейнера перед восстановлением:

$ docker exec -it  gitlab-ctl stop puma
$ docker exec -it  gitlab-ctl stop sidekiq

Проверьте статус:

$ docker exec -it  gitlab-ctl status

Скопируйте файл бэкапа в /srv/gitlab/data/backups на новой машине и выполните команду восстановления, указав имя бэкапа без суффикса _gitlab_backup.tar:

$ docker exec -it  gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

Замените gitlab-secrets.json и при необходимости перенесите docker-compose.yml/.env.

Запустите контейнеры заново:

$ docker compose down --remove-orphans
$ docker compose up -d

Проверьте целостность установки:

$ docker exec -it  gitlab-rake gitlab:check SANITIZE=true

H2: Шаг 13 — Обновление GitLab

Процесс обновления для минорных версий:

1. Сделайте бэкап.
2. Остановите контейнеры: docker compose down –remove-orphans
3. Выполните docker compose pull
4. Запустите docker compose up -d

Для крупных (major) обновлений следуйте официальной документации GitLab: иногда требуется промежуточное обновление между версиями.

H2: Альтернативные подходы (когда этот метод не подходит)

1. Установка Omnibus-пакета (apt) напрямую на хост — проще для отдельных серверов без контейнеризации и когда не требуется многоконтейнерное окружение.
2. Разворачивание в Kubernetes с использованием Helm-чартов — подходит для продакшн‑кластеров с высоким уровнем автоматизации.
3. Использование облачного GitLab (gitlab.com) — избавляет от администрирования инфраструктуры, подходит для команд, не желающих управлять сервером.

Когда этот метод может не подойти:

• Если у вас нет опыта с Docker и контейнерами в продакшне;
• Если требуется тонкая интеграция с существующей системой мониторинга/логирования, и вы предпочитаете нативную установку;
• Когда нужна поддержка enterprise‑функций, недоступных в CE (в этом случае рассмотрите GitLab EE или SaaS‑решения).

H2: Ментальные модели и эвристики для эксплуатации

• Разделяйте конфигурацию и данные: держите docker-compose.yml, .env и gitlab-secrets.json в системе управления конфигурацией и в резервных копиях.
• Имутабельность контейнера: не храните важные данные внутри контейнера; используйте привязанные тома.
• Безопасность по умолчанию: отключайте публичную регистрацию и включайте 2FA для администраторов.
• Принцип наименьших привилегий: используйте отдельные аккаунты админов и сервисные пользователи.

H2: Риски и меры смягчения

Риск: потеря gitlab-secrets.json → частичная потеря возможности расшифровки токенов. Митигирование: всегда делать отдельную резервную копию /srv/gitlab/config/gitlab-secrets.json и хранить её в безопасном месте.

Риск: нехватка /dev/shm для Prometheus → проблемы с метриками. Митигирование: установить shm_size минимум 256m или отключить Prometheus, если он не нужен.

Риск: взлом веб-интерфейса при открытой регистрации. Митигирование: отключить Sign-up enabled и настроить SSO или LDAP для централизованной аутентификации.

H2: Роль‑ориентированные контрольные списки

Контрольный список для админа (перед запуском):

• DNS A/AAAA запись настроена на сервер.
• UFW разрешает 80/443/SMTP/SSH-порт.
• Docker и docker-compose установлены.
• /srv/gitlab exists и имеет корректные права.
• Файлы docker-compose.yml и .env доступны в репозитории конфигурации.

Контрольный список DevOps (после запуска):

• Проверить, что контейнеры поднялись и сервисы работают (docker ps).
• Проверить логи на ошибки (docker logs).
• Убедиться, что root-пароль извлечен и изменён.
• Настроить мониторинг и оповещения для доступности сервиса.

Контрольный список разработчика:

• Настроен SSH-ключ в профиле.
• Можно клонировать/пушить репозитории.
• CI/CD раннеры настроены (при необходимости).

H2: SOP — стандартная операционная процедура (резервное копирование и восстановление)

1. Плановая резервная копия:
   • Выполнять gitlab-backup create внутри контейнера.
   • Сохранять gitlab-secrets.json и docker-compose.yml отдельно.
   • Переносить бэкап на удалённое хранилище (S3, NFS, SCP).
2. Восстановление:
   • Поднимите базовую установку GitLab с теми же путями.
   • Остановите puma/sidekiq.
   • Скопируйте бэкап в /srv/gitlab/data/backups.
   • Выполните gitlab-backup restore с нужным именем.
   • Восстановите gitlab-secrets.json и docker-compose.yml.
   • Поднимите контейнеры и проверьте gitlab-rake gitlab:check.

H2: Набор полезных сниппетов и шаблонов

docker-compose.yml (минимум): см. раздел выше.

Пример команды для просмотра логов и фильтрации ошибок:

$ docker logs gitlab-howtoforge 2>&1 | grep -i error | tail -n 50

Команда для обновления образов и перезапуска:

$ docker compose pull
$ docker compose down --remove-orphans
$ docker compose up -d

H2: Критерии приёмки

Чтобы считать установку успешной, проверьте:

• По адресу https://<ваш домен> доступна страница логина GitLab.
• Вход под root работает, пароль изменён и сохранён.
• Можно создать проект, клонировать его и запушить изменения через SSH и HTTPS.
• Резервное копирование создает архив в /srv/gitlab/data/backups.
• При необходимости отключен Prometheus и Service Ping.

H2: Примеры отказов и способы диагностики

Ситуация: контейнер не поднимается — проверьте docker logs и свободное место на диске (особенно в /srv/gitlab/data).

Ситуация: SSL не получен автоматически — убедитесь, что порт 80 и 443 доступны и DNS указывает на сервер; проверьте логи certbot в контейнере.

Ситуация: SMTP не отправляет почту — проверьте корректность данных smtp_address, smtp_port, аутентификацию и наличие разрешений у провайдера (например, SES требует подтверждения домена).

H2: Сравнение подходов (кратко)

• Docker Compose: быстрый старт, простота копирования конфигурации, хорошо подходит для одного сервера.
• Omnibus пакет (apt): исторически простой путь, менее контейнеризированный.
• Kubernetes + Helm: масштабируемость и интеграция с корпоративной инфраструктурой, требует большего уровня экспертизы.

H2: Словарь терминов (1‑строчные определения)

• FQDN: Fully Qualified Domain Name — полное доменное имя сервера.
• Omnibus: упакованная версия GitLab, включающая все зависимости.
• CE/EE: Community Edition / Enterprise Edition GitLab.
• shm_size: размер разделяемой памяти контейнера (/dev/shm).

H2: Дополнительные советы по эксплуатации

• Храните ключи и секреты в защищённом хранилище (Vault, KMS).
• Автоматизируйте обновления образов и проверяйте изменения в staging перед prod.
• Настройте мониторинг: availability, disk usage, CPU, memory, health endpoints.

Итог и дальнейшие шаги

Вы развернули GitLab CE в Docker на Ubuntu 22.04, настроили базовую безопасность, создали проект и выполнили первый push. Дальше можно:

• Настроить CI/CD пайплайны и раннеры;
• Подключить централизованную аутентификацию (LDAP/SSO);
• Автоматизировать бэкапы и тестировать процедуры восстановления;
• Рассмотреть миграцию на EE или SaaS, если нужны дополнительные функции.

Спасибо за внимание. Если у вас остались вопросы — опишите ситуацию и конфигурацию, и мы поможем с диагностикой.