Развёртывание GitLab в Docker — полное руководство для продакшн

Быстрые ссылки

• Официальный Docker-образ
• Развёртывание GitLab в Docker
• Отладка проблем развёртывания
• Настройка GitLab
• Обновление GitLab
• Резервное копирование установки
• Краткое резюме

GitLab — это платформа для размещения Git-репозиториев, CI/CD и DevOps-процессов. Он доступен как SaaS на GitLab.com и как самостоятельная (self-managed) установка под вашу администрацию.

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

В этом руководстве описано, как с помощью Docker развернуть боевой экземпляр GitLab, подходящий для хостинга кода и командной работы. Важно: Docker не отменяет аппаратных требований GitLab — потребуется минимум 4 ГБ свободной памяти и примерно 10 ГБ свободного дискового пространства; для комфортной работы рекомендуется больше.

Официальный Docker-образ

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

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

Предварительные требования

• Docker Engine установлен на хосте (современная версия).
• DNS A-запись для домена, например gitlab.example.com, указывает на IP Docker-хоста.
• Публичный сертификат TLS (или настройка Let’s Encrypt / прокси).
• Резервные копии и мониторинг для продакшн-окружения.

Совет по оценке ресурсов: если вы планируете более десятка активных разработчиков/CI-пайплайнов, увеличьте ОЗУ до 8–16 ГБ и используйте отдельный диск для /var/opt/gitlab.

Быстрое развёртывание

Запустите контейнер с привязкой портов и монтированием volume для персистентных данных:

docker run -d -p 22:22 -p 80:80 -p 443:443 \
  --name gitlab \
  --hostname gitlab.example.com \
  --restart unless-stopped \
  --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

Пояснения ключей:

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

Docker скачает образ GitLab CE и запустит контейнер. Рекомендуется фиксировать версию образа (тег) для контролируемых обновлений.

Дождитесь окончания первого запуска (несколько минут). После этого откройте https://gitlab.example.com и войдите как root. Пароль по умолчанию генерируется автоматически и хранится в файле /etc/gitlab/initial_root_password внутри контейнера:

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

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

Если UI недоступен, проверьте логи контейнера:

docker logs gitlab --follow

Если и логи, и UI «зависли», попробуйте перезапустить контейнер:

docker restart gitlab

Распространённая ошибка в логах:

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

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

Логи внутри /var/log/gitlab и лог-файлы Docker на хосте быстро растут. Для контейнера рекомендуется сменить драйвер логирования Docker с json-file на local или journald и настроить ротацию.

Пример очистки старых логов внутри контейнера:

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

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

Настройка GitLab

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

docker run -e GITLAB_OMNIBUS_CONFIG="gitlab_rails['allowed_hosts'] = ['gitlab.example.com']\nnginx['redirect_http_to_https'] = true" \
  ... gitlab/gitlab-ce:14.7.0-ce.0

Или отредактируйте /etc/gitlab/gitlab.rb внутри запущенного контейнера и перезапустите контейнер для применения изменений:

docker exec -it gitlab bash
# вне контейнера: docker restart gitlab

При каждом старте контейнер автоматически запускает Omnibus reconfigure, который применит текущую конфигурацию gitlab.rb. В это время сервисы могут быть недоступны несколько секунд.

Важно поддерживать корректность синтаксиса при вставке конфигурации через GITLAB_OMNIBUS_CONFIG: используйте переносы строки (\n) и экранирование кавычек.

Обновление GitLab

Процесс обновления при использовании Docker простой: остановите старый контейнер и запустите новый с теми же volume и флагами, но с обновлённым тегом образа.

1. Получите новый образ:

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

2. Остановите и удалите старый контейнер:

docker stop gitlab
docker rm gitlab

3. Запустите новый контейнер с прежними параметрами, указав новый тег.

Ваши данные безопасно находятся в volume и будут повторно подключены к новому контейнеру.

Чтобы не копировать длинную строку docker run каждый раз, используйте docker-compose:

version: '3.7'
services:
  gitlab:
    image: gitlab/gitlab-ce:14.7.1-ce.0
    hostname: gitlab.example.com
    ports:
      - '22:22'
      - '80:80'
      - '443:443'
    volumes:
      - gitlab_config:/etc/gitlab
      - gitlab_logs:/var/log/gitlab
      - gitlab_data:/var/opt/gitlab
    restart: unless-stopped
volumes:
  gitlab_config:
  gitlab_logs:
  gitlab_data:

Запуск/обновление:

docker-compose up -d

После обновления проверьте, требуется ли ручное выполнение миграций или пост-миграционные шаги, описанные в релизных заметках GitLab.

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

• UI доступен и проходит авторизация под root.
• Проекты и репозитории доступны и целы.
• CI-раннеры подключаются (если используются).
• Бэкапы доступны и восстановление тестировано.

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

Регулярные бэкапы жизненно важны. GitLab включает утилиту gitlab-backup для создания полного архива установки.

Создание резервной копии (локально в volume):

docker exec -t gitlab gitlab-backup create

По умолчанию бэкапы сохраняются в /var/opt/gitlab/backups, который смонтирован в volume. Для дополнительной защиты настраивайте загрузку бэкапов в объектное хранилище (S3-совместимое).

Пример настройки загрузки в S3 (фрагмент gitlab.rb):

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

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

Планирование через cron на хосте:

0 2 * * * docker exec -t gitlab gitlab-backup create

Проверьте периодически целостность архива и процедуру восстановления на тестовой среде.

Безопасность и эксплуатация

• Ограничьте доступ к Docker daemon (используйте сокеты с правами и или Rootless Docker).
• Примените firewall, откройте только необходимые порты (22/80/443), используйте прокси или WAF при необходимости.
• Следите за обновлениями безопасности образа и сторонних зависимостей.
• Для TLS используйте Let’s Encrypt или сторонние сертификаты на обратном прокси.

Важно: контейнеры с доступом к Docker сокету effectively дают root-доступ к хосту. Проектируйте безопасность соответственно.

Когда Docker-монолит не подходит

• Нагрузка растёт и требуется масштабирование отдельных сервисов (Gitaly, Sidekiq, PostgreSQL) — стоит перейти на Kubernetes с Helm chart.
• Требования к высокой доступности и геораспределению — рассмотрите HA-архитектуру GitLab с внешними базами данных и репликацией.
• Жёсткие требования к управлению журналами и интеграции с корпоративными SIEM — лучше разнести компоненты.

Альтернативные подходы

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

Инструментарий администратора — шпаргалка

Короткий список команд и мест для проверки:

• Просмотр логов контейнера:

docker logs gitlab --follow

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

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

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

docker exec -t gitlab gitlab-backup create

• Очистка логов внутри контейнера:

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

• Перезапуск контейнера:

docker restart gitlab

Playbook: обновление GitLab в Docker

1. Оповестите команду и остановите CI-планы.
2. Сделайте ручной бэкап: docker exec -t gitlab gitlab-backup create.
3. Проверьте целостность архива и загрузите копию в удалённое хранилище.
4. docker pull
5. docker stop gitlab && docker rm gitlab
6. docker run … с новым тегом или docker-compose pull && docker-compose up -d
7. Мониторьте логи и метрики 15–30 минут.
8. Откат: если критические ошибки, остановите новый контейнер, запустите предыдущую версию образа и восстановите из бэкапа при необходимости.

Инцидент-руководство (Runbook)

Симптом: 500 ошибки на UI, CI падают.

1. Проверить логи:

docker logs gitlab --tail 500

2. Если видно сообщение про /dev/shm — увеличить –shm-size и перезапустить контейнер с новым значением.
3. Если старт останавливается на миграции, дождаться её окончания или проверить процесс работы команды reconfigure внутри контейнера.
4. Если пространство на диске закончилось — очистить старые бэкапы, логи или подключить дополнительный диск к volume.
5. При невозможности восстановления — развернуть тестовую среду, пройти процедуру восстановления из бэкапа и сравнить конфигурации.

Дерево решений: Docker vs Kubernetes vs Omnibus

