Caddy Web Server

Automatic HTTPS

Caddy is the only web server that provisions and renews Let's Encrypt TLS certificates automatically. Zero configuration needed. Supports ACME HTTP-01, DNS-01, and TLS-ALPN challenges. Point a domain at your server, write a Caddyfile, and HTTPS just works.

• Certificates stored in ~/.local/share/caddy (Linux) or $HOME/Library/Application Support/Caddy (macOS)
• Auto-renews certificates before expiry — no cron job needed
• On-demand TLS: provision certificates the first time a domain is requested
• Local HTTPS for development via a built-in local CA (caddy trust)
• Supports ZeroSSL and custom ACME endpoints in addition to Let's Encrypt

Caddyfile Syntax

Caddy's config language is drastically simpler than nginx or Apache. A full reverse proxy with HTTPS is just 3 lines. Caddy also exposes a JSON API for programmatic configuration and supports hot-reload without downtime via caddy reload.

• Intuitive block-based syntax — no semicolons, no location blocks
• Directives are ordered by priority automatically; no try_files hacks
• JSON API: POST /load to push a new config atomically
• caddy reload applies changes without dropping connections
• Named matchers for reusable request matching logic

HTTP/2 and HTTP/3

HTTP/2 is enabled by default for all HTTPS sites in Caddy. HTTP/3 (QUIC) is available via the experimental protocol config. Both multiplexing and header compression are built in — no extra modules to install.

• HTTP/2 enabled automatically for all TLS connections
• HTTP/3 via servers { protocol { experimental_http3 } } in global config
• QUIC requires UDP 443 to be open at the firewall
• Server push available (HTTP/2) for preloading critical assets
• Graceful fallback to HTTP/1.1 for older clients

Security Defaults

Caddy sets secure TLS defaults out of the box: TLS 1.2 minimum, modern cipher suites, OCSP stapling, and automatic HSTS for HTTPS sites. Security headers (CSP, X-Frame-Options, etc.) must be added manually via the header directive — but the TLS foundation is already hardened.

• TLS 1.2 minimum enforced globally; TLS 1.3 preferred
• Modern cipher suites only: ECDHE with AES-GCM and ChaCha20-Poly1305
• OCSP stapling enabled by default for faster TLS handshakes
• Automatic HSTS with includeSubDomains when HTTPS is active
• No server version disclosed in response headers by default

Strip path prefix when proxying

Use handle_path instead of handle to strip the matched prefix before forwarding the request. Useful when your upstream app is designed to run at / but you're exposing it at /app/.

