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.

Disclosure: contains an affiliate link to Inferno VPS.

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)

NeedPick
One or a handful of services, hand-edited configCaddy
Many services, frequent additions via Compose labelsTraefik
Smallest possible config fileCaddy
Built-in support for many backend types (TCP, UDP, gRPC)Traefik
Dashboard / observability out of the boxTraefik
Static-file serving alongside reverse proxyingCaddy

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.

View Inferno plans →

What to do next


Author: Daniel Ferro — Lisbon. Last tested: 2026-05-22 on Caddy 2.8-alpine, Docker CE 27.3, Ubuntu 22.04.