Запуск приватного Docker Registry: руководство по развёртыванию и эксплуатации

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

• Running a Registry

• Accessing Your Registry

• Setting up Authentication

• Setting Up SSL

• SSL via LetsEncrypt

• Other Ways to Deploy

Что такое Docker Registry?

Docker Registry — это серверный сервис, который хранит и индексирует Docker-образы. Вы «push» (отправляете) собранные образы в реестр; другие устройства затем «pull» (загружают) эти образы и запускают контейнеры без доступа к исходному Dockerfile.

Крупнейший публичный реестр — Docker Hub; собственный реестр даёт контроль над хранением, политиками доступа и упрощает интеграцию с внутренними CI/CD и политиками безопасности.

Краткие определения:

• Образ (image): упакованный файловый набор и метаданные, используемые для создания контейнера.
• Реестр (registry): сервер, хранящий образы и метаданные о них.

В этом руководстве показано самостоятлеьное (self-hosted) развёртывание. Предположения: на хосте установлены Docker и docker-compose; у вас есть права для запуска сервисов и управления файлами на сервере.

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

• Docker (Engine) и docker-compose установлены и обновлены.
• Достаточно свободного места на диске для хранения образов.
• Базовые знания работы с терминалом и правами sudo.
• Для публичного TLS: A/AAAA DNS-запись, указывающая на сервер реестра.

Важно: реестр при активном использовании быстро растёт по объёму. Планируйте место под логи и бэкапы.

Быстрый запуск реестра (docker-compose)

Registry распространяется как официальный Docker-образ registry:2. Сервер по умолчанию слушает порт 5000 внутри контейнера. На хосте нужно пробросить порт и смонтировать том для постоянного хранения данных.

Создайте рабочую директорию и файл docker-compose.yml. В примере реестр будет доступен на порту 5000, а данные — в папке ./data.

version: "3"
services:
  registry:
    image: registry:2
    ports:
      - "5000:5000"
    environment:
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/data
    restart: unless-stopped
    volumes:
      - ./data:/data

Сохраните файл и запустите контейнер в фоне:

docker-compose up -d

docker-compose скачает образ registry:2 и запустит контейнер с указанной конфигурацией.

Важно: при запуске на боевом сервере рекомендуется сразу настроить аутентификацию и TLS.

Доступ к реестру: теги, push и pull

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

docker tag my-image localhost:5000/my-image
docker push localhost:5000/my-image

На другом хосте используйте сетевой адрес сервера вместо localhost:

docker pull my-registry.example.com:5000/my-image

Если вы не настроили TLS, Docker CLI будет требовать insecure-registry в настройках демона при удалённом доступе — но лучше настроить HTTPS.

Настройка аутентификации (HTTP Basic Auth)

По умолчанию реестр открыт для всех. Для ограничения доступа обычно используют HTTP Basic Auth через htpasswd. Команда htpasswd генерирует файл с паролями.

Установите утилиты, создайте директорию auth и сгенерируйте файл:

sudo apt install apache2-utils
mkdir auth
htpasswd -Bc auth/.htpasswd my-username

Файл будет находиться в auth/.htpasswd и содержать хэш пароля. Обновите docker-compose.yml, чтобы подключить этот файл как том и включить аутентификацию:

version: "3"
services:
  registry:
    image: registry:2
    ports:
      - "5000:5000"
    environment:
      - REGISTRY_AUTH=htpasswd
      - REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm
      - REGISTRY_AUTH_HTPASSWD_PATH=/auth/.htpasswd
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/data
    restart: unless-stopped
    volumes:
      - ./auth:/auth
      - ./data:/data

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

docker-compose up -d --force-recreate

Теперь доступ к реестру потребует docker login:

docker login localhost:5000

Docker сохранит креденшелы в ~/.docker/config.json до команды docker logout или истечения срока действия.

Примечание: Basic Auth удобен и прост, но плохо масштабируется для большого количества пользователей и не предоставляет гибкой RBAC.

Добавление TLS (HTTPS)

Для безопасности и совместимости с клиентами Docker важно включить TLS. Самый простой способ — подключить сертификат и ключ в контейнер и переключить сервис на порт 443.

Обновлённый пример docker-compose.yml с TLS:

version: "3"
services:
  registry:
    image: registry:2
    ports:
      - "443:5000"
    environment:
      - REGISTRY_AUTH=htpasswd
      - REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm
      - REGISTRY_AUTH_HTPASSWD_PATH=/auth/.htpasswd
      - REGISTRY_HTTP_ADDR=0.0.0.0:443
      - REGISTRY_HTTP_TLS_CERTIFICATE=/certs/cert.crt
      - REGISTRY_HTTP_TLS_KEY=/certs/cert.key
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/data
    restart: unless-stopped
    volumes:
      - ./auth:/auth
      - ./certs:/certs
      - ./data:/data

Поместите cert.crt и cert.key в ./certs и перезапустите контейнер. После этого реестр будет принимать HTTPS-запросы на порту 443.

Если сертификат самоподписан, клиентам Docker придётся добавить сертификат в доверенные на машинах, где выполняется docker pull/push.

Автоматический TLS через Let’s Encrypt

Registry поддерживает автоматическое получение сертификатов Let’s Encrypt. Это удобно для публичных инстансов, когда DNS и порт 443 открыты.

Добавьте переменные окружения с контактным email и списком хостов:

version: "3"
services:
  registry:
    image: registry:2
    ports:
      - "443:5000"
    environment:
      - REGISTRY_AUTH=htpasswd
      - REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm
      - REGISTRY_AUTH_HTPASSWD_PATH=/auth/.htpasswd
      - REGISTRY_HTTP_TLS_LETSENCRYPT_EMAIL=example@example.com
      - REGISTRY_HTTP_TLS_LETSENCRYPT_HOSTS=[my-registry.com]
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/data
    restart: unless-stopped
    volumes:
      - ./auth:/auth
      - ./certs:/certs
      - ./data:/data

После пересоздания контейнера реестр попытается получить сертификат от Let’s Encrypt. Учтите, что для успешного получения сертификата:

• Порт 443 должен быть доступен снаружи (файрволл/NAT настроены).
• DNS-запись my-registry.com должна указывать на ваш сервер.

Если автоматическое обновление не подходит, используйте внешние ACME-клиенты (certbot) и монтируйте сертификат в контейнер.

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

Basic Auth удобен для небольших команд, но в корпоративных сценариях требуется делегированная аутентификация и RBAC. Docker Registry поддерживает делегирование аутентификации через токены: сервер делегирует проверку учётных данных внешнему token-сервису.

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

• docker_auth — сервер токенов, поддерживающий LDAP/ OAuth2/ SSO-интеграции.
• Harbor — полноценный реестр с UI, RBAC, политиками сканирования уязвимостей и репликацией.
• Portus — фронтенд и система аутентификации для Registry.
• Nexus/Artifactory — артефакт-репозитории с поддержкой Docker и расширенными возможностями.

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

Резервное копирование, восстановление и управление хранилищем

Файловая система реестра хранит слои и манипуляционные метаданные. Рекомендуем:

• Регулярно бэкапить каталог data (или бекенд-хранилище в S3/облачном хранилище).
• Использовать snapshot-совместимые бэкапы (LVM/ZFS/блоковые снапшоты) для консистентности.
• Периодически чистить неиспользуемые теги и образы (garbage-collect).

Пример команды запуска garbage-collect (требует остановки реестра или запуска в режиме read-only):

docker run --rm -v /path/to/data:/var/lib/registry registry:2 garbage-collect /etc/docker/registry/config.yml

Порядок бэкапа и восстановления:

1. Остановите запись в реестр (переключите на read-only или остановите контейнер).
2. Сделайте консистентный бэкап каталога данных (или снимок тома).
3. Восстановите файлы на целевом хосте, проверьте права и владение.
4. Запустите реестр и проверьте доступность образов.

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

• Образы доступны по pull с авторизацией и без ошибок TLS.
• Система успешно прошла тест push/pull на 3–5 образах разного размера.
• Бэкап и восстановление выполнены и проверены на тестовой среде.

Инцидентный план и откат (runbook)

Если после изменения конфигурации что-то пошло не так:

1. Проверить логи контейнера: docker-compose logs registry или docker logs .
2. Вернуть предыдущую версию docker-compose.yml из системы контроля версий.
3. Пересоздать контейнер: docker-compose up -d –force-recreate.
4. При проблемах с данными — восстановить последний валидный бэкап и проверить целостность образов.