flowchart TD
  A[Нужен GitLab] --> B{Требуется масштабирование?}
  B -- Нет --> C[Docker/Omnibus на отдельном хосте]
  B -- Да --> D{Требуется HA и масштабирование компонентов?}
  D -- Да --> E[Kubernetes + Helm]
  D -- Нет --> F[Omnibus на выделенном сервере]
  C --> G[Хорошо для малых команд]
  E --> H[Подходит для предприятий]
  F --> I[Подходит для простого управления]

Рольевые чек-листы

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

• Настроить резервное копирование и проверку восстановлений.
• Настроить мониторинг и оповещения по доступности.
• Контролировать доступ к Docker daemon.

DevOps-инженер:

• Автоматизировать обновления через CI/CD или IaC.
• Настроить логирование и ротацию на уровне Docker.
• Оптимизировать параметры /dev/shm и ресурсы контейнера.

Разработчик:

• Проверить работу Git и CI после обновления.
• Сообщать о регрессиях и проблемах в issue tracker.

Мини-методология приёмки развёртывания

1. Установить и проверить доступность UI и SSH-пушей.
2. Выполнить тестовый CI-пайплайн и создать несколько репозиториев.
3. Выполнить бэкап и симулировать восстановление в тестовую среду.
4. Наблюдать метрики CPU/памяти/диска в течение 48 часов.

Тестовые сценарии и критерии приёмки

• Критерий: успешный вход в систему под root и доступ к проектам.
• Тест: клонирование репозитория по SSH и HTTP.
• Тест: запуск простого CI-пайплайна и успешное прохождение задач.
• Тест: создание и загрузка бэкапа, восстановление из него в тестовой среде.

Фактбокс — ключевые параметры

• Минимальная оперативная память: 4 ГБ (рекомендация для тестовой/малой нагрузки).
• Рекомендуемая оперативная память для продакшн малой команды: 8 ГБ и выше.
• Рекомендуемое место на диске: минимум ~10 ГБ свободно; для репозиториев и CI — значительно больше.
• Минимальный /dev/shm для GitLab: 256 МБ; увеличивайте для высоких нагрузок.

Копия сообщения для социальных сетей (Open Graph)

OG title: GitLab в Docker — развёртывание и эксплуатация OG description: Пошаговое руководство по развёртыванию, настройке, обновлению и бэкапам GitLab в Docker для малых и средних команд.

Часто задаваемые вопросы

Q: Подходит ли Docker для продакшн A: Да, для малых и средних инсталляций при правильной конфигурации и ротации логов. Для больших нагрузок лучше Kubernetes.

Q: Где хранить бэкапы A: Локально в volume и дополнительно в удалённом объектном хранилище (S3 или совместимое).

Q: Как увеличить /dev/shm A: При запуске контейнера укажите –shm-size 256m или больше.

Короткий словарь

• Omnibus: собранный пакет GitLab, включающий все сервисы.
• Gitaly: сервис для работы с Git-репозиториями внутри GitLab.
• SHM (/dev/shm): раздел общей памяти в Linux, используемый для быстрых временных записей.

Резюме

Docker — быстрый способ изолировать и развернуть GitLab. Для успешной эксплуатации: используйте volume для данных, увеличьте /dev/shm, настройте драйвер логов Docker и автоматические бэкапы. Для роста и высокой доступности рассматривайте Kubernetes и Helm.

Важно: протестируйте восстановление бэкапов и обновления в тестовой среде до применения в продакшне.

Краткое объявление для команды (100–200 слов):

Развёртывание GitLab в Docker завершено. Инструкция включает шаги запуска, настройки конфигурации, управления логами, бэкапами и обновлениями. Минимальные требования — 4 ГБ ОЗУ и ~10 ГБ свободного диска; для продакшна рекомендуется выделить больше ресурсов. Для автоматизации используйте docker-compose, для масштабирования — переходите на Kubernetes и Helm. Настройте удалённое хранилище для бэкапов и ротацию логов. Перед любым обновлением выполните ручной бэкап и проверьте процедуру восстановления.