Гид по технологиям

Частный Docker Registry на Ubuntu 18.04 с Nginx и базовой аутентификацией

• 7 min read • DevOps • Обновлено 25 Nov 2025
Приватный Docker Registry на Ubuntu 18.04
Приватный Docker Registry на Ubuntu 18.04

Вид каталога проекта и структура директорий для Registry

Docker Registry — это open source серверное приложение, которое хранит и распространяет Docker-образы. За Docker Hub также стоял Registry как серверная часть. Частный (private) Registry удобен для CI/CD, централизует кастомные образы и ускоряет цикл разработки и доставки.

В этом руководстве показано, как установить и настроить приватный Docker Registry на Ubuntu 18.04 с использованием Nginx и защиты по имени пользователя/паролю (basic auth).

Кому это полезно

  • DevOps и инженерам, которые хотят локальный реестр образов
  • Командам, требующим контроль доступа и собственный SSL
  • Проектам с требованиями offline / private registry

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

  • Сервер с Ubuntu 18.04
  • Права root или sudo
  • Домен, указывающий на сервер (в примерах registry.hakase-labs.io)
  • SSL-сертификат для домена (fullchain.pem и privkey.pem) или возможность использовать собственный CA

Что будем делать

  1. Установим зависимости
  2. Установим Docker и Docker Compose
  3. Настроим приватный Docker Registry (docker-compose, Nginx, SSL, htpasswd)
  4. Протестируем push/pull образов и добавим Root CA в систему

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

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

Выполните:

sudo apt install -y gnupg2 pass apache2-utils httpie

Коротко о пакетах:

  • gnupg2 и pass — можно использовать для безопасного хранения секретов;
  • apache2-utils — содержит htpasswd для генерации файла с паролями;
  • httpie — удобный HTTP-клиент для тестирования API Registry.

Важно: htpasswd сохраняет пароли в формате, который Registry поддерживает (htpasswd / htpasswd-файл).

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

Установим docker и docker-compose из репозиториев Ubuntu:

sudo apt install -y docker.io docker-compose -y

Запустите и добавьте Docker в автозагрузку:

sudo systemctl start docker
sudo systemctl enable docker

Проверьте версии:

docker version
docker-compose version

Вывод версий Docker и Docker Compose

Если команды возвращают версии — Docker и Compose установлены успешно.

Шаг 3 — Настройка приватного Docker Registry

В этом разделе создаём структуру каталогов, конфигурацию docker-compose, виртуальный хост для Nginx, SSL и файл с паролями.

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

Создадим каталог проекта registry и внутренние папки nginx и auth:

mkdir -p registry/{nginx,auth}

Перейдём в каталог и создадим дополнительные папки для конфигов и ssl:

cd registry/
mkdir -p nginx/{conf.d/,ssl}

Команда tree покажет структуру.

Структура директорий проекта для Registry и Nginx

Создание docker-compose.yml

Перейдите в каталог registry и создайте файл docker-compose.yml:

cd registry/
vim docker-compose.yml

Ниже — конфигурация, в которой определены сервисы registry и nginx, сеть mynet и том registrydata. Сервис registry использует образ registry:2 и подключает htpasswd-файл из ./auth/registry.passwd.

Содержимое docker-compose.yml:

version: '3'
services:

#Registry
  registry:
    image: registry:2
    restart: always
    ports:
    - "5000:5000"
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry-Realm
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/registry.passwd
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
    volumes:
      - registrydata:/data
      - ./auth:/auth
    networks:
      - mynet

#Nginx Service
  nginx:
    image: nginx:alpine
    container_name: nginx
    restart: unless-stopped
    tty: true
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d/:/etc/nginx/conf.d/
      - ./nginx/ssl/:/etc/nginx/ssl/
    networks:
      - mynet

#Docker Networks
networks:
  mynet:
    driver: bridge
#Volumes
volumes:
  registrydata:
    driver: local

Сохраните файл.

Примечание: если вы планируете хранить большие образы, проверьте диск, где создаётся том registrydata — по умолчанию это локальный диск хоста.

Конфигурация виртуального хоста Nginx

Создайте файл nginx/conf.d/registry.conf:

cd nginx/conf.d/
vim registry.conf

Вставьте конфигурацию Nginx:

upstream docker-registry {
    server registry:5000;
}

server {
    listen 80;
    server_name registry.hakase-labs.io;
    return 301 https://registry.hakase-labs.io$request_uri;
}

