How to Deploy and Use a Personal Docker Registry with Distribution

Why a Private Registry?

Developing and delivering projects often requires a consistent runtime environment, but local setups can be unpredictable and differ across operating systems. Using Docker images simplifies deployment, yet pulling images from public registries can fail, prompting the need for a self‑hosted registry.

1. Local Deployment (Learning Purpose)

A basic setup runs the registry container on localhost only, useful for familiarizing yourself with Distribution. This method has limited practical value because it cannot be accessed remotely.

2. Deleting the Local Repository

Because the container is configured to start automatically, removing it requires chaining stop and remove commands, e.g., docker stop myregistry && docker rm myregistry.

3. Persistent Storage

To retain images after the container is removed, mount a host directory into the container as a volume, ensuring the registry’s data persists on the host filesystem.

4. Enabling External Access

External access requires three conditions:

Set a custom registry URL such as https://myregistry.distribution.com/ (adjust to your own domain).

Ensure DNS, router, and firewall allow inbound traffic to the host’s port 443.

Provide a certificate authorized by a Certificate Authority (CA) or a self‑signed one.

5. Configuring the Registry Domain

Since the registry is intended for internal use, map the chosen domain to the host’s IP by editing each machine’s /etc/hosts file, adding a line like:

192.168.1.10  myregistry.distribution.com

6. Setting Up a Self‑Signed Certificate

Because the registry uses HTTPS, generate a self‑signed certificate with OpenSSL (version ≥ 1.1.1 to support -addext). The certificate and key are then placed in the container’s /certs directory and referenced via the registry’s TLS options.

7. Installing the Root Certificate

Copy the generated CA certificate into Docker’s trusted certificates directory (e.g., /etc/docker/certs.d/myregistry.distribution.com/ca.crt) and restart Docker so the client trusts the registry.

8. Starting the Registry

After completing the above configuration, launch the registry with a command such as:

docker run -d \
  --name myregistry \
  -p 443:5000 \
  -v /my/registry/data:/var/lib/registry \
  -v /my/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/server.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/server.key \
  registry:2

The server becomes reachable by any machine on the same subnet using the configured domain.

9. Optional UI Layer

The registry itself lacks a graphical interface for browsing stored images. To add a UI, deploy a docker‑registry‑ui container that connects to the registry endpoint.