Protect configuration and recovery state

Two assets decide whether a bad day is a blip or a disaster. Control of the running configuration, and the state Caddy needs to come back after a loss. Let’s look at both.

The admin API

Caddy is controlled at runtime through its admin API, listening on localhost:2019. Every caddy reload you’ve run in this course used it. You can read the live configuration directly:

curl http://localhost:2019/config/ | jq .

That JSON is the actual running configuration. It’s the truth, even if someone edited the Caddyfile without reloading. When the file and the behavior disagree, this is what settles it.

The API also accepts POST and PATCH requests that change configuration on the fly. That’s why it must stay private. Whoever reaches this endpoint owns the server. They can reroute your traffic anywhere, or add a site of their own.

The default localhost binding is correct. Leave it alone. If you ever need remote administration, tunnel over SSH instead of exposing the port.

Caddy’s storage

The second asset is Caddy’s storage: the data directory holding certificates, private keys, and the ACME account. Lose it and Caddy re-issues everything from scratch. Slow at best, rate-limited at worst.

Back it up with the built-in command:

caddy storage export --output caddy-storage.tar

storage export produces a tar archive of the whole storage. Treat it like a private key, because it contains your private keys. Encrypt it, store it apart from your configuration backups, and never commit it to a repository.

Restore is the mirror image:

caddy storage import --input caddy-storage.tar

Run the drill once

A backup you haven’t restored is a guess. Run the drill in a throwaway VM or container, before you need it.

Install Caddy. Restore the Caddyfile from version control. Import the storage. Start the service. Confirm the site comes up over HTTPS.

Then check the runtime log. No new certificate issuance means the restored state worked: Caddy found its certificates and used them. If you see it requesting new ones, the import didn’t land where Caddy looks, and now is the time to find out why.

Your recovery kit

Your full recovery kit is three things:

• the Caddyfile, in version control
• the storage export, somewhere encrypted
• the notes from lesson one about your binary version and modules

With those, a dead server is an hour of calm work. Without them, it’s a scramble against expiring certificates and a binary you can’t reproduce.

My advice is to write the restore steps in a short file next to the Caddyfile and to run through them once a year. Ten minutes of practice beats reading the docs at 3am.