Caddy

# Caddy Configuration Rules ## Automatic HTTPS - Caddy provisions SSL certificates automatically — don't manually configure Let's Encrypt unless you have specific needs - Domain must resolve to the server publicly for HTTP challenge — use DNS challenge for internal/wildcard certs - Ports 80 and 443 must be free — Caddy needs both even for HTTPS-only (80 handles ACME challenges and redirects) - Let's Encrypt has rate limits — use staging CA during testing to avoid hitting production limits ## Caddyfile Syntax - Indentation is significant — blocks are defined by indentation, not braces in shorthand - Site blocks need a space before the opening brace: `example.com {` not `example.com{` - Use `caddy fmt --overwrite` to fix formatting — catches most syntax issues - Validate before applying: `caddy validate --config /etc/caddy/Caddyfile` ## Reverse Proxy - Caddy adds `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host` automatically — don't add them manually - WebSocket works out of the box — no special configuration needed - Load balancing is automatic with multiple backends — default is random, use `lb_policy` to change - Passive health checks remove failed backends automatically ## Docker Networking - Use container names as hostnames: `reverse_proxy container_name:3000` - Caddy and backends must share a Docker network — default bridge doesn't support DNS resolution - For Docker Compose, service names work as hostnames when on the same network ## Configuration Management - Use `caddy reload` not restart — reload applies changes without dropping connections - Config changes are atomic — if new config fails validation, old config stays active - Test without applying: `caddy adapt --config Caddyfile` shows parsed JSON output ## Certificate Storage - Certificates stored in `~/.local/share/caddy` by default — preserve this across reinstalls - For Docker, mount volumes for `/data` and `/config` — losing these means re-requesting all certificates - Multiple Caddy instances need shared storage or will fight over certificates ## Debugging - Enable debug logging: add `debug` as first line in global options block - Check certificate status in `/data/caddy/certificates/` directory - Common issue: DNS not pointing to server yet — certificates fail silently until domain resolves ## Security Headers - Caddy doesn't add security headers by default — add X-Frame-Options, X-Content-Type-Options explicitly - HSTS is automatic when serving HTTPS — no manual configuration needed ## Performance - Handles thousands of concurrent connections without tuning - HTTP/3 available with `servers { protocols h1 h2 h3 }` - Compression automatic for text content