Как запустить приватный Docker Registry

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

• Запуск реестра
• Доступ к реестру
• Настройка аутентификации
• Настройка SSL
• SSL через Let’s Encrypt
• Другие способы развертывания
• Проверка и приёмка
• Контроль безопасности и эксплуатация

Введение

Запуск собственного Docker Registry даёт приватное хранилище для образов Docker. Это полезно в корпоративной среде, при необходимости строгого контроля доступа или чтобы сократить зависимость от публичных регистров типа Docker Hub.

Определение: Docker Registry — серверная система для хранения и индексирования Docker-образов. Вы отправляете (push) в реестр готовые образы, а другие пользователи получают их (pull) без доступа к исходным Dockerfile.

Кому это подходит: небольшим командам, локальным инсталляциям CI/CD, офлайн-средам и организациям, где важен контроль размещения образов.

Предварительные требования: Docker и docker-compose на машине, где будет размещён реестр. Достаточно дискового пространства для хранения образов.

Запуск реестра

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

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

Пример минимального docker-compose для локального теста (реестр доступен на порту 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.yml и запустите:

docker-compose up -d

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

Советы по размещению данных

• Разделите данные и конфигурацию: ./data для слоёв, ./auth для файлов аутентификации, ./certs для сертификатов.
• Планируйте рост: образ может быстро занимать гигабайты при активном использовании.
• Для production рассмотрите удалённые backend’ы (S3, GCS или похожие), чтобы не зависеть от локального диска.

Доступ к реестру

Чтобы отправить образ в реестр, нужно его правильно пометить (tag) с адресом реестра, затем выполнить docker push.

На машине, где запущен реестр, можно использовать localhost:

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

После push вы увидите слои образа в папке ./data. Чтобы получить образ с другого хоста, замените localhost на IP или DNS-имя сервера:

docker pull 10.0.1.5:5000/my-image

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

Настройка аутентификации

Без аутентификации реестр открыт. Базовый способ — HTTP Basic Auth с htpasswd.

Создание htpasswd (пример для Debian/Ubuntu):

sudo apt update && sudo apt install -y apache2-utils
mkdir -p 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 CLI будет требовать логин:

docker login localhost:5000

Введите пользователя и пароль из htpasswd. Docker кэширует учётные данные на клиенте; чтобы удалить их, выполните docker logout.

Важно: htpasswd подходит для небольших команд. Для крупных организаций используйте токен-авторизацию или интеграцию с внешними провайдерами.

Настройка SSL

TLS необходим за исключением локальной работы на localhost. Реестр поддерживает TLS-конфигурацию через переменные окружения, если вы монтируете сертификаты в контейнер.

Пример конфигурации для прослушивания HTTPS на 443 и использования локальных сертификатов:

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

Добавьте в ./certs файлы cert.crt и cert.key. Перезапустите контейнер. Клиенты должны подключаться по HTTPS и доверять сертификату. Для публичного домена используйте сертификат, выданный CA.

Совет: вместо проброса 443:5000 можно настроить обратный прокси (Nginx, Traefik) и держать реестр на внутреннем порту. Это упрощает управление сертификатами и логированием.

SSL через LetsEncrypt

У реестра есть поддержка автоматического получения сертификатов через Let’s Encrypt. Для этого реестр должен быть публично доступен по домену и порту 443.

Установите переменные окружения для электронной почты и списка доменов:

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=you@example.com
      - REGISTRY_HTTP_TLS_LETSENCRYPT_HOSTS=[my-registry.example.com]
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/data
    restart: unless-stopped
    volumes:
      - ./auth:/auth
      - ./certs:/certs
      - ./data:/data

Примените изменения и дождитесь создания сертификата. Let’s Encrypt выполнит проверку владения доменом и выпустит сертификат. Подождите несколько минут — процесс может занять время.

Важно: убедитесь, что DNS указывает на сервер, а порты 80 и 443 открыты для Let’s Encrypt.

Другие способы развертывания

Docker-compose + htpasswd + Let’s Encrypt — самый простой путь. Но существуют более масштабируемые и удобные варианты:

• Токен-авторизация: сервер делегирует проверку внешнему токен-серверу. Подходит для интеграции с корпоративными IAM/SSO.
• Внешние проекты: docker_auth — пример сервисов, которые реализуют токен-авторизацию и дополнительные политики доступа.
• GUI-решения: Portus (SUSE) предоставляет веб-интерфейс и собственную модель аутентификации.
• Управляемые сервисы: облачные registries (AWS ECR, Google Artifact Registry) предоставляют платформенные возможности, но отличаются по модели биллинга и интеграции.

Когда базовый подход терпит неудачу:

• Если нужна групповая, ролевая авторизация и аудит — базовый htpasswd недостаточен.
• Если количество пользователей велико — переходите на централизованную авторизацию с токенами.
• Если нужна высокая доступность и репликация — используйте S3/облачные backend’ы и балансировщики нагрузки.

Проверка и приёмка

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

• Реестр отвечает на HTTPS-запросы на ожидаемом домене.
• Аутентификация требует логин/пароль и блокирует неавторизованные запросы.
• Можно push/pull тестового образа с нескольких клиентов.
• Образы корректно сохраняются в каталоге ./data или в стороннем бэкенде.
• Логи контейнера логично отражают операции push/pull и ошибки.

Простой тестовый сценарий:

1. docker login my-registry:443 — успешный вход.
2. docker tag busybox my-registry:443/test/busybox:latest
3. docker push my-registry:443/test/busybox:latest
4. docker pull my-registry:443/test/busybox:latest
5. Посмотреть ./data на наличие слоёв.

Критерии приёмки: все шаги выполняются без ошибок, и разрешения соответствуют ожиданиям.

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

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

• Всегда включайте TLS для публичного доступа.
• Храните htpasswd и приватные ключи вне общих репозиториев.
• Ограничьте доступ на сетевом уровне (firewall, security groups).
• Внедрите сканирование уязвимостей образов (Trivy, Clair) перед push.
• Настройте бэкапы каталога данных и метаданных реестра.
• Введите политику хранения (retention) для удаления старых образов и экономии места.
• Внимательно тестируйте обновления registry: сначала на staging.

Пример hardening-checklist (роль: DevOps):

• TLS включён и сертификаты обновляются.
• htpasswd или внешняя auth-система настроены.
• Логи централизованы (syslog / ELK / Loki).
• Мониторинг: свободное место, число запросов, ошибки.
• Периодические бэкапы данных и проверка восстановления.
• Политики очистки и квоты на пространство.

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

Простая стратегия бэкапа:

1. Останавливайте контейнер реестра.
2. Копируйте ./data и ./auth в защищённое хранилище (scp, rsync, S3).
3. Для восстановления распакуйте данные в соответствующие папки и запустите контейнер.

Важно: если используете S3 или другой удалённый backend, бэкап метаданных может потребоваться отдельно.

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

• Варианты хранилищ: filesystem (локально), S3-совместимое хранилище, GCS. При переходе на S3 обновите конфигурацию storage и перенесите данные.
• Версии: меняйте версию registry осторожно. Всегда читайте release notes при обновлении.
• Порты: если меняете порт (например, с 5000 на 443), обновите CI/CD и скрипты, которые обращаются к реестру.

Шаблон для production с обратным прокси (пример)

Ниже — упрощённый пример с Nginx в роли обратного прокси, который держит TLS, а реестр остаётся на внутреннем порту 5000.

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

  nginx:
    image: nginx:stable
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - registry
    restart: unless-stopped

Nginx конфиг проксирует запросы на внутренний контейнер registry:5000 и управляет TLS.

Сценарии отказов и откат

Типовые проблемы и действия:

• Сертификат просрочен: откат на старый cert, перезапуск nginx/registry, план автоматического обновления.
• Утечка учётных данных: сбросить пароли, пересоздать htpasswd, уведомить команду, проверка логов.
• Переполнение диска: временно приостановить новые push, очистить старые теги по политике, расширить хранилище.

Что ещё учитывать для локального российского деплоймента

• DNS и публичные домены: если вы планируете выдачу сертификатов Let’s Encrypt, домен должен быть доступен извне.
• Локальные альтернативы хранилищ: можно использовать S3-совместимые российские решения при необходимости локализации данных.

Что делать, если нужна расширенная авторизация

• Внедрите отдельный token-issuer и настройте registry на делегирование авторизации.
• Или используйте готовые проекты (docker_auth) для поддержки ролей и политик доступа.
• Для корпоративной интеграции рассмотрите SSO через OIDC/LDAP на уровне прокси или внешнего сервиса.

Мини-методология: как внедрять реестр по шагам

1. Разверните тестовый реестр на staging с htpasswd и локальным хранилищем.
2. Проведите базовые push/pull тесты с CI.
3. Добавьте TLS (Let’s Encrypt или CA) и проверяйте клиенты.
4. Настройте мониторинг и бэкапы.
5. Перенесите в production, подготовив rollback-план.

Decision flow (Mermaid)

flowchart TD
  A[Нужен приватный реестр?] -->|да| B{Публичный доступ нужен?}
  B -->|нет| C[docker-compose, локальный FS, htpasswd]
  B -->|да| D{Нужна автоматизация сертификатов?}
  D -->|да| E[Let's Encrypt или reverse proxy с ACME]
  D -->|нет| F[Сертификат от CA, прокси]
  A -->|нет| G[Использовать Docker Hub или облачный регистр]

Частые вопросы

Q: Можно ли использовать registry без Docker Compose?
A: Да. Вы можете запускать контейнер registry напрямую через docker run или в Kubernetes как Deployment.

Q: Что лучше для масштабирования — локальное хранилище или S3?
A: Для масштабирования и высокой доступности предпочтительнее S3-совместимый backend.

Q: Как интегрировать сканирование уязвимостей?
A: Используйте инструменты типа Trivy или Clair в вашей CI, чтобы сканировать образы до push.

Итог

Важно: приватный Docker Registry — гибкое решение. Для простых сценариев хватит docker-compose + htpasswd + TLS. Для корпоративной эксплуатации планируйте внешнюю авторизацию, мониторинг, бэкапы и стратегию хранения.

Короткое резюме ниже.

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

• Быстрый старт: docker-compose + ./data для хранения.
• Безопасность: включите TLS и аутентификацию.
• Масштабирование: рассмотрите S3-бэкенд и токен-авторизацию.