Private Docker Registry Setup – Step-by-Step Guide with Examples & FAQs

Introduction – Why Set Up a Private Docker Registry?

As Docker adoption grows in modern DevOps workflows, the need to store and manage container images securely becomes critical. While Docker Hub is a great public registry, many teams and organizations need private registries to:

• Protect proprietary code
• Ensure network isolation
• Avoid rate limits from public services
• Maintain full control over deployment infrastructure

In this guide, you’ll learn:

• What a private Docker registry is
• How to set up and secure your own registry
• How to push and pull images from it
• Best practices for production environments

What is a Private Docker Registry?

A private Docker registry is a self-hosted solution for storing and distributing Docker images, similar to Docker Hub — but under your control. You can host it on-premise or in the cloud.

Benefits:

• Keep container images private and secure
• Avoid Docker Hub’s rate limits and service disruptions
• Optimize build and deployment speed in local environments
• Customize access control, storage location, and policies

Prerequisites

Before setting up your registry, ensure you have:

• Docker installed (Linux, Windows, or macOS)
• Basic Docker command-line experience
• Optional: Domain and SSL for production security

Step-by-Step: Setting Up a Private Docker Registry

Step 1: Pull the Docker Registry Image

docker pull registry:2

This pulls the latest version (v2) of the official Docker Registry image.

Step 2: Run the Registry Container

docker run -d -p 5000:5000 --name private-registry registry:2

Explanation:

• -d runs it in detached mode
• -p 5000:5000 maps port 5000 of host to container
• --name assigns a name to the container

Your registry is now available at http://localhost:5000

Step 3: Push an Image to Your Private Registry

docker pull alpine
docker tag alpine localhost:5000/my-alpine
docker push localhost:5000/my-alpine

Add localhost:5000 as an insecure registry in Docker config for testing (/etc/docker/daemon.json):

{
  "insecure-registries": ["localhost:5000"]
}

Step 4: Pull & Use Images from Private Registry

docker pull localhost:5000/my-alpine
docker run -it localhost:5000/my-alpine sh

Optional: Add Basic Authentication

Secure your registry with a username and password.

Step 1: Create Credentials File

mkdir auth
docker run --entrypoint htpasswd httpd:2 -Bbn username password > auth/htpasswd

Step 2: Run the Secure Registry

docker run -d -p 5000:5000 \
  --name secure-registry \
  -v $(pwd)/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  registry:2

Optional: Use Domain & SSL for Production

1. Point a domain to your server IP
2. Use NGINX/Caddy as a reverse proxy
3. Obtain SSL from Let’s Encrypt or create a self-signed certificate
4. Configure Docker clients to trust your cert

Cleaning Up

Stop and remove your registry container:

docker stop private-registry
docker rm private-registry

Summary – Recap & Next Steps

Setting up a private Docker registry empowers your team with secure, customizable image storage. Whether you’re testing locally or deploying at scale, this setup gives you control over image distribution and compliance.

Key Takeaways:

• Use registry:2 image to create a self-hosted registry
• Push/pull images with custom tags like localhost:5000/my-image
• Secure access with htpasswd authentication
• Add SSL and domain for production use
• Avoid Docker Hub limits with complete autonomy

Real-World Relevance: A private registry is essential in enterprise DevOps, internal microservices, and regulated environments.

Frequently Asked Questions (FAQs)

Q1: Is a private Docker registry free?

Yes. The official Docker registry image is open-source and free to use.
You only pay for server infrastructure (VM, storage, etc.)

Q2: How can I access the private registry from another machine?

Use the host’s IP or domain:

docker pull your-server-ip:5000/image-name

Ensure the client trusts your registry in its daemon.json.

Q3: Can I set up multiple users?

Yes. Use htpasswd to generate multiple credentials
For advanced setups, integrate LDAP or OAuth.

Q4: What is the default storage path?

Images are stored inside the container filesystem.

To persist data:

-v /your/host/dir:/var/lib/registry

Q5: Is HTTP safe for production?

No. Always use HTTPS in production
Use SSL/TLS to protect login credentials and image transfers

Q6: How can I delete images?

1. Use Docker Registry HTTP API or manually remove the image files
2. Run garbage collection:

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