How to Create a Private Registry in Docker: Step-by-Step Guide

To create a private Docker registry, run the official registry image using docker run -d -p 5000:5000 --name registry registry:2. This starts a local registry on port 5000 where you can push and pull Docker images privately.

Syntax

The basic command to start a private Docker registry is:

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

Explanation of parts:

• docker run: Runs a new container.
• -d: Runs the container in detached mode (in the background).
• -p 5000:5000: Maps port 5000 of your machine to port 5000 in the container.
• --name registry: Names the container "registry" for easy reference.
• registry:2: Uses the official Docker registry image, version 2.

bash

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

Output

a long container ID string indicating the registry container started successfully

Example

This example shows how to start a private registry, tag an image, and push it to your local registry.

bash

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

docker pull busybox

docker tag busybox localhost:5000/my-busybox

docker push localhost:5000/my-busybox

Output

Unable to find image 'busybox:latest' locally
latest: Pulling from library/busybox
Digest: sha256:...
Status: Downloaded newer image for busybox:latest
The push refers to repository [localhost:5000/my-busybox]
...
Pushed

Common Pitfalls

Common mistakes when creating a private Docker registry include:

• Not mapping the port correctly, so the registry is unreachable.
• Forgetting to tag images with the registry address before pushing.
• Not configuring TLS for secure communication (the example uses HTTP by default).
• Trying to push without logging in if authentication is enabled.

For production, always secure your registry with TLS and authentication.

bash

docker push my-busybox
# Error: "denied: requested access to the resource is denied"

# Correct way:
docker tag busybox localhost:5000/my-busybox
docker push localhost:5000/my-busybox

Quick Reference

Summary tips for creating and using a private Docker registry:

• Use docker run -d -p 5000:5000 --name registry registry:2 to start the registry.
• Tag images with localhost:5000/your-image-name before pushing.
• Push images using docker push localhost:5000/your-image-name.
• Pull images using docker pull localhost:5000/your-image-name.
• For security, configure TLS and authentication in production.

Key Takeaways

Run the official registry image with port 5000 exposed to create a private Docker registry.

Always tag your images with the registry address before pushing to the private registry.

Use HTTP by default for local testing but configure TLS for secure production use.

Common errors come from missing tags or incorrect port mapping.

Secure your private registry with authentication and TLS in real environments.