As containerized applications become the norm in modern software delivery, organizations need secure, scalable, and efficient ways to manage Docker images. While public registries like Docker Hub are useful, they may not meet enterprise needs for privacy, control, and speed.

This guide walks you through setting up a custom Docker registry, enabling TLS encryption, authentication, and scaling strategies for managing container images securely within your infrastructure.

Why Use a Custom Docker Registry?

Benefits include:

  • Security: Host images in your own network with encryption and access control
  • Performance: Reduce external dependency and speed up deployments
  • Control: Apply custom image retention, tagging, and cleanup policies
  • Compliance: Meet internal or industry regulations (e.g., HIPAA, GDPR)
  • CI/CD Integration: Seamless integration with pipelines without rate limiting

Step 1: Basic Registry Setup with Docker

Start by running a registry container:

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

This sets up an open, unauthenticated registry accessible on port 5000.

Test by pushing an image:

docker tag nginx localhost:5000/nginx
docker push localhost:5000/nginx

Step 2: Enable TLS for Secure Image Transfer

To secure your registry:

  1. Generate self-signed or trusted TLS certificates:
openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key \
-x509 -days 365 -out domain.crt
  1. Mount certs to the registry container:
docker run -d \
--name my-registry \
-v $(pwd)/certs:/certs \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
-p 443:5000 \
registry:2
  1. Configure Docker clients to trust the cert (or disable cert verification in dev).

Step 3: Add Basic Authentication

  1. Install htpasswd and generate credentials:
htpasswd -Bbn admin strongpassword > auth/htpasswd
  1. Run registry with auth enabled:
docker run -d \
--name my-registry \
-v $(pwd)/auth:/auth \
-v $(pwd)/certs:/certs \
-e "REGISTRY_AUTH=htpasswd" \
-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
-e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
-e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt" \
-e "REGISTRY_HTTP_TLS_KEY=/certs/domain.key" \
-p 443:5000 \
registry:2

Push and pull will now require credentials.

Step 4: Enable Storage Backend and Cleanup Policies

By default, images are stored on the container’s local filesystem.

To use external storage like S3:

storage:
s3:
accesskey: YOUR_KEY
secretkey: YOUR_SECRET
region: us-east-1
bucket: my-registry-bucket
encrypt: true

You can also set:

  • Retention policies using lifecycle scripts
  • Garbage collection via:
registry garbage-collect /etc/docker/registry/config.yml

Step 5: High Availability and Scaling

To scale your registry:

  • Use HAProxy/Nginx as a load balancer across multiple registry instances
  • Store images in shared backend (e.g., S3 or NFS)
  • Use Redis or etcd for shared caching or metadata if needed
  • Deploy behind Kubernetes Ingress for better control and integration

Step 6: Kubernetes Integration

To use a private registry in Kubernetes:

  1. Create a Docker registry secret:
kubectl create secret docker-registry regcred \
--docker-server=myregistry.com \
--docker-username=admin \
--docker-password=strongpassword \
--docker-email=you@example.com
  1. Reference it in your pod:
imagePullSecrets:
- name: regcred

Step 7: Monitor and Audit

Monitor your registry with:

  • Prometheus Exporters (e.g., registry_exporter)
  • Access logs via Docker logs
  • Audit trails for who pulled/pushed what and when

Security Best Practices

  • Use TLS with trusted CAs
  • Rotate credentials and certificates
  • Limit access using firewalls and ACLs
  • Enable image signing and verification (Docker Content Trust or Notary)
  • Set up RBAC with OAuth/LDAP if required

Conclusion

A custom Docker registry gives you full control over how container images are stored, accessed, and deployed. Whether you’re supporting internal dev teams or deploying in production, building a secure and scalable registry helps improve reliability, meet compliance goals, and reduce dependency on third-party services.

By integrating TLS, authentication, storage backends, and scaling strategies, you can operate a registry that’s truly enterprise-ready.