Установка GitLab на Debian 12 с Docker

Кратко: пошаговое руководство по установке и запуску GitLab Community Edition в Docker на Debian 12 с настройкой SSH, Docker Compose, томов, резервного копирования и базовой безопасности.
Что даст: полный контроль над репозиториями, возможность интеграций и гибкая локальная эксплуатация.
Важно: используйте FQDN, настройте SMTP для уведомлений, создайте резервные копии и защитите доступ (2FA, отключение публичной регистрации).

Логотип GitLab и серверная установка

Общая идея: GitLab Server — это самоуправляемая версия GitLab, сопоставимая с облачной, но размещаемая на вашем сервере. Преимущество — полный контроль над кодом и конфигурацией. В этом руководстве показано, как установить GitLab Community Edition в контейнер Docker на Debian 12.

Кому подходит это руководство: сисадминам и инженерам DevOps, которые хотят локально развернуть GitLab на собственном сервере или VPS.

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

Важно

Рекомендую пробежать все шаги на тестовом сервере прежде чем переносить в продакшен.
Перед обновлением GitLab всегда делайте резервную копию.

Содержание

Предварительные требования
Установка зависимостей
Изменение системного SSH-порта
Установка Docker и Docker Compose
Настройка Docker томов
Установка GitLab через docker-compose
Первичный вход и начальная конфигурация
Создание первого проекта и работа с SSH
Управление контейнером
Резервное копирование и восстановление
Процедура обновления
Безопасность и конфиденциальность
Чеклисты и runbook’ы
Тесты, критерии приёмки и глоссарий
Заключение

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

Сервер с Debian 12.
Действительный FQDN, например gitlab.example.com, указывающий на сервер.
Доступ под root или эквивалентные sudo-привилегии.
Система обновлена:

apt update && apt upgrade -y

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

Установите базовые пакеты, которые потребуются в процессе установки:

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

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

Шаг 2 — Смена системного SSH-порта

GitLab по умолчанию использует порт SSH 22 внутри контейнера. Лучше сменить системный порт SSH на хосте, чтобы избежать конфликта.

Откройте файл /etc/ssh/sshd_config:

nano /etc/ssh/sshd_config

Найдите строку с портом, раскомментируйте и измените значение. В примере установим 2222:

#Port 22

замените на

Port 2222

Сохраните файл, перезапустите сервис SSH и переподключитесь на новый порт:

systemctl restart sshd
ssh username@ -p 2222

Примечание: убедитесь, что ваш брандмауэр и провайдер не блокируют выбранный порт.

Шаг 3 — Установка Docker и Docker Compose

Добавьте GPG-ключ Docker:

curl -fsSL https://download.docker.com/linux/debian/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/debian \
  $(lsb_release -cs) stable' | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

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

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

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

usermod -aG docker ${USER}

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

su - $(USER)

Примечание: в текущем руководстве используется плагин docker compose v2, команды — ‘docker compose’, а не ‘docker-compose’.

Шаг 4 — Настройка Docker томов

Создайте каталог для хранения данных GitLab и файлы окружения:

mkdir -p /opt/gitlab/vol
cd /opt/gitlab
nano .env

Вставьте в .env:

GITLAB_HOME=/opt/gitlab/vol

Том монтируется в контейнер для обеспечения персистентности. Таблица соответствий директорий:

Local Location	Container Location	Usage
$GITLAB_HOME/data	/var/opt/gitlab	данные приложения
$GITLAB_HOME/logs	/var/log/gitlab	логи
$GITLAB_HOME/config	/etc/gitlab	конфигурация

Шаг 5 — Установка GitLab через Docker Compose

Создайте docker-compose.yml в /opt/gitlab:

nano docker-compose.yml

Вставьте конфигурацию (в этом примере используется GitLab EE-образ; для Community Edition замените образ на gitlab/gitlab-ce:latest):

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: Docker-образ GitLab. Для CE замените на ‘gitlab/gitlab-ce:latest’.
container_name: читаемое имя контейнера.
restart: политика перезапуска, ‘always’ — контейнер перезапустится автоматически.
hostname и external_url: указывают домен, по которому будет доступен GitLab; https запускает автоматическую установку Let’s Encrypt.
SMTP: настройте почтовый сервер для уведомлений.
ports: проброс портов хоста на контейнер (включают 22, 80, 443, 587). Если порт 22 занят на хосте, пробросьте, например, ‘3333:22’ и добавьте ‘gitlab_rails[‘gitlab_shell_ssh_port’] = 3333’ в GITLAB_OMNIBUS_CONFIG.
volumes: точки монтирования для персистентности.
shm_size: увеличение shared memory до минимум 256m рекомендуется для Prometheus-метрик.

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

docker compose up -d

Мониторинг логов:

docker logs gitlab-howtoforge -f

Посмотреть запущенные контейнеры:

docker ps

GitLab сгенерирует начальный root-пароль и сохранит его в файле initial_root_password в каталоге конфигурации. Просмотреть пароль:

cat /opt/gitlab/vol/config/initial_root_password

Скопируйте пароль и сохраните в безопасном месте — файл может быть удалён после первого запуска reconfigure.

