Nginx or Caddy before Docker containers: automatic TLS and HTTP/3
Staging
Several containers run on the VPS: Next.js on port 3000, API on 8080. We need one reverse proxy that accepts 80 and 443, issues and renews Let's Encrypt certificates, serves HTTP/2 and HTTP/3, and proxies across domains. Two real candidates are Caddy and Nginx. Below are the working configurations of both and an analysis of where each breaks down.
Common to both: only proxies are published. Application containers do not have a ports section; the proxy goes to them by the service name within the compose network.
Caddy: minimum configuration
# compose.yml
services:
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp" # HTTP/3 работает поверх QUIC, то есть UDP
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
web:
build: ./web
api:
build: ./api
volumes:
caddy_data:
caddy_config:# Caddyfile
{
email ops@example.com
}
example.com {
encode zstd gzip
reverse_proxy web:3000
}
api.example.com {
reverse_proxy api:8080
}
www.example.com {
redir https://example.com{uri} permanent
}That's enough. Caddy itself will receive ACME certificates, renew them, redirect HTTP to HTTPS and enable HTTP/3 (in Caddy 2 it is enabled by default, only a forwarded UDP port is needed). The X-Forwarded-For and X-Forwarded-Proto headers are set automatically.
Volume caddy_data is critical. It contains certificates and ACME account keys. Without a volume, each recreated container requests certificates anew, and with frequent deployments you will run into Let's Encrypt's release limits for a single domain.
Nginx: more manual work
# conf.d/example.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name example.com www.example.com;
location /.well-known/acme-challenge/ { root /var/www/certbot; }
location / { return 301 https://example.com$request_uri; }
}
server {
listen 443 ssl;
listen 443 quic reuseport;
http2 on;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
add_header Alt-Svc 'h3=":443"; ma=86400' always;
resolver 127.0.0.11 valid=10s;
set $web http://web:3000;
location / {
proxy_pass $web;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}Explanations for non-obvious lines:
listen 443 quicand thehttp2 ondirective appeared in branch 1.25. The HTTP/3 module must be built: checkdocker compose exec nginx nginx -V 2>&1 | grep -o http_v3_module.reuseportis specified once per address:port pair. In the secondserverwithquicwritelisten 443 quic;without it, otherwise nginx will not start.Alt-Svctells the browser that the server knows HTTP/3. The first request always goes over TCP, the next ones through QUIC.resolver 127.0.0.11and the variable inproxy_pass- workaround the classic problem. Nginx resolves the namewebonce at startup. If the container is recreated and received a new IP, the proxy will continue to send requests to the old address and return 502. With a variable, the name is resolved through Docker's built-in DNS and cached for 10 seconds. Without this same technique, nginx will not start at all ifwebis not yet raised:host not found in upstream.
Certificates are a separate task: certbot container with webroot /var/www/certbot, shared volume with /etc/letsencrypt and regular renewal followed by nginx -s reload. Forgotten reload is a common cause of an expired certificate when a file has been successfully renewed.
Essential comparison
| Question | Caddy | Nginx | |---|---|---| | TLS Issue and Renewal | built-in | certbot or acme.sh separately | | HTTP/3 | default | need module and listen quic | | Rebuilding containers | resolves names dynamically | need resolver and variable | | Caching responses | via plugins | inline proxy_cache | | Request limits | via plugins | built-in limit_req, limit_conn | | Ready-made configs and answers on forums | less | a lot |
How to check
# HTTP/2 и заголовок Alt-Svc curl -sI https://example.com | grep -iE "^HTTP|alt-svc" # HTTP/3, если curl собран с его поддержкой curl --http3-only -sI https://example.com | head -1 # Сертификат и срок действия echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \ | openssl x509 -noout -issuer -enddate
In the browser, open DevTools, Network tab and turn on the Protocol column: after loading again, there should be h3.
Where HTTP/3 usually breaks down
- UDP 443 closed. Opening the port in compose is not enough: check UFW (
ufw allow 443/udp) and the provider's cloud firewall, where the rules for TCP and UDP are separate. - Website behind Cloudflare with proxying enabled. Then HTTP/3 with the browser is terminated by Cloudflare, and traffic goes to your server via TCP. Setting up QUIC on origin is pointless.
- Corporate networks are cutting UDP. The browser will fall back to HTTP/2, and this is normal behavior and not a bug.
What to choose
For multiple services on the same server without special requirements, Caddy gives working HTTPS and HTTP/3 with the least amount of room for error. Nginx is justified if you need a built-in cache, thin limits, you already have debugged configs or the team knows it well. Performance on typical workloads of a small project depends on the application, not on the proxy, so it’s not worth choosing based on it.