Если TLS перестал работать — проверьте наличие и права на сертификаты, а также корректность DNS и проброса портов.

Безопасность и рекомендации по жёсткой конфигурации

• Всегда включайте TLS для реестров, доступных не только с localhost.
• Используйте делегированную аутентификацию и RBAC для больших команд.
• Храните файлы htpasswd и сертификаты в защищённой файловой системе с ограничением доступа (chmod 600).
• Включите аудит доступов (сбор логов) и интеграцию с SIEM при наличии требований.
• Регулярно применяйте обновления для образа registry и зависимых компонентов.
• Ограничьте входящие соединения на уровне брандмауэра, разрешив только необходимые IP/сети.

Когда этот подход не подойдёт (контрпримеры)

• Вам нужен глобально распределённый реестр с репликацией между регионами — лучше использовать решения с репликацией (Harbor, коммерческие сервисы).
• Нужны продвинутые политики CI/CD и сканирование уязвимостей из коробки — рассмотрите Harbor или Artifactory.
• Поддержка миллионов образов и пиковых нагрузок — стоит рассмотреть облачные реестры (ECR/GCR/ACR) или специализированные кластеры с балансировщиками.

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

• Harbor: UI, сканирование, политика репликации, более удобен для корпоративных сред.
• JFrog Artifactory / Sonatype Nexus: расширенные возможности управления артефактами.
• Облачные реестры: AWS ECR, Google Container Registry (GCR), Azure Container Registry (ACR) — управляемые сервисы с SLA.

Ментальная модель: представьте registry как «файловый сервер» для образов — вам нужен контроль доступа, резервное копирование и SSL, точно как для любого важного файлового репозитория.

Чек-лист по ролям

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

• Настроить Docker и docker-compose.
• Создать структуры томов: ./data, ./auth, ./certs.
• Настроить бэкапы и мониторинг.

DevOps / Инженер CI/CD:

• Интегрировать push/pull в пайплайны.
• Настроить автоматический тестовый pull после сборки.

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

• Использовать корректные теги: my-registry.example.com:5000/project/image:tag.
• Выполнять docker login перед push.

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

• Аудитировать логи.
• Проверять права файлов и доступ к томам.

Мини-методология развёртывания (шаги)

1. Подготовка: установить Docker, подготовить DNS, резервирование диска.
2. Инициализация: создать docker-compose.yml и директории.
3. Аутентификация: создать auth/.htpasswd и подключить.
4. TLS: подключить сертификат или настроить Let’s Encrypt.
5. Тестирование: выполнить docker login/push/pull.
6. Сопровождение: настроить бэкапы, garbage-collect, мониторинг.

Совместимость и миграция

• При миграции данных между инстанциями копируйте каталог storage/data (или соответствующий том в S3). Проверьте соответствие версий registry: старые версии метаданных могут быть несовместимы с новыми функциями.
• Тестируйте миграцию на реплике перед переносом основной нагрузки.

Короткая галерея исключительных случаев

• Если реестр развёрнут за прокси/балансировщиком, убедитесь, что заголовки X-Forwarded-Proto и корректная конфигурация TLS передаются до реестра.
• При использовании IPv6 проверьте, что Docker Engine и firewall поддерживают нужный стек.

1‑строчный глоссарий

• Registry: сервер хранения Docker-образов; Image: собранный контейнерный артефакт; Push/Pull: операции отправки/загрузки образа.

Примерный сценарий тестов / Критерии приёмки

• Успешный docker login с корректными учётными данными.
• Успешный push образа размером ~100 МБ и последующий pull с другого хоста.
• Корректная работа HTTPS (валидный сертификат в браузере/openssl s_client).
• Проверка восстановления: восстановление тестовой ветки из бэкапа и успешный pull восстановленного образа.

Резюме

Собственный Docker Registry — простое и мощное средство для приватного хранения образов. Для базовой работы достаточно docker-compose, htpasswd и TLS; для корпоративных сценариев стоит рассмотреть делегированную аутентификацию и решения уровня Harbor или Artifactory. Не забывайте о бэкапах, garbage-collect и мониторинге.

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