server {
    listen 443 ssl http2;
    server_name registry.hakase-labs.io;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    # Log files for Debug
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;

    location / {
        # Do not allow connections from docker 1.5 and earlier
        # docker pre-1.6.0 did not properly set the user agent on ping, catch "Go *" user agents
        if ($http_user_agent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" )  {
            return 404;
        }

        proxy_pass                          http://docker-registry;
        proxy_set_header  Host              $http_host;
        proxy_set_header  X-Real-IP         $remote_addr;
        proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header  X-Forwarded-Proto $scheme;
        proxy_read_timeout                  900;
    }

}

Сохраните.

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

vim additional.conf

Вставьте:

client_max_body_size 2G;

Сохраните.

SSL-сертификаты и базовая аутентификация

Скопируйте ваши SSL-файлы в каталог nginx/ssl/:

cp /path/to/ssl/fullchain.pem nginx/ssl/
cp /path/to/ssl/privkey.pem nginx/ssl/

Затем создайте файл с паролями для Registry в папке auth:

cd auth/
htpasswd -Bc registry.passwd hakase
TYPE THE STRONG PASSWORD

На этой стадии окружение готово для запуска.

Экран создания паролей htpasswd для Registry

Запуск Docker Registry

Запустите стек в фоне:

docker-compose up -d

Проверка статуса контейнеров:

docker-compose ps
netstat -plntu

Вы увидите сервис registry, слушающий порт 5000 внутри сети mynet, а Nginx — на 80/443 портах хоста.

Запуск контейнеров и вывод docker-compose

Проверка статуса Nginx и Registry

Шаг 4 — Тестирование

Перед тестированием добавьте корневой сертификат в Docker и систему, если вы используете самоподписанный CA.

Если у вас PEM-файл rootCA.pem, сконвертируйте в CRT:

openssl x509 -in rootCA.pem -inform PEM -out rootCA.crt

Скопируйте сертификат в директорию Docker для конкретного хоста:

mkdir -p /etc/docker/certs.d/registry.hakase-labs.io/
cp rootCA.crt /etc/docker/certs.d/registry.hakase-labs.io/

Добавьте сертификат в системное хранилище доверенных корней:

mkdir -p /usr/share/ca-certificates/extra/
cp rootCA.crt /usr/share/ca-certificates/extra/

dpkg-reconfigure ca-certificates
systemctl restart docker

Добавление Root CA и перезапуск Docker

Download / Tag / Push образа

Скачиваем образ:

docker pull ubuntu:16.04

Тегируем его под наш реестр:

docker image tag ubuntu:16.04 registry.hakase-labs.io/ubuntu16

Проверяем локальные образы:

docker images

Список локальных образов перед push

Авторизуемся в реестре (вводим имя пользователя и пароль, которые указали при htpasswd):

docker login https://registry.hakase-labs.io/v2/

Проверяем список репозиториев в Registry через HTTP API (httpie):

http -a hakase https://registry.hakase-labs.io/v2/_catalog

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

Теперь пушим образ в приватный реестр:

docker push registry.hakase-labs.io/ubuntu16

Опять запрашиваем каталог, чтобы убедиться, что ubuntu16 появился:

http -a hakase https://registry.hakase-labs.io/v2/_catalog

Успешный push в Registry

Поздравляем — приватный Docker Registry с Nginx и базовой аутентификацией развернут и протестирован.

Безопасность и жёсткие настройки

Важно повысить безопасность Registry перед использованием в продакшене.

  • Используйте TLS: никогда не запускайте Registry без HTTPS на публичных сетях.
  • Ограничьте доступ на уровне сети (firewall, security groups) — разрешайте доступ только с доверенных IP/сервисов.
  • Храните файл с паролями в отдельном защищённом хранилище (Vault, KMS). Не коммитьте registry.passwd в репозиторий.
  • Добавьте двухфакторную аутентификацию и/или интеграцию с LDAP/AD при возможности (альтернативы: Harbor, Nexus).
  • Включите мониторинг и логирование: собирайте nginx- и registry-логи, настраивайте оповещения при неудачных попытках входа.
  • Регулярно проверяйте свободное место на диске тома registrydata и настраивайте политики очистки (garbage collection) для удаления неиспользуемых слоёв.

Короткая команда для запускa garbage collection (требует остановки push/pull во время выполнения):

docker exec -it  bin/registry garbage-collect /etc/docker/registry/config.yml

Примечание: перед запуском GC сделайте бэкап тома.

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

  • Использовать готовые решения с UI и RBAC: Harbor, JFrog Artifactory, Sonatype Nexus — дают управление репозиториями, пользователей, сканирование уязвимостей.
  • Облачные реестры: Amazon ECR, Google Container Registry/Artifact Registry, Azure Container Registry — интеграция с облачными IAM и управляемой инфраструктурой.
  • Если требуется простой локальный кэш для Docker Hub — использовать pull-through cache у registry.

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

  • У вас требования к аудитам и сложным политикам доступа — лучше готовые продукты (Harbor, Artifactory).
  • Требуется масштабирование на десятки тысяч репозиториев с распределёнными storage-миграциями — задумайтесь о облачных решениях или корпоративных платформах.

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

