Skip to main content

2025-02-11

Quote

“Cherish the time, never forget your original aspiration.” — Jane · Nice Nan

Deploying a Docker Registry​

To provide a pull-through cache for servers that cannot access Docker Hub, you can deploy an instance of the official Docker Registry on a machine with Docker Hub access.

1. Create the Registry Configuration File​

Create a file at /path/to/config.yaml with the following content:

version: 0.1
proxy:
  remoteurl: https://registry-1.docker.io
  • version: 0.1 Specifies the configuration schema version.
  • proxy.remoteurl Points to the Docker Hub endpoint (https://registry-1.docker.io by default).

This configuration tells your Registry that, whenever a requested image is not found locally, it should fetch and cache it from Docker Hub.

2. Configure Nginx as a Reverse Proxy​

Create an nginx configuration file at /path/to/registry.conf:

server {
    listen 443 ssl;
    server_name domain.name;

    ssl_certificate     /etc/nginx/cert/domain.name.crt;
    ssl_certificate_key /etc/nginx/cert/domain.name.key;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $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;
    }
}
  • listen 443 ssl; Listens for HTTPS traffic on port 443.
  • server_name Your registry’s domain name.
  • ssl_certificate / ssl_certificate_key Paths to your TLS certificate and private key.
  • location / Proxies all incoming requests to the registry running on localhost:5000, forwarding common headers.

3. Run the Registry Container​

With Docker installed, launch the registry container, mounting your configuration:

docker run -d \
  --name registry \
  -p 5000:5000 \
  -v /path/to/config.yaml:/etc/docker/registry/config.yml \
  registry:2
  • -p 5000:5000 Exposes the registry on port 5000.
  • -v /path/to/config.yaml Binds your custom configuration into the container.
  • registry:2 Uses the official Registry image (version 2).

4. Verify and Use the Pull-Through Cache​

  1. Test Pulling an Image

    docker pull domain.name/myimage:tag

    The first pull fetches from Docker Hub, caching it locally.

  2. Subsequent Pulls Subsequent pulls for the same image/tag will be served from your local cache, reducing Docker Hub traffic.

  3. Cleanup (Optional) You can configure garbage collection in the registry to reclaim space from untagged or expired blobs. See the Docker Registry Garbage Collection documentation for details.

By deploying a pull-through registry behind an HTTPS reverse proxy, you enable isolated environments to mirror and cache Docker Hub images securely and efficiently.