プライベートDockerレジストリを構築する方法｜registryコンテナの運用とDocker Hub rate limit対策

この記事のポイント

・docker run registry:2 で5分以内にプライベートレジストリを起動できる
・push/pullはイメージに「ホスト:ポート/」タグを付けるだけでよい
・TLS + htpasswd認証でセキュアな社内専用レジストリを構築できる
・pull through cache設定でDocker Hub rate limitを実質回避できる

# create working directories for registry
mkdir -p ~/registry/{data,certs,auth}
cd ~/registry

services:
  registry:
    image: registry:2
    container_name: registry
    restart: always
    ports:
      - "5000:5000"
    volumes:
      - ./data:/var/lib/registry
    environment:
      REGISTRY_STORAGE_DELETE_ENABLED: "true"

# start the registry container
docker compose up -d

# confirm it is running
docker compose ps

$ curl -s http://localhost:5000/v2/
{}

# pull from Docker Hub (needed only on first time)
docker pull nginx:latest

# tag the image for our private registry
docker tag nginx:latest localhost:5000/nginx:latest

$ docker push localhost:5000/nginx:latest
The push refers to repository [localhost:5000/nginx]
9e3f92c03290: Pushed
d0e26daf1f58: Pushed
2c7e9b31bd18: Pushed
d2a37b3d0ba5: Pushed
fccbe3c16ded: Pushed
latest: digest: sha256:a4b2c3d4e5f6789012abcdef1234567890abcdef1234567890abcdef12345678 size: 1862

# remove local cache to verify pull from private registry
docker rmi localhost:5000/nginx:latest

$ docker pull localhost:5000/nginx:latest
latest: Pulling from nginx
d2a37b3d0ba5: Pull complete
2c7e9b31bd18: Pull complete
fccbe3c16ded: Pull complete
9e3f92c03290: Pull complete
Digest: sha256:a4b2c3d4e5f6789012abcdef1234567890abcdef1234567890abcdef12345678
Status: Downloaded newer image for localhost:5000/nginx:latest
localhost:5000/nginx:latest

# generate a self-signed certificate valid for 365 days
$ openssl req -newkey rsa:4096 -nodes -sha256     -keyout ~/registry/certs/domain.key     -x509 -days 365     -out ~/registry/certs/domain.crt     -subj "/CN=registry.local"
Generating a RSA private key
...............++++
writing RSA key

# 192.168.x.x  registry.local  （実際のIPに置き換えること）

# register the self-signed cert as trusted CA (RHEL/Rocky Linux)
sudo mkdir -p /etc/docker/certs.d/registry.local:5000
sudo cp ~/registry/certs/domain.crt     /etc/docker/certs.d/registry.local:5000/ca.crt

# Ubuntu: update system trust store
sudo cp ~/registry/certs/domain.crt     /usr/local/share/ca-certificates/registry-local.crt
sudo update-ca-certificates

# install htpasswd tool (RHEL/Rocky Linux)
sudo dnf install -y httpd-tools

# install htpasswd tool (Ubuntu)
sudo apt-get install -y apache2-utils

# create password file with bcrypt hashing (-B is recommended)
$ htpasswd -Bc ~/registry/auth/htpasswd admin
New password:
Re-type new password:
Adding password for user admin

services:
  registry:
    image: registry:2
    container_name: registry
    restart: always
    ports:
      - "5000:5000"
    volumes:
      - ./data:/var/lib/registry
      - ./certs:/certs
      - ./auth:/auth
    environment:
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
      REGISTRY_HTTP_TLS_KEY: /certs/domain.key
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
      REGISTRY_STORAGE_DELETE_ENABLED: "true"

# restart the registry to apply TLS settings
docker compose down && docker compose up -d

# test login to the secure registry
$ docker login registry.local:5000
Username: admin
Password:
WARNING! Your password will be stored unencrypted in /home/user/.docker/config.json.
Login Succeeded

# check remaining pull quota from Docker Hub
TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull"     | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
curl -s --head     -H "Authorization: Bearer ${TOKEN}"     https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest     | grep -i ratelimit

ratelimit-limit: 100;w=21600
ratelimit-remaining: 47;w=21600
docker-ratelimit-source: 203.0.113.xx

services:
  registry-cache:
    image: registry:2
    container_name: registry-cache
    restart: always
    ports:
      - "5001:5000"
    volumes:
      - ./cache-data:/var/lib/registry
    environment:
      REGISTRY_PROXY_REMOTEURL: "https://registry-1.docker.io"
      # optional: add docker hub credentials to increase rate limit
      # REGISTRY_PROXY_USERNAME: "your-dockerhub-username"
      # REGISTRY_PROXY_PASSWORD: "your-dockerhub-token"

{
  "registry-mirrors": ["http://registry.local:5001"]
}

sudo systemctl restart docker

# verify the mirror is registered
$ docker info | grep -A 5 "Registry Mirrors"
 Registry Mirrors:
  http://registry.local:5001/

# check storage usage
$ du -sh ~/registry/data/
4.8G    /home/admin/registry/data/

# list all repositories via API
$ curl -s https://registry.local:5000/v2/_catalog     --cacert ~/registry/certs/domain.crt     -u admin:yourpassword
{"repositories":["nginx","ubuntu","myapp"]}

# dry-run: show what would be deleted without actually deleting
$ docker exec registry bin/registry garbage-collect     --dry-run /etc/docker/registry/config.yml
myapp: marking manifest sha256:1a2b3c4d...
nginx: marking manifest sha256:a4b2c3d4...
3 blobs marked, 15 blobs and 5 manifests eligible for deletion
blob eligible for deletion: sha256:deadbeef...

# stop the registry, run garbage-collect, then restart
docker compose stop
docker exec registry bin/registry garbage-collect     /etc/docker/registry/config.yml
docker compose start

# stop the registry before backup to ensure data consistency
docker compose stop
tar czf /backup/registry-data-$(date +%Y%m%d).tar.gz -C ~/registry data/
docker compose start

# verify the backup file was created
$ ls -lh /backup/registry-data-*.tar.gz
-rw-r--r-- 1 admin admin 4.2G Jul 17 03:00 /backup/registry-data-20260717.tar.gz

Error response from daemon: Get "https://registry.local:5000/v2/":
http: server gave HTTP response to HTTPS client

# /etc/docker/daemon.json に insecure-registries を追加する
{
  "insecure-registries": ["registry.local:5000"]
}

Error response from daemon: Get "https://registry.local:5000/v2/":
x509: certificate signed by unknown authority

Error response from daemon: Head "https://registry.local:5000/v2/nginx/manifests/latest":
no basic auth credentials