🔒 Private Docker Registry Setup

As Docker becomes more integral to modern DevOps workflows, managing and distributing images securely becomes crucial. While Docker Hub offers a public registry for storing and sharing images, there are scenarios where hosting your own private Docker registry is necessary — especially when dealing with proprietary applications, sensitive codebases, or compliance policies.

In this guide, we’ll walk you through the setup of a private Docker registry, step by step, and answer frequently asked questions to help you get up and running confidently.

---

📌 What is a Private Docker Registry?

A private Docker registry is a storage and distribution system for Docker images that you host and manage within your own infrastructure or cloud. It behaves like Docker Hub but remains accessible only within your network or to authorized users.

Why use a private registry?

• ✅ Keep proprietary images secure and internal
• ✅ Improve build and deployment speed in local environments
• ✅ Customize access control and storage
• ✅ Avoid rate limits and downtime from public services

---

🧰 Prerequisites

Before you begin, ensure you have the following:

• A system with Docker installed (Linux, Windows, or macOS)
• Basic knowledge of Docker commands
• Optional: Domain name and SSL certificate for production use

---

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

🔹 Step 1: Pull the Registry Image

Docker provides an official image for the registry.

docker pull registry:2

ℹ️ This command pulls version 2 of the Docker Registry, which is the latest stable version.

---

🔹 Step 2: Run the Registry Container

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

Explanation:

• -d: Run in detached mode
• -p 5000:5000: Maps port 5000 on host to container
• --name: Names the container private-registry

Your private registry is now accessible at http://localhost:5000.

---

🔹 Step 3: Tag and Push an Image

Let’s push an image to your registry.

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

📝 Ensure that localhost:5000 is included in Docker’s list of insecure registries for testing.

---

🔹 Step 4: Use the Image from Your Private Registry

To pull and use the image from your private registry:

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

---

🔐 Optional: Enable Authentication

For secure access, add basic authentication using htpasswd.

Step 1: Create Credentials File

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

Step 2: Run Registry with Auth

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 a Domain with SSL (Recommended for Production)

To use a custom domain and secure it with HTTPS:

1. Set up a domain pointing to your server IP.
2. Use NGINX or Caddy as a reverse proxy.
3. Generate and install an SSL certificate (Let’s Encrypt or self-signed).
4. Update Docker clients to trust the certificate.

---

🧽 Cleaning Up

To stop and remove the registry:

docker stop private-registry
docker rm private-registry

---

✅ Conclusion

Setting up your private Docker registry is straightforward and gives you full control over how container images are stored, shared, and secured within your organization or development workflow. With authentication and SSL in place, you can scale and manage your container infrastructure with confidence.

---

❓ Frequently Asked Questions (FAQs)

🔸 Q1: Is a private Docker registry free?

Yes, the official Docker registry image is open-source and free. However, storage and server hosting may incur costs.

---

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

Use the IP or hostname of the registry server. You must configure Docker on the client machine to trust the registry, especially if it’s using HTTP or a self-signed certificate.

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

---

🔸 Q3: Can I set up multiple users for access control?

Yes. Use a tool like htpasswd to create credentials for multiple users, or implement advanced authentication via LDAP or OAuth.

---

🔸 Q4: What is the default storage location for images?

By default, images are stored in the container filesystem. For persistence, mount a volume:

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

---

🔸 Q5: Is it safe to run a private registry over HTTP?

For testing, it’s okay to run without HTTPS, but never in production. Always use SSL/TLS to secure image transfers and credentials.

---

🔸 Q6: Can I delete images from my private registry?

Yes, but it’s not as straightforward. You need to:

1. Delete the image via API or manually remove files.
2. Run the garbage collection command:

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

---