Three Caddy notes I keep re-learning

2026-06-30

1. fmt and validate before every restart

Half of my "Caddy is broken" moments were a missing brace or a stray comma. The habit that fixed it:

caddy fmt --overwrite /etc/caddy/Caddyfile
caddy validate --config /etc/caddy/Caddyfile
systemctl restart caddy

fmt is not cosmetic here: when it re-indents a block strangely, that block is usually missing a brace.

2. Certificate renewal is port 80 plus DNS

Every renewal failure I have actually had was one of three things: port 80/tcp unreachable in the firewall, DNS pointing somewhere else, or the domain expired. Ten seconds to tell which:

journalctl -u caddy --no-pager | grep -i renew

The certificate plumbing itself has never once been the problem.

3. file_server can serve pre-compressed files

file_server {
    precompressed zstd br gzip
}

If index.html.zst (or .br, .gz) sits next to index.html, Caddy sends the best variant the client supports as-is — no per-request compression work. One real footgun: the sibling is served as long as it exists. Edit the HTML and forget to regenerate the compressed copies, and visitors happily receive the stale version. My fix is a two-line script that rebuilds them; it runs as part of "I edited the site", same as the reload.