Docker Registry Server Configuration – Securely Host and Manage Docker Images

Introduction – Why Set Up a Private Docker Registry?

If you’re building and deploying containerized applications, you’ll eventually need a secure and scalable way to manage Docker images. While Docker Hub is convenient, it lacks the control needed for sensitive, internal workloads.

A Docker Registry Server gives you full control over how and where your container images are stored, accessed, and distributed. Whether you’re a DevOps engineer, developer, or sysadmin, learning how to set up your own registry is essential for production-ready pipelines.

By the end of this guide, you’ll learn how to:

• Deploy a local Docker registry
• Secure it with authentication and HTTPS
• Push and pull Docker images
• Customize it with configuration files
• Optimize storage with garbage collection

What Is a Docker Registry?

A Docker Registry is a storage and distribution system for Docker images. It allows teams to:

• Store private images securely
• Share images across environments or teams
• Automate image delivery in CI/CD pipelines

Docker offers an open-source registry implementation via the registry:2 image, which can be hosted anywhere.

Step 1: Run a Local Docker Registry

To get started quickly, use the official Docker Registry image:

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

This runs a registry server on localhost:5000 with no authentication or TLS—ideal for local development and testing.

Step 2: Add Basic Authentication with htpasswd

For secure environments, authentication is a must.

Prerequisites:

• Install the htpasswd tool (apache2-utils package)
• Create a new credentials file

mkdir auth
htpasswd -Bc auth/htpasswd myuser

This generates a hashed password file for user myuser.

Step 3: Run an Authenticated Docker Registry

Now configure the registry to require login credentials:

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

Docker will now prompt for your username/password during image operations.

Step 4: Push and Pull Docker Images

Once your registry is running:

1. Tag your image: docker tag nginx localhost:5000/my-nginx
2. Push it to your private registry: docker push localhost:5000/my-nginx
3. Pull it back: docker pull localhost:5000/my-nginx

If you encounter an error, it may be due to insecure HTTP—next, we’ll solve that with HTTPS.

Step 5: Enable HTTPS with Self-Signed TLS Certificates

Production registries must use HTTPS to encrypt communication.

Generate Certificates:

mkdir certs
openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout certs/domain.key \
  -x509 -days 365 -out certs/domain.crt

Run the registry with TLS:

docker run -d \
  -p 443:5000 \
  --name registry-tls \
  -v $(pwd)/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  registry:2

Your registry is now accessible via https://localhost.

Step 6: Verify Registry Functionality

Use curl to confirm everything is working:

curl -u myuser:mypassword https://localhost:443/v2/_catalog --insecure

Expected Output:

{"repositories":["my-nginx"]}

This shows your registry is running, secure, and storing images correctly.

Step 7: Use a Custom Configuration File (Optional)

Advanced users can override the default settings with a YAML configuration.

Example: config.yml

version: 0.1
log:
  level: debug
storage:
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: :5000

Run the container with this config:

docker run -d -p 5000:5000 \
  -v $(pwd)/config.yml:/etc/docker/registry/config.yml \
  registry:2

This allows fine-tuning of logging, storage, and network settings.

Step 8: Clean Up Old Docker Images

Docker registries retain unused blobs unless garbage collection is triggered manually.

Run Garbage Collection:

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

The registry container must be stopped before running this to avoid corruption.

Summary – Key Takeaways

By configuring your own Docker Registry Server, you gain total control over image management in local or production environments.

Recap:

• Start with the registry:2 image
• Secure with htpasswd and TLS
• Tag, push, and pull images locally
• Customize behavior with a YAML config
• Run garbage collection to free up storage

Next Step: Use your registry in Kubernetes, CI/CD pipelines, or enterprise image workflows.

Frequently Asked Questions (FAQs)

What is a Docker Registry?
A centralized server where Docker images are stored and distributed via docker pull and docker push.

How do I log into a private Docker registry?
Use the command:

docker login localhost:5000

Why am I seeing errors when pushing images?
You may be pushing to an insecure HTTP registry. Add this in /etc/docker/daemon.json:

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

Then restart Docker.

Can I use a domain like registry.example.com?
Yes. Point DNS to your server and bind a certificate for that domain in your TLS config.

What are alternatives to self-hosting a registry?
Popular services include:

• Docker Hub (public & private repositories)
• AWS Elastic Container Registry (ECR)
• GitHub Container Registry
• Google Artifact Registry