example.com {
    handle_path /app/* {
        reverse_proxy localhost:8080
    }
}

A request to /app/login arrives at the backend as /login.

Health checks on upstream

Caddy can actively probe upstreams and automatically remove unhealthy backends from the rotation. If the health check fails, Caddy returns a 502 rather than forwarding to a dead backend.

example.com {
    reverse_proxy localhost:3000 {
        health_uri      /health
        health_interval 10s
        health_timeout  5s
    }
}

WebSocket proxying

WebSocket connections work automatically in Caddy — no special configuration needed. Caddy detects Upgrade: websocket headers and performs the connection upgrade transparently, passing it through to the upstream.

# Nothing extra needed — just proxy as usual:
example.com {
    reverse_proxy localhost:3000
}

This works for Socket.IO, native WebSockets, and SSE (Server-Sent Events).

Redirect HTTP to HTTPS (manual)

For named domains, Caddy redirects HTTP to HTTPS automatically. If you need a manual redirect (e.g., you turned off auto_https):

http://example.com {
    redir https://{host}{uri} permanent
}

https://example.com {
    reverse_proxy localhost:3000
}

Custom TLS certificate

Use your own certificate instead of having Caddy provision one from Let's Encrypt. Useful when certificates are managed externally (e.g., by Vault, AWS ACM, or an internal CA).

example.com {
    tls /path/to/cert.pem /path/to/key.pem
    reverse_proxy localhost:3000
}

Caddy will still watch for cert file changes and reload them hot.

Load balancing across multiple upstreams

Caddy supports round-robin, random, least-connections, and IP-hash load balancing. Combine with health checks for automatic failover.

example.com {
    reverse_proxy {
        to localhost:3001 localhost:3002 localhost:3003
        lb_policy least_conn
        health_uri /health
        health_interval 15s
    }
}

Rate limiting (with plugin)

Basic rate limiting requires the caddy-ratelimit plugin baked into a custom Caddy build. For simpler setups, put Cloudflare or a WAF in front. Custom Caddy builds with plugins: caddyserver.com/download.

# With caddy-ratelimit plugin installed:
example.com {
    rate_limit {remote_host} 100r/m
    reverse_proxy localhost:3000
}

Global options block

The { } block at the top of a Caddyfile (before any site blocks) sets global options. Common settings: email for Let's Encrypt, disabling automatic HTTPS (useful behind Cloudflare Tunnel), and enabling HTTP/3.

{
    email [email protected]
    auto_https off          # if TLS is handled upstream
    servers {
        protocol {
            experimental_http3
        }
    }
}

example.com {
    reverse_proxy localhost:3000
}

Validate Caddyfile syntax

Check your Caddyfile for syntax errors without applying it. Returns a non-zero exit code on failure — safe to use in CI pipelines.

caddy validate --config /etc/caddy/Caddyfile

In Docker: docker exec caddy caddy validate --config /etc/caddy/Caddyfile

Inspect the compiled JSON config

See the internal JSON representation that Caddy actually runs. Useful for debugging directive ordering and understanding how Caddy interprets your Caddyfile.

caddy adapt --config /etc/caddy/Caddyfile \
  --adapter caddyfile | jq .

Auto-reload on file change (dev mode)

Run Caddy in watch mode during development. Any change to the Caddyfile triggers an automatic reload — no manual caddy reload needed.

caddy run --watch

Caddy watches the Caddyfile in the current directory by default. Combine with --config to specify a path.

ACME challenge troubleshooting

If Caddy fails to obtain a Let's Encrypt certificate, check these common causes:

• Port 80 must be publicly reachable for HTTP-01 challenge
• DNS must point to your server's IP before Caddy starts
• If behind a reverse proxy or CDN, disable their caching for /.well-known/acme-challenge/
• Let's Encrypt rate limits: 5 failures per hour per domain
• For DNS-01 challenge (behind NAT): use a custom Caddy build with a DNS provider plugin

Locate TLS certificate files

If you need to inspect or copy the certificates Caddy obtained:

# Linux (systemd package install)
ls /var/lib/caddy/.local/share/caddy/certificates/

# macOS (Homebrew)
ls "$HOME/Library/Application Support/Caddy/certificates/"

# Docker (named volume)
docker run --rm -v caddy_data:/data alpine ls \
  /data/caddy/certificates/

View logs

Caddy logs are structured JSON by default (Zap logger). Filter and pretty-print them with jq.

# Linux systemd
journalctl -u caddy --since "10 minutes ago"

# Docker
docker logs caddy --since 10m -f

# Pretty-print JSON log line
journalctl -u caddy -n 50 -o cat | jq .msg

Test reverse proxy headers

Verify that Caddy is forwarding the correct headers to your backend. curl -v shows request and response headers.

# Check response headers from Caddy
curl -I https://example.com

# Check what headers your backend receives
# (add a /debug/headers route in your app, or use httpbin)
curl https://example.com/debug/headers

Caddy automatically sets X-Forwarded-For, X-Forwarded-Proto, and X-Real-IP when reverse proxying.

Caddy API — live config inspection

Caddy's admin API (localhost:2019 by default) lets you inspect and update the running config programmatically without a reload.

# View running config
curl http://localhost:2019/config/

# Reload config via API
curl -X POST "http://localhost:2019/load" \
  -H "Content-Type: text/caddyfile" \
  --data-binary @/etc/caddy/Caddyfile

Disable the admin API in production if not needed: { admin off } in the global options block.