This article covers How to Set Up a Private in detail. Docker Hub is convenient, but public registries come with rate limits, and some images should simply never leave your own network. A private docker registry gives you unlimited pushes, full control over retention, and fast pulls on your LAN or VPC. In this guide you will run the official registry image on Ubuntu with persistent storage, htpasswd authentication and a discussion of TLS — then push and pull your first image. You need a working Docker host first; our Ubuntu 24.04 installation guide covers that.
Prerequisites – How to Set Up a Private
- Ubuntu 22.04/24.04 server with Docker Engine installed
- A hostname pointing to the server, e.g.
registry.example.com(a LAN DNS name works too) - Disk space for the images you plan to store — they add up quickly

Step 1: Prepare Storage and Credentials – How to Set Up a Private
mkdir -p /srv/registry/{data,auth}
cd /srv/registry
Generate a password file for basic authentication using the official httpd tools image (no host packages needed):
docker run --rm \
--entrypoint htpasswd \
httpd:2 -Bbn admin 'YourStrongPassword' > auth/htpasswd
chmod 600 auth/htpasswd
The -B flag selects bcrypt hashing. Keep this file readable only by root — anyone who obtains it plus network access can try to crack it offline.
Step 2: Run the Private Docker Registry
docker run -d \
--name registry \
--restart always \
-p 5000:5000 \
-v /srv/registry/data:/var/lib/registry \
-v /srv/registry/auth:/auth \
-e REGISTRY_AUTH=htpasswd \
-e REGISTRY_AUTH_HTPASSWD_REALM="Private Registry" \
-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
registry:2
The registry stores every pushed layer under /srv/registry/data on the host, thanks to the bind mount — that directory is what you back up. Check it is healthy:
curl -u admin:YourStrongPassword https://localhost:5000/v2/
# -> {} means the API is up
(Over plain HTTP from localhost, use http:// for this first smoke test only.)
Step 3: Solve TLS — the Step Everyone Skips
Docker refuses to push to a registry over plain HTTP unless it is explicitly marked insecure. You have two proper options:
Option A — real TLS (recommended). Put the registry behind a reverse proxy with a Let’s Encrypt certificate, or supply certificates directly with REGISTRY_HTTP_TLS_CERTIFICATE and REGISTRY_HTTP_TLS_KEY. Our walkthrough on securing Nginx with Let’s Encrypt shows how to obtain the certificate; point the proxy at port 5000.
Option B — insecure registry (lab/LAN only). On every Docker client, add to /etc/docker/daemon.json:
{ "insecure-registries": ["registry.example.com:5000"] }
Then restart Docker. Understand the trade-off: credentials and image contents cross the network unencrypted. Acceptable on an isolated lab network, unacceptable on anything else.
Step 4: Push and Pull Your First Image
The workflow mirrors Docker Hub — the only difference is the registry hostname prefix, which is how Docker knows where to send the image. Compare with our walkthrough on how to push a Docker image to Docker Hub:
# Log in
docker login registry.example.com:5000
# Tag an existing image for the private registry
docker tag myapp:1.0.0 registry.example.com:5000/myapp:1.0.0
# Push it
docker push registry.example.com:5000/myapp:1.0.0
# On another machine: login, then pull
docker pull registry.example.com:5000/myapp:1.0.0
# List repositories through the API
curl -u admin:YourStrongPassword https://registry.example.com:5000/v2/_catalog
Optional: Run It with Docker Compose
On a server you manage long-term, a compose file documents the registry’s configuration far better than a long docker run command buried in your shell history. Save the same settings as a docker-compose.yml, keep the file next to the data and auth directories under /srv/registry, and upgrades become two commands: docker compose pull followed by docker compose up -d. Version-controlling that compose file (without the htpasswd file itself) means your registry can be rebuilt on a new host in minutes, with only the data directory to restore from backup.
Step 5: Housekeeping — Garbage Collection
Deleting tags through the API (enabled with REGISTRY_STORAGE_DELETE_ENABLED=true) only removes references; the underlying layers stay on disk until garbage collection runs:
docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml
Run it during quiet periods — while GC runs, pushes should be paused for consistency. Also back up /srv/registry/data like any other important data directory, and monitor its growth: registries collect forgotten experiment images exactly the way Docker hosts do.
Troubleshooting
“server gave HTTP response to HTTPS client”. The client expects TLS but the registry serves plain HTTP, or vice versa. Align the setup — proper certificate, or the insecure-registries entry on every client.
unauthorized / authentication required. Wrong credentials, or the htpasswd file path/realm does not match the environment variables. Check docker logs registry.
Push fails partway with a 413 or timeout. A reverse proxy in front is limiting request size — raise client_max_body_size in Nginx (registry layers are large).
x509: certificate signed by unknown authority. Your CA is not trusted by the Docker daemon. Install the CA certificate into the host trust store and restart Docker, rather than disabling verification.
Conclusion
A private registry is one container, one data directory and one password file away. Add TLS, run garbage collection on a schedule, and back up the storage folder — you now own your image supply chain with no rate limits. For configuration options far beyond this guide, consult the official Distribution registry documentation.