Администратор (инфраструктура):

  • Настроил firewall и разрешил только нужные порты
  • Разместил SSL-сертификаты и настроил автоматическое обновление (если используется LetsEncrypt)
  • Настроил бэкапы тома registrydata
  • Включил логирование и мониторинг

DevOps-инженер:

  • Подготовил docker-compose и проверил сети/тома
  • Настроил htpasswd или интеграцию с LDAP
  • Произвёл тест push/pull
  • Настроил GC и расписание обслуживания

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

  • Получил доступ и credentials
  • Протестировал docker login/push/pull
  • Добавил инструкции в CI для push в приватный реестр

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

  1. Подготовка: проверка домена, получение SSL и подготовка бэкапов.
  2. Настройка окружения: firewall, мониторинг, пользователи.
  3. Тестовое развёртывание в staging (копия прод окружения).
  4. Миграция и cutover: синхронизировать образы и переключить CI/CD.
  5. После запуска: мониторинг и план обслуживания (GC, обновления).

Устранение неполадок

Проблема: “Не удаётся залогиниться”

  • Проверьте правильность файла auth/registry.passwd и его права.
  • Убедитесь, что Nginx проксирует запросы в сервис registry (docker-compose ps).
  • Просмотрите логи Nginx и Registry: docker-compose logs nginx / docker-compose logs registry.

Проблема: “Docker не доверяет сертификату”

  • Убедитесь, что rootCA.crt скопирован в /etc/docker/certs.d/registry.hakase-labs.io/ и перезапущен docker.
  • Если используется системный CA — добавьте crt в /usr/share/ca-certificates/extra/ и выполните dpkg-reconfigure ca-certificates.

Проблема: “Недостаточно места при push”

  • Проверьте доступное место на диске тома registrydata: df -h
  • Очистите старые образы/логируйте GC.

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

  • Registry доступен по HTTPS и отвечает на /v2/ с кодом 200 для авторизованных пользователей.
  • Push и pull тестовый образов выполняются успешно из CI и локальных машин разработчиков.
  • Процедуры бэкапа и восстановления задокументированы.

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

  • Registry — сервис хранения Docker-образов.
  • HTPasswd — формат файла с хешированными паролями для базовой аутентификации.
  • GC (garbage collection) — сборщик мусора в Registry, очищает неиспользуемые слои.

Пример принятия решений — поток работ

flowchart TD
  A[Подготовка окружения] --> B{SSL готов?}
  B -- Да --> C[Настроить Nginx и скопировать сертификаты]
  B -- Нет --> D[Получить сертификат 'Let's Encrypt или CA']
  C --> E[Создать htpasswd и docker-compose.yml]
  E --> F[Запустить docker-compose up -d]
  F --> G[Провести тесты push/pull]
  G --> H{Тесты прошли?}
  H -- Да --> I[Переход в продакшен]
  H -- Нет --> J[Устранить ошибки]

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

  • Приватный Docker Registry даёт контроль над образами и ускоряет CI/CD.
  • Главные шаги: настройка docker-compose, Nginx с TLS и htpasswd, установка CA в Docker, тестовый push/pull.
  • Для продакшена дополнительно: firewall, мониторинг, бэкапы, GC и, при необходимости, миграция на более функциональные решения.

Ссылки

Список директорий и конфигурационных файлов проекта Registry

Проверка образов и успешный push в приватный реестр

Автор: техническое руководство, адаптация и дополнения для безопасного и управляемого развёртывания приватного Docker Registry.

Поделиться: X/Twitter Facebook LinkedIn Telegram
Автор
Редакция

Похожие материалы

Несколько аккаунтов Skype: Multi Skype Launcher
Программное обеспечение

Несколько аккаунтов Skype: Multi Skype Launcher

Журнал для работы: повысить продуктивность
Productivity

Журнал для работы: повысить продуктивность

Персональные звуки уведомлений на Android
Android.

Персональные звуки уведомлений на Android

Скачивание шоу Hulu для офлайн‑просмотра
Стриминг

Скачивание шоу Hulu для офлайн‑просмотра

Microsoft Start: персонализированная новостная лента
Новости

Microsoft Start: персонализированная новостная лента

Как изменить имя в Epic Games быстро
Гайды

Как изменить имя в Epic Games быстро