Caddy guide
What Caddy does in production
Caddy terminates HTTP and HTTPS, serves static files, and reverse-proxies to
app servers — similar to nginx or Apache, but with automatic certificate
management built in. Configuration is usually a Caddyfile at
/etc/caddy/Caddyfile. Caddy reloads config without dropping
connections when you run caddy reload or
systemctl reload caddy.
How a request is handled
When a client connects, the typical workflow is:
- TCP accept — Caddy listens on configured addresses (default :80 and :443)
- TLS handshake — for HTTPS, Caddy selects a certificate by SNI hostname
- Site block match — the request hostname maps to a
site blockin the Caddyfile - Directive chain — matchers and handlers run in order (
route,handle,reverse_proxy,file_server) - Upstream or file — request is proxied to a backend or served from disk
- Response — logged via Caddy's structured logging (access logs configurable per site)
Caddyfile basics
A site block starts with the hostname (or :port) followed by a
braced block of directives:
example.com {
reverse_proxy 127.0.0.1:8080
}
www.example.com {
redir https://example.com{uri}
}
The first line is the address Caddy binds to and matches. Multiple site blocks can coexist in one file; more specific blocks should be defined before catch-alls.
Automatic HTTPS
When a site block uses a public hostname (not localhost or a raw IP), Caddy automatically provisions TLS certificates from Let's Encrypt via ACME. Requirements: DNS must resolve to the server, ports 80 and 443 must be reachable from the internet (or use DNS challenge), and the system clock must be accurate.
Key directives to know
reverse_proxy— forward requests to upstream(s); supports load balancing and health checksfile_server— serve static files fromrootroot— document root for file servingredir— HTTP redirectshandle/route— path-based routing within a sitetls— override automatic TLS (custom certs, internal CA, disable HTTPS)encode— compression (gzip, zstd)
Configuration and validation
Always validate before reload — a bad Caddyfile can prevent startup:
caddy validate --config /etc/caddy/Caddyfile. Format for
consistency: caddy fmt --overwrite /etc/caddy/Caddyfile.
Check service status with systemctl status caddy and logs with
journalctl -u caddy.
Learning resources
- Caddy documentation — caddyserver.com/docs (official reference)
- Caddyfile tutorial — caddyserver.com/docs/caddyfile (syntax and structure)
- reverse_proxy — caddyserver.com/docs/caddyfile/directives/reverse_proxy (upstream configuration)
- Automatic HTTPS — caddyserver.com/docs/automatic-https (how ACME provisioning works)
Practice scenarios
Hands-on Caddy scenarios on live Linux VMs: caddy