Caddy reverse proxy for Docker (2026 guide)
If Nginx feels too manual and Traefik feels too much, Caddy is the middle path: a four-line Caddyfile gets you automatic HTTPS for any number of upstream containers — without label gymnastics.
The four-line Caddyfile
This is genuinely the entire config for a single service:
app.example.com {
reverse_proxy app:8080
}
That's it. Caddy provisions a Let's Encrypt certificate on first start, renews it automatically, redirects HTTP to HTTPS, and serves HTTP/2. No flags, no extra services, no acme.json to chmod.
The setup
mkdir -p ~/caddy && cd ~/caddy
nano docker-compose.yml
name: caddy
networks:
proxy:
name: proxy
services:
caddy:
image: caddy:2.8-alpine
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
networks:
- proxy
volumes:
caddy_data:
caddy_config:
Create the Caddyfile:
nano Caddyfile
# Global options
{
email you@example.com
}
# n8n
n8n.example.com {
reverse_proxy n8n:5678
encode gzip
request_body {
max_size 50MB
}
}
# Generic app
app.example.com {
reverse_proxy app:8080
}
# Static site with a basic-auth gate
status.example.com {
basicauth {
admin $2a$14$HASH_FROM_caddy_hash-password
}
reverse_proxy uptime-kuma:3001
}
Bring it up:
docker compose up -d
docker compose logs -f caddy
Caddy walks each example.com entry, validates DNS, requests a certificate over HTTP-01 (or TLS-ALPN-01 on port 443), and starts serving. Visit each URL — green padlock on the first request.
Connecting apps to Caddy
Each upstream service has to be reachable on the same Docker network as Caddy. The simplest pattern: declare the network external and join from each app:
services:
n8n:
image: docker.n8n.io/n8nio/n8n:1.71.3
networks:
- proxy
- default
# ... rest of the n8n compose ...
networks:
proxy:
external: true
default:
Caddy now resolves the hostname n8n to the n8n container's IP on the shared network. The reverse_proxy n8n:5678 line works without any extra labels.
Generating the basic-auth hash
docker run --rm caddy:2.8-alpine caddy hash-password
# Type the password twice; copy the $2a$... hash into Caddyfile
# (no $ escaping required in Caddyfile, unlike Compose labels)
Tuning per route
The Caddyfile is delightfully readable. A few common knobs:
n8n.example.com {
reverse_proxy n8n:5678
encode gzip zstd
request_body { max_size 50MB }
# Custom security headers (Caddy already sets a sensible default set)
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options nosniff
Referrer-Policy no-referrer
X-Frame-Options SAMEORIGIN
}
# Rate-limit a webhook endpoint
@webhooks path /webhook/*
rate_limit @webhooks {
zone webhook { window 1m events 600 }
}
}
The rate_limit directive requires the rate-limit plugin — easiest way is to build a custom Caddy image with xcaddy. For most setups, stick with the upstream image and the included directives.
Wildcard certificates (DNS-01)
For wildcards (*.example.com), Caddy needs a DNS plugin for your provider. Cloudflare is the most common:
# Use a custom image with the plugin baked in
services:
caddy:
image: ghcr.io/example/caddy-with-cloudflare:2.8
# ... rest unchanged
environment:
CLOUDFLARE_API_TOKEN: ${CLOUDFLARE_API_TOKEN}
# Caddyfile
*.example.com {
tls {
dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}
reverse_proxy {host}.svc:80 # placeholder; route to per-subdomain backends
}
Pre-built images with various DNS plugins exist on the Caddy community Docker repos. Building your own with xcaddy takes about a minute.
Caddy vs Traefik (when to pick which)
| Need | Pick |
|---|---|
| One or a handful of services, hand-edited config | Caddy |
| Many services, frequent additions via Compose labels | Traefik |
| Smallest possible config file | Caddy |
| Built-in support for many backend types (TCP, UDP, gRPC) | Traefik |
| Dashboard / observability out of the box | Traefik |
| Static-file serving alongside reverse proxying | Caddy |
Both are excellent. Pick based on the shape of the team — Caddy is friendlier for teams that prefer one obvious config file; Traefik is friendlier for teams already living in Compose labels. See our Traefik guide for the comparison from the other direction.
Backing up Caddy
Two volumes matter: caddy_data (certificates + ACME account) and the Caddyfile itself (in git). Back them up the same way you back up other volumes — see our backup guide pattern. Losing caddy_data isn't catastrophic — Caddy re-issues certs on next start — but you'll hit Let's Encrypt rate limits if you do it on a large set of domains.
Reloading after edits
# Validate
docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile
# Graceful reload (no dropped connections)
docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile
Don't docker compose restart just to re-read the Caddyfile — the reload is graceful and instant.
Common Caddy mistakes
"Connection refused" to the upstream
The app container isn't on the shared network. Add networks: [proxy] to it. Confirm with docker network inspect proxy.
Certificate stays self-signed forever
DNS for the hostname doesn't point at the server, or port 80 is blocked. Caddy retries with exponential backoff; check the logs for the actual ACME error.
"server.go: server connections are blocked"
You have another process bound to port 80 or 443. Usually a leftover Nginx from before. sudo systemctl disable --now nginx.
Caddy reloads but old config keeps serving
You edited the file on the host but Caddy reads it from /etc/caddy/Caddyfile inside the container. Confirm the volume mount is ./Caddyfile:/etc/caddy/Caddyfile:ro and that you're editing the file in the right directory.
VPS for a Caddy-fronted stack?
Caddy itself uses ~30 MB RAM. Fits on every Inferno plan; the 2 GB tier handles Caddy + several typical self-hosted apps.
What to do next
- Compare with Traefik if you're undecided.
- Harden the apps Caddy fronts.
- Watchtower for image updates — keep Caddy itself on a pinned tag and let auto-updates work on the apps behind it.
- Uptime Kuma to alert when a routed domain stops responding.
Author: Daniel Ferro — Lisbon. Last tested: 2026-05-22 on Caddy 2.8-alpine, Docker CE 27.3, Ubuntu 22.04.