Шаг 6 — Конфигурация GitLab и первичный доступ

Доступ к интерфейсу

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

Вход: логин root и пароль из файла initial_root_password.

Экран входа GitLab

После входа вы попадёте в панель управления GitLab.

Панель управления GitLab

Ограничение публичной регистрации

Чтобы запретить случайную регистрацию пользователей:

Нажмите Turn off в появившемся попапе или зайдите в Админ-панель → Settings → General → Sign-up restrictions.
Снимите галочку Sign-up enabled.
Сохраните изменения.

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

Редактирование профиля и смена пароля

Отредактируйте профиль: иконка пользователя → Edit profile.

Редактирование профиля

Обязательно смените root-пароль: Account → Password.

Смена пароля

Рекомендуется включить двухфакторную аутентификацию (2FA).

Отключение Prometheus и сборников данных

Если вы не используете встроенные метрики Prometheus, можно отключить их для экономии ресурсов:

Admin Panel → Settings → Metrics and profiling → Metrics - Prometheus → отключите Enable health and performance metrics endpoint → Save changes.

Вы также можете отключить Service Ping в разделе Usage statistics, если хотите минимизировать сбор телеметрии.

Отключить метрики

Шаг 7 — Создание первого проекта и настройка SSH

Создание 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) — убедитесь, что служба OpenSSH Authentication Agent запущена, затем добавьте ключ с указанием пути к файлу.

Создайте или обновите ~/.ssh/config, чтобы автоматизировать подключение:

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

Скопируйте публичный ключ:

cat ~/.ssh/id_ed25519.pub

Вставьте ключ в GitLab: профиль → SSH Keys → Add Key.

SSH Keys

Проверка соединения SSH:

ssh -T [email protected]

Подтвердите добавление ключа в known_hosts и ожидайте сообщения приветствия.

Создание проекта и коммит из командной строки

Создайте новый проект: New project → Create blank project. Инициализируйте README при создании при желании.

Создать проект

Клонирование по 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

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

Проект после коммита

Шаг 8 — Управление контейнером

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

docker compose down

Запуск:

docker compose up -d

Применение изменений в compose-файле (убирает “осиротевшие” контейнеры):

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

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

docker compose restart

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

docker exec -it  bash

Шаг 9 — Резервное копирование GitLab

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

docker exec -t gitlab-howtoforge gitlab-backup create

По умолчанию бэкап сохраняется в /srv/gitlab/data/backups. Замечание: gitlab-secrets.json и docker-compose.yml не входят в tar-архив, их нужно копировать отдельно (они важны для восстановления и конфигурации).

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

Пример простой cron-записи (ежедневно в 2:30):

30 2 * * * docker exec -t gitlab-howtoforge gitlab-backup create && rsync -av /opt/gitlab/vol/data/backups/ remote-backup:/backups/gitlab

Шаг 10 — Восстановление GitLab

Подготовьте целевой сервер с установленным Docker и такой же структурой каталогов томов. Скопируйте бэкап в /srv/gitlab/data/backups и gitlab-secrets.json в /srv/gitlab/config.

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

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

Проверьте, что процессы остановлены:

docker exec -it  gitlab-ctl status

Запустите восстановление (уберите суффикс _gitlab_backup.tar из имени архива):

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

Перезапустите контейнеры, чтобы применить конфигурацию compose-файла:

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

Проверка состояния GitLab:

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

Шаг 11 — Обновление GitLab

Перед обновлением выполните резервное копирование.

Остановите и удалите текущие контейнеры (данные сохранятся в томах):

docker compose down --remove-orphans

Обновите образ и запустите снова:

docker compose pull
docker compose up -d

Для перехода между minor-версиями этот сценарий обычно работает. Для мажорных обновлений смотрите официальную документацию GitLab — иногда требуются промежуточные версии и дополнительные шаги.

Безопасность и повышение приватности

Рекомендации по безопасности:

Всегда используйте HTTPS и валидный сертификат (Let’s Encrypt или ваш CA).
Включите двухфакторную аутентификацию для администраторов.
Отключите публичную регистрацию, если GitLab не предназначен для публичного использования.
Отключите Service Ping и ненужные метрики для приватности.
Храните gitlab-secrets.json в зашифрованном хранилище и делайте его бэкап отдельно.
Обновляйте систему и Docker до актуальных патчей.
Ограничьте доступ к SSH по IP, если это допустимо вашей политикой безопасности.

Замечание по SSL: если вы используете внешний обратный прокси (nginx, Traefik), перенесите TLS-терминацию на него и настройте проброс в контейнер GitLab по HTTP внутренне.

Чеклисты и операционные playbook’ы

Чеклист администратора на этапе деплоя

Сервер с Debian 12 обновлён
FQDN указывает на сервер
Docker и docker compose установлены
Том для GitLab создан и права проверены
SMTP настроен и протестирован
SSL установлен и работает
Публичная регистрация отключена при необходимости
2FA включена для админов
Резервное копирование настроено

Dev checklist перед выкладкой в продакшен

Проверено клонирование репозиториев по SSH и HTTPS
CI/CD runners настроены и проверены
Тесты CI проходят локально
Параметры видимости проектов задокументированы

