Deploying a Private Docker Registry with Docker-Registry and Web UI

🚀 Docker Registry + Web UI Private Image Repository Deployement Guide

docker-registry is an official lightweight private Docker image registry. Paired with docker-registry-ui, it provides a web interface suitable for individuals or small teams.

📌 1. Environment Requirements

Operating System: Linux (CentOS 7+, Ubuntu 20.04+, Rocky Linux 9+)
CPU: 2 cores or more
Memory: 2GB or more
Storage: 50GB or more (adjust based on image size)
Docker: Version 28.0.0+
Docker Compose: Version 2.0+

📌 2. Install Docker and Docker Compose

📍 2.1 Install Docker

curl -fsSL https://get.docker.com | bash
systemctl enable docker --now

📍 2.2 Verify Docker Version

docker version

Ensure both Client & Server versions are 28.0.0 or higher.

📍 2.3 Install Docker Compose

mkdir -p /usr/local/lib/docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o /usr/local/lib/docker/cli-plugins/docker-compose
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
docker compose version

📌 3. Deploy Docker Registry

First, run Docker Registry listening on port 5000:

docker run -d -p 5000:5000 --restart=always --name registry registry:2

This starts a private Docker image registry on port 5000.
Images are stored by default in the /var/lib/registry directory.

📍 Verify Successful Startup

curl http://localhost:5000/v2/_catalog

If the response is { "repositories": [] }, the Regsitry is running correctly.

📌 4. Deploy Web UI

Use Joxit/docker-registry-ui to provide a web management interface:

docker run -d -p 8080:80 --restart=always --name registry-ui \
  -e REGISTRY_TITLE="My Private Registry" \
  -e NGINX_PROXY_PASS="http://registry:5000" \
  --link registry \
  joxit/docker-registry-ui:latest

📍 4.1 Access the Web UI

Now open your browser and visit:

http://localhost:8080

You will see the Docker Registry Web UI 🎉.

📌 5. Push and Pull Images

📍 5.1 Tag a Local Image

docker tag ubuntu:latest localhost:5000/ubuntu:latest

📍 5.2 Push the Image

docker push localhost:5000/ubuntu:latest

📍 5.3 Pull the Image

docker pull localhost:5000/ubuntu:latest

📍 5.4 List Images in the Registry

curl http://localhost:5000/v2/_catalog

📌 6. Configure Docker to Allow HTTP Access

By default, Docker does not allow HTTP access to private registries. Add the following to /etc/docker/daemon.json:

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

Then restart Docker:

systemctl restart docker

📌 7. Configure Registry Data Storage

To change the storage path, mount a host directory:

docker run -d -p 5000:5000 --restart=always \
  -v /data/registry:/var/lib/registry \
  --name registry registry:2

All image will be stored in the /data/registry directory.

📌 8. Use HTTPS for Secure Access (Recommended for Production)

📍 8.1 Generate a Self-Signed SSL Certificate

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

When prompted for certificate information, the Common Name (CN) must be your domain name or IP address.

📍 8.2 Run Registry with HTTPS

docker run -d -p 443:5000 --restart=always \
  -v /certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  --name registry registry:2

You can now access the private registry via https://your-domain.com.

📍 8.3 Configure Docker to Trust the Certificate

Copy domain.crt to:

cp /certs/domain.crt /etc/docker/certs.d/your-domain.com/ca.crt