Archivio Domande

 How to Install a Secure Docker Registry with Let's Encrypt on Ubuntu 24.04

A Docker Registry lets you securely host and distribute your own Docker images — ideal for private teams, CI/CD pipelines, or in-house app stores.

This guide walks you through setting up a secure, production-ready Docker Registry using Nginx and Let's Encrypt on Ubuntu 24.04 LTS.

 Prerequisites

• Ubuntu 24.04 server with sudo access
• A domain name (e.g. registry.yourdomain.com) pointing to your server
• Ports 80 and 443 open in your firewall
• Basic Linux and Docker familiarity

⚙️ Step 1 – Update your system and install dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y apt-transport-https ca-certificates curl gnupg-agent \
    software-properties-common apache2-utils docker.io nginx certbot python3-certbot-nginx

sudo systemctl enable docker
sudo systemctl start docker

 Step 2 – Create directories for the Registry

sudo mkdir -p /var/lib/registry
sudo mkdir -p /etc/docker/registry/auth

These folders store your container images and authentication files.

 Step 3 – Create an admin user for Registry access

sudo htpasswd -Bbn admin StrongPassword123! | sudo tee /etc/docker/registry/auth/htpasswd

Replace admin and StrongPassword123! with your own credentials.

 Step 4 – Run the Docker Registry container

sudo docker run -d \
  --restart=always \
  --name registry \
  -p 127.0.0.1:5000:5000 \
  -v /var/lib/registry:/var/lib/registry \
  -v /etc/docker/registry/auth:/auth \
  -e "REGISTRY_HTTP_ADDR=0.0.0.0:5000" \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  registry:2

 Step 5 – Configure Nginx as a reverse proxy

Create a new config file:

sudo nano /etc/nginx/sites-available/registry.conf

Paste the following:

server {
    listen 80;
    server_name registry.yourdomain.com;

    location / {
        proxy_pass                          http://localhost:5000;
        proxy_set_header  Host              $host;
        proxy_set_header  X-Real-IP         $remote_addr;
        proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header  X-Forwarded-Proto $scheme;
        client_max_body_size 0;
        chunked_transfer_encoding on;
    }
}

Then enable and reload Nginx:

sudo ln -s /etc/nginx/sites-available/registry.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

 Step 6 – Obtain a Let's Encrypt SSL certificate

sudo certbot --nginx -d registry.yourdomain.com \
  --agree-tos --redirect --non-interactive --email admin@yourdomain.com

Certbot automatically sets up HTTPS in your Nginx configuration.

sudo systemctl list-timers | grep certbot

This confirms automatic renewal is active.

 Step 7 – Allow firewall traffic for HTTP + HTTPS

sudo ufw allow 'Nginx Full'
sudo ufw reload

 Step 8 – Test your Docker Registry

Verify via curl:

curl -u admin:StrongPassword123! https://registry.yourdomain.com/v2/_catalog

You should see:

{"repositories":[]}

Login from any Docker client:

docker login registry.yourdomain.com
# Username: admin
# Password: StrongPassword123!

Push your first image:

docker tag nginx registry.yourdomain.com/nginx
docker push registry.yourdomain.com/nginx

♻️ Step 9 – Enable automatic updates

sudo apt update && sudo apt upgrade -y

Let's Encrypt certificates renew automatically via certbot.

✅ Summary

Your secure Docker Registry is now live at:

 https://registry.yourdomain.com

To test it: 

curl -u admin:StrongPassword123! https://registry.yourdomain.com/v2/_catalog

You should get: {"repositories":[]}

 Troubleshooting

• Check Docker logs:
  sudo docker logs registry
• Check Nginx logs:
  sudo tail -f /var/log/nginx/error.log
• Manually renew certificates:
  sudo certbot renew --dry-run

Article version 1.0 — tested on Ubuntu 24.04 LTS, Docker 24.x, Certbot 2.x