Резервное копирование — краткий runbook

Выполнить команду создания бэкапа.
Скопировать gitlab-secrets.json и docker-compose.yml в безопасное хранилище.
Перенести архивы на offsite-хранилище.
Проверить целостность архива (tar -tf).

Восстановление — краткий runbook

Развернуть чистую установку GitLab с тем же образом/версией.
Скопировать gitlab-secrets.json и архив бэкапа в соответствующие директории.
Остановить puma и sidekiq.
Запустить gitlab-backup restore.
Перезапустить контейнеры и выполнить gitlab:check.

SOP обновления (основные шаги)

Сделать полный бэкап и проверить его наличие offsite.
Проверить журнал изменений GitLab на предмет специальных инструкций по миграции.
Переключить пользователей в режим обслуживания при необходимости.
Протестировать обновление на staging-копии.
Выполнить обновление на проде и проверить логи.

Мини-методология: деплой GitLab в 6 шагах

Подготовка хоста и сети.
Установка Docker и Compose.
Настройка томов и .env.
Запуск docker compose и первичная конфигурация.
Настройка SMTP, SSL и безопасности.
Резервное копирование и проверка восстановления.

Decision tree — когда использовать Docker и когда нет

flowchart TD
  A[Нужен GitLab] --> B{Требуется полный контроль над хостом?}
  B -- Да --> C[Самохостинг 'Docker на Debian']
  B -- Нет --> D[Использовать GitLab.com или SaaS]
  C --> E{Есть ли требования к высокой доступности?}
  E -- Да --> F[Рассмотреть k8s и Helm-чарты]
  E -- Нет --> G[Docker Compose подходит]

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

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

GitLab доступен по HTTPS на заданном FQDN.
Вход в систему выполнен под root с новым паролем.
SSH-подключение к репозиторию работает (git clone, git push).
SMTP-уведомления отправляются корректно (письмо восстановления пароля).
Созданные резервные копии можно восстановить на тестовом сервере.

Тестовые сценарии

Переход по URL https://gitlab.example.com, валидный сертификат, отсутствие предупреждений браузера.
Вход как root, смена пароля и повторная успешная авторизация.
Добавление SSH-ключа и успешный git push.
Создание резервной копии и восстановление на тестовом стенде.

Короткий глоссарий (1 линия)

FQDN: полное доменное имя сервера.
CE: Community Edition — бесплатная редакция GitLab.
EE: Enterprise Edition — платная расширенная редакция.
Omnibus: набор конфигураций для запуска GitLab.

Совместимость, миграция и тонкости локализации

Для миграции с предыдущих версий GitLab проверяйте последовательность версий — иногда требуется промежуточное обновление.
При использовании внешнего хранилища артефактов и LFS настройте доступ и права на файловую систему.
В локальном окружении учитывайте часовой пояс сервера для корректности временных меток и CI-планировщиков.

Проблемы и варианты, когда этот подход не подходит

Когда NOT использовать Docker Compose на одном хосте:

Если нужна высокая доступность и отказоустойчивость — лучше использовать Kubernetes и распределённую инфраструктуру.
Для больших инсталляций с сотнями разработчиков и высокими требованиями к масштабированию — рекомендуется масштабируемая архитектура с отдельными базами данных и хранилищами.

Альтернативы

GitLab SaaS (gitlab.com) — если не нужен полный контроль над инстансом.
GitLab на Kubernetes с Helm — для production-кластеров с высокой нагрузкой.
Другие решения: Gitea, GitHub Enterprise — в зависимости от бизнес-требований.

Юридические и privacy заметки (GDPR)

Самохостинг повышает контроль над персональными данными, но ответственность за их защиту лежит на вас.
Если вы храните персональные данные пользователей (email, IP, логи), убедитесь, что политика хранения и возможность удаления данных соответствует требованиям GDPR или вашим локальным законам.
Отключение Service Ping и сборников статистики снижает объём телеметрии, отправляемой в GitLab.

Социальный превью и короткое объявление

Рекомендуемое OG-заголовок: Быстрая установка GitLab на Debian 12 OG-описание: Разверните GitLab CE в Docker на Debian 12: установка, настройка SSH и SMTP, резервные копии и рекомендации по безопасности.

Короткое объявление (120–160 слов)

Устанавливаем GitLab Community Edition в Docker на Debian 12: полное руководство от подготовки сервера до первого проекта. Вы научитесь настраивать Docker и Docker Compose, монтировать персистентные тома, запускать GitLab с HTTPS и SMTP, добавлять SSH-ключи и создавать проекты. Включены инструкции по резервному копированию, восстановлению и обновлению, а также чеклисты безопасности и операционные runbook’ы. Подходит для тестовых и production-сред с учётом масштабирования и GDPR-рекомендаций.

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

GitLab можно успешно развернуть в Docker на Debian 12 за счёт docker compose и монтируемых томов.
Обязательно настройте SMTP, SSL и резервное копирование.
Для продакшен-инсталляций продумайте HA-архитектуру и процедуру обновлений.

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

Установка GitLab Server на Debian 12 с Docker