Skip to content
Blog

Enabling HTTPS and TLS for Private Docker Registries

Securing private Docker registries with HTTPS and TLS certificates, generating self-signed or Let's Encrypt certificates, configuring NGINX reverse proxies, and trusting root CA bundles.

Published on • November 18, 2026

AI Assistant

By default, the Docker Engine CLI requires all remote container registry connections to be encrypted using TLS/HTTPS. If you attempt to push or pull from a private registry over plain HTTP (e.g. 192.168.1.10:5000), the Docker daemon rejects the connection with:

Error response from daemon: Get "https://192.168.1.10:5000/v2/": http: server gave HTTP response to HTTPS client

In this tutorial, we will learn how to enable HTTPS for a self-hosted Docker registry using self-signed TLS certificates, configure an NGINX reverse proxy for TLS termination, and install CA certificates on host systems.

Overview of TLS Architectures for Registries

+-----------------------------------------------------------------------------------+
| Option A: Native Registry TLS                                                     |
|   - Mount TLS certificates directly into the `registry:2` container.              |
|   - Simplest architecture for single-node private setups.                          |
+-----------------------------------------------------------------------------------+
| Option B: TLS Termination via NGINX / Caddy Proxy (Recommended)                   |
|   - NGINX handles HTTPS termination, cert rotation, rate limits, & CORS headers.   |
|   - Registry runs in background on localhost HTTP.                                |
|   - Supports automated ACME Let's Encrypt certificates.                           |
+-----------------------------------------------------------------------------------+

Method 1: Generating and Using Self-Signed Certificates

For internal lab environments or private network testing, generate a custom CA and server certificate using openssl.

Step 1: Generate Self-Signed TLS Certificates

mkdir -p /opt/registry/certs

openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout /opt/registry/certs/domain.key \
  -x509 -days 365 \
  -out /opt/registry/certs/domain.crt \
  -subj "/CN=registry.internal.net" \
  -addext "subjectAltName=DNS:registry.internal.net,IP:192.168.1.10"

Step 2: Deploy Registry Container with TLS Certificates

Mount the certificate files and pass environment variables to registry:2:

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

Step 3: Installing Self-Signed CA on Docker Host Clients

Because the certificate is self-signed, client Docker daemons will reject it (x509: certificate signed by unknown authority). You must copy the certificate to Docker’s trusted certificates directory on all client hosts:

# Create directory matching target registry hostname & port
sudo mkdir -p /etc/docker/certs.d/registry.internal.net:443

# Copy the server public certificate
sudo cp /opt/registry/certs/domain.crt /etc/docker/certs.d/registry.internal.net:443/ca.crt

# Restart Docker daemon to refresh certificate store
sudo systemctl restart docker

Now docker login registry.internal.net:443 will succeed securely without errors!

In production, placing an NGINX reverse proxy in front of the registry is recommended for certificate management, upload buffering, and header rewriting.

docker-compose.yml with NGINX and Registry

version: '3.8'

services:
  registry:
    image: registry:2
    restart: always
    environment:
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
    volumes:
      - /opt/registry/data:/var/lib/registry

  nginx:
    image: nginx:alpine
    restart: always
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - /opt/registry/certs:/etc/nginx/certs:ro
    depends_on:
      - registry

Production nginx.conf Configuration

events { worker_connections 1024; }

http {
    # Crucial: Allow uploading large container layer blobs (default is 1MB!)
    client_max_body_size 0;

    # Disable chunked transfer encoding buffering for docker push compatibility
    chunked_transfer_encoding on;

    upstream docker-registry {
        server registry:5000;
    }

    server {
        listen 443 ssl;
        server_name registry.internal.net;

        ssl_certificate /etc/nginx/certs/domain.crt;
        ssl_certificate_key /etc/nginx/certs/domain.key;

        # Modern SSL protocol configurations
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;

        location /v2/ {
            # Required Docker registry headers
            proxy_pass http://docker-registry;
            proxy_set_header Host $http_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;
            proxy_read_timeout 900;
        }
    }
}

Key detail: client_max_body_size 0; disables body size limits in NGINX. Without this setting, pushing layers larger than 1 MB will fail with 413 Request Entity Too Large.

Verifying TLS Security Setup

Test your secure registry setup using curl and docker:

# Verify TLS handshake and certificate chain
curl -v https://registry.internal.net/v2/

# Test docker login and image push
docker login registry.internal.net
docker tag alpine:latest registry.internal.net/my-alpine:v1
docker push registry.internal.net/my-alpine:v1

Summary Checklist

ComponentSetting / Command
Certificate SANEnsure Subject Alternative Name (SAN) contains domain or IP
Docker Certs Path/etc/docker/certs.d/<registry-domain>/ca.crt
NGINX Upload Limitclient_max_body_size 0;
Proxy Timeoutproxy_read_timeout 900; (prevents timeouts during large layer pushes)

Enabling TLS/HTTPS for private container registries protects credentials and layer data in transit across enterprise networks.