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!
Method 2: TLS Termination with NGINX Reverse Proxy (Recommended)
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
| Component | Setting / Command |
|---|---|
| Certificate SAN | Ensure Subject Alternative Name (SAN) contains domain or IP |
| Docker Certs Path | /etc/docker/certs.d/<registry-domain>/ca.crt |
| NGINX Upload Limit | client_max_body_size 0; |
| Proxy Timeout | proxy_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.