GitLab в Docker — продакшен-развёртывание

Графика с логотипом GitLab — стилизованная голова лисицы

Быстрая навигация

The Official Docker Image
Deploying GitLab With Docker
Investigating Deployment Issues
Configuring GitLab
Applying GitLab Updates
Backing Up Your Installation
Проверка приёмки и контроль качества
Резюме

Введение

GitLab — платформа для хранения Git-репозиториев, CI/CD и управления DevOps-процессами. Доступна как SaaS на GitLab.com и как self-managed дистрибутив для развёртывания на собственной инфраструктуре.

GitLab — составная система, где под капотом работает множество компонентов: PostgreSQL, Redis, Gitaly, Prometheus, Sidekiq, NGINX и основной Rails-приложение. Установка «в систему» добавит эти сервисы в хостовую ОС. Запуск же в Docker помещает всё внутрь контейнера и помогает изолировать зависимости от хоста.

Прежде чем начать: Docker не убирает минимальные требования GitLab. Для базового рабочего экземпляра требуется минимум ~4 ГБ свободной оперативной памяти и ~10 ГБ свободного дискового пространства; для активных команд потребуется значительно больше.

Скриншот панели GitLab после свежей установки версии 14.7

The Official Docker Image

GitLab предоставляет официальный Docker-образ, включающий все необходимые компоненты (Omnibus). Это максимально простой путь для запуска, однако образ монолитен: все сервисы работают в одном контейнере. Для небольших команд это удобно, но у таких контейнеров ограниченная масштабируемость и сложнее управление ресурсами.

Альтернатива для крупных установок — использование Helm-чарта для развёртывания в Kubernetes. Там каждый сервис запускается отдельным Pod’ом, что упрощает горизонтальное и вертикальное масштабирование.

Важно: официальный образ удобен для быстрого старта и тестирования, но опция для долгосрочной продакшен-эксплуатации должна оцениваться с учётом требований по доступности, резервному копированию и мониторингу.

Развёртывание GitLab в Docker — подготовка

Установите Docker (и Docker Compose, если планируете использовать compose).
Настройте DNS A-запись для домена, по которому будет доступен GitLab (пример: gitlab.example.com), указывающую на IP Docker-хоста.
Убедитесь, что у вас есть свободные порты 22 (SSH), 80 (HTTP) и 443 (HTTPS) на хосте.
Подготовьте тома Docker для хранения конфигурации, логов и данных — важный шаг, чтобы сохранить информацию вне контейнера.

Полный пример команды docker run

Ниже показан корректно оформленный и готовый к использованию пример команды. Обратите внимание на экранирование кавычек и использование volumes:

docker run -d \
  --hostname gitlab.example.com \
  --name gitlab \
  --restart unless-stopped \
  --shm-size=256m \
  -p 22:22 -p 80:80 -p 443:443 \
  -v gitlab_config:/etc/gitlab \
  -v gitlab_logs:/var/log/gitlab \
  -v gitlab_data:/var/opt/gitlab \
  gitlab/gitlab-ce:14.7.0-ce.0

Пояснения флагов (кратко):

-d — запустить контейнер в фоне.
-p — проброс портов (SSH/HTTP/HTTPS).
–name — удобное имя контейнера.
–hostname — должен совпадать с доменом, по которому вы будете заходить.
–restart — политика перезапуска для обработки сбоев/ребута хоста.
–shm-size — размер раздела /dev/shm (по умолчанию 64 МБ; GitLab рекомендует минимум 256 МБ).
-v — монтирование Docker-томов для сохранения конфигурации, логов и данных.

Контейнер загрузит образ gitlab/gitlab-ce:14.7.0-ce.0 и выполнит первичную настройку. Это займет несколько минут — дождитесь появления логов, указывающих на завершение настройки.

Скриншот начальных логов контейнера GitLab при развёртывании в Docker

Получение пароля root

После первой настройки веб-интерфейс будет доступен по указанному домену. Аккаунт root генерирует пароль автоматически. Получить его можно так:

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

Если вы использовали другое имя контейнера — подставьте его вместо gitlab.

Скриншот страницы входа GitLab

Отладка проблем развёртывания

Важно понимать, что инициализация GitLab — длительный процесс: много шагов конфигурации, миграции БД и сборки CSS/JS. Если веб-интерфейс недоступен — проверьте логи контейнера:

docker logs gitlab --follow

Советы при зависании выполнения или 500-х ошибках:

Дайте процессу больше времени — первые настройки могут занимать 5–15 минут и более.
Перезапуск контейнера иногда «дорезолвит» проблемы: docker restart gitlab.
Если логи не меняются и видите ошибки, изучите конкретные сообщения и ищите в документации GitLab соответствующие инструкции.

Распространённые ошибки и как их решать

Ошибка с записью в /dev/shm:

writing value to /dev/shm/gitlab/... failed with unmapped file

Причина: Docker по умолчанию предоставляет контейнеру только 64 МБ в /dev/shm, что недостаточно для Prometheus и других подсистем. Решение: при запуске задайте –shm-size, например, 256m или больше при высокой нагрузке.

Переполнение логов Docker (buffer overflow):

Логи GitLab (внутри контейнера и в Docker json-файлах на хосте) могут быстро расти. Для управления этой проблемой:

Очищайте старые лог-файлы внутри контейнера:

docker exec -it gitlab rm /var/log/gitlab/*

На хосте избегайте хранения логов в формате json-file без ротации. Рассмотрите смену драйвера логов на local или journald. Пример конфигурации демонстрации (daemon.json):

{
  "log-driver": "local",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

После изменения перезапустите Docker daemon.

Проблемы с нехваткой места или с I/O:

Проверяйте свободное место в томах, а также производительность дисковой подсистемы. Медленные диски могут замедлить миграции и фоновые задания.

Конфигурация GitLab в контейнере

Вы можете добавить фрагменты конфигурации при запуске через переменную окружения GITLAB_OMNIBUS_CONFIG. Это должна быть корректная Ruby-строка, которая будет дописана в /etc/gitlab/gitlab.rb.

Пример (обратите внимание на правильные кавычки и экранирование):

docker run -d \
  --hostname gitlab.example.com \
  --name gitlab \
  -e GITLAB_OMNIBUS_CONFIG="gitlab_rails['trusted_proxies'] = ['192.0.2.0/24']; nginx['redirect_http_to_https'] = true" \
  --shm-size=256m \
  -v gitlab_config:/etc/gitlab \
  -v gitlab_logs:/var/log/gitlab \
  -v gitlab_data:/var/opt/gitlab \
  gitlab/gitlab-ce:14.7.0-ce.0

Можно также редактировать /etc/gitlab/gitlab.rb внутри контейнера и затем перезапускать контейнер — при старте образ выполнит Omnibus reconfigure и применит изменения.

docker exec -it gitlab vi /etc/gitlab/gitlab.rb

docker restart gitlab

После перезапуска сервисы могут быть недоступны на несколько секунд, пока конфигурация применяется.

Обновления GitLab

Обновление в Docker — процесс замены контейнера на новый образ с сохранением томов. Процесс общий:

docker pull gitlab/gitlab-ce:
docker stop gitlab && docker rm gitlab
docker run … gitlab/gitlab-ce:

Пример получения нового образа:

docker pull gitlab/gitlab-ce:14.7.1-ce.0

Удаление старого контейнера (контейнер с томами можно удалить, тома при этом сохранятся):

docker rm gitlab

Повторный запуск — с теми же флагами и теми же volume-имёнами.

Удобство: Docker Compose

Чтобы не дублировать длинные флаги при каждом обновлении, храните конфигурацию в docker-compose.yml. Ниже — корректно оформленный пример compose-файла для Monolithic образа:

version: "3.8"

services:
  gitlab:
    image: gitlab/gitlab-ce:14.7.0-ce.0
    hostname: gitlab.example.com
    restart: unless-stopped
    shm_size: 256m
    ports:
      - "22:22"
      - "80:80"
      - "443:443"
    volumes:
      - gitlab_config:/etc/gitlab
      - gitlab_logs:/var/log/gitlab
      - gitlab_data:/var/opt/gitlab
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
        nginx['redirect_http_to_https'] = true

volumes:
  gitlab_config:
  gitlab_logs:
  gitlab_data:

Запуск:

docker-compose up -d

Чтобы обновиться, измените тег image и выполните docker-compose pull && docker-compose up -d. Docker Compose выполнит замену контейнера, монтируя прежние тома.

Замечание по маршруту обновлений

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

Резервное копирование и восстановление

Регулярные бэкапы — обязательны. GitLab хранит репозитории, CI-артефакты, настройки, и миграции. Docker-образ предоставляет утилиту gitlab-backup.

Создание бэкапа:

docker exec -t gitlab gitlab-backup create

По умолчанию архивы сохраняются в /var/opt/gitlab/backups — этот путь в контейнере монтируется в ваш Docker-том, так что бэкап окажется вне контейнера.

Резервирование в удалённое хранилище (S3 или совместимое): добавьте в gitlab.rb параметры для upload:

gitlab_rails['backup_upload_connection'] = {
  "provider" => "AWS",
  "region" => "eu-west-1",
  "aws_access_key_id" => "ACCESS_KEY",
  "aws_secret_access_key" => "SECRET_KEY"
  # "endpoint" => "https://s3.example.com"  # для совместимых S3
}

gitlab_rails['backup_upload_remote_directory'] = "gitlab-backups"

После настройки gitlab-backup create будет автоматически отправлять архивы в объектное хранилище.

Автоматизация (cron на хосте):

# каждый час
0 * * * * docker exec -t gitlab gitlab-backup create

Храните бэкапы отдельно от хоста и контейнера — например, на S3, NFS или другом удалённом хранилище. Тестируйте восстановление периодически.

Политики логирования и ротации

Docker json-file по умолчанию не подходит для больших продакшен-систем. Опции:

Поменять драйвер логов Docker на local/journald и настроить ротацию.
Внутри контейнера настроить logrotate или политику очистки старых файлов.
Перенаправлять системные логи в централизованный стек (ELK/EFK, Loki) для долгосрочного хранения и анализа.

Безопасность и аудит

Ограничьте доступ к Docker daemon (socket). Не давайте root-доступ пользователям, которым он не нужен.
Настройте TLS для доступа к GitLab через HTTPS. Рассмотрите автоматизацию сертификатов через Let’s Encrypt.
Настройте брандмауэр (iptables/nftables) и политики минимального доступа к портам.
Регулярно проверяйте обновления образа и ОС хоста.

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

Перед выпуском в продакшен проверьте следующее:

Веб-интерфейс доступен по HTTPS и корректно перенаправляет с HTTP.
Успешный вход как root и возможность создавать проект.
Репозиторий можно запушить и получить по SSH/Git.
CI runner запускает базовую pipeline.
Бекап создаётся и загружается в удалённое хранилище.
Логи ротации настроены и не приводят к переполнению диска.
Мониторинг базовых метрик (CPU, RAM, дисковая I/O) настроен.

Роль‑ориентированные чек‑листы

Администратор:

Убедиться в наличии DNS и корректном сертификате.
Проверить конфигурацию GITLAB_OMNIBUS_CONFIG.
Настроить бэкап и периодически тестировать восстановление.

SRE / инженер по надёжности:

Настроить мониторинг и оповещения (Prometheus/Grafana или аналог).
Оценить требования по памяти и CPU, запланировать масштабирование.
Настроить мощную дисковую подсистему или высокопроизводительный NFS.

Developer / команда разработки:

Проверить процесс CI/CD и регистрацию Runner’ов.
Тестировать push/pull и управление правами доступа.

Безопасность:

Провести аудит доступа к Docker сокету.
Настроить политику паролей и двухфакторную аутентификацию.
Проверить журналы аудита GitLab.

SOP: обновление GitLab в Docker (короткая инструкция)

Создать свежий бэкап: docker exec -t gitlab gitlab-backup create
Протестировать бэкап (опционально восстановить в тестовом контейнере).
docker pull gitlab/gitlab-ce:
docker-compose pull && docker-compose up -d (или вручную docker run с новым тегом)
Проверить логи: docker logs gitlab –follow
Убедиться, что веб-интерфейс и репозитории работают.
Мониторить метрики в течение первичных 24–48 часов.

План восстановления при отказе (Runbook)

Сценарий: контейнер не запускается / повреждение данных

Сохранить текущие логи и конфигурацию (docker cp, tar тома).
Откатить контейнер: остановить и запустить предыдущий образ, если доступен.
Если требуется восстановление из бэкапа — подготовить тестовый хост, развернуть образ с тем же тегом, смонтировать пустые тома и выполнить gitlab-backup restore.
Проверить целостность репозиториев и баз данных.
Перевести пользователей на read-only режим, пока идёт восстановление.

Тесты и критерии приёмки

Тестовые случаи, которые нужно выполнить перед объявлением продакшеном:

Регистрация проекта, push через SSH, clone через HTTPS.
Создание и успешный запуск простого pipeline.
Проверка восстановления из последнего бэкапа на тестовом инстансе.
Нагрузочный тест: симулировать пулл/пуш от N пользователей (определите N на вашей организации).
Проверка шаблона обновления (поднятие нового образа и проверка миграций).

Ментальные модели и рекомендации по выбору

Малые команды, тестовые проекты, PoC: официальный монолитный Docker-образ — быстрый путь.
Средние установки с растущими требованиями: использовать отдельную машину с Omnibus или Compose и подготовить план разделения сервисов.
Для высоких требований по доступности и масштабированию: Kubernetes с Helm-чартом GitLab, где каждый сервис — отдельный Pod.

Примеры альтернатив и когда они подходят

Omnibus на отдельном виртуальном сервере — проще интегрировать с хранилищем и безопасностью хоста.
Helm + Kubernetes — для крупных организаций, требующих независимого масштабирования Prometheus, Gitaly и прочих компонентов.
SaaS GitLab.com — если не хочется управлять инфраструктурой.

Decision flow (Mermaid)

flowchart TD
  A[Нужен GitLab?] --> B{Требования}
  B -->|Небольшая команда| C[Docker монолит]
  B -->|Средняя команда| D[Omnibus на VM / Compose]
  B -->|Большая, HA| E[Kubernetes + Helm]
  C --> F[Быстрый старт]
  D --> G[Удобное администрирование]
  E --> H[Гибкое масштабирование]

(Если ваш рендер не поддерживает Mermaid — визуализируйте как простую ветвящуюся логику.)

Глоссарий — 1 строка термина

Omnibus: собранный пакет GitLab, включающий все сервисы и утилиты.
Gitaly: сервис хранения и обслуживания Git-репозиториев в GitLab.
Prometheus: сервер мониторинга, собирающий метрики.
Runner: процесс, выполняющий CI задания.

Контрольные заметки и ограничения

Не храните секретные ключи прямо в gitlab.rb без доступа контроля.
Никогда не публикуйте бэкапы с приватными репозиториями в открытый доступ.
Документируйте процедуры обновления и восстановления внутри команды.

Короткое резюме

Docker-образ GitLab — удобный и быстрый способ запустить рабочий экземпляр. Для продакшен-эксплуатации важно:

Правильно смонтировать тома и настроить ротацию логов;
Увеличить /dev/shm через –shm-size;
Автоматизировать бэкапы и проверить процесс восстановления;
Подумать о масштабировании заранее: для больших нагрузок выбирайте Kubernetes.

Important: тестируйте обновления и восстановления на тестовой среде прежде чем применять их в продакшене.

Итог: Docker подходит для быстрого развёртывания и малых‑средних установок. Для корпоративной эксплуатации оцените требования по доступности и масштабируемости и выберите архитектуру (омнибус, Compose или Kubernetes) соответственно.