The Caddyfile is not Caddy's native configuration format. What is, how does the Caddyfile relate to it, and how does a running Caddy instance receive a new configuration?

## Two layers, and why the distinction matters Most web servers have exactly one configuration language, and it is the one you write. Caddy has two: 1. **JSON is the native config.** It is a structured document — an `apps` object containing, for HTTP, servers with listen addresses, routes, matchers and handlers. Every knob Caddy has is reachable there, because it is what the modules are actually configured from. 2. **The Caddyfile is an adapter's input.** A *config adapter* is a module that turns some other format into that JSON. The Caddyfile adapter is the default and by far the most used, but it is one of several, and it is not privileged in the runtime. The practical consequence is that the Caddyfile is deliberately lossy in the direction of brevity: it makes the common cases short by expanding one directive into several JSON constructs. `reverse_proxy` alone produces a route, a matcher, a handler and an upstream list. ## Seeing the conversion ```bash caddy adapt --config Caddyfile --pretty ``` This is the debugging move that separates people who use Caddy from people who have operated it. When a Caddyfile does something surprising — a matcher wider than you meant, directives ordered differently than written, a site block that swallowed a path — the adapted JSON shows the actual structure rather than your intent. Two companion commands live in the same family: `caddy validate` loads a config to check it without serving, and `caddy fmt` normalises Caddyfile whitespace. ## The admin API is the real control plane A running Caddy binds an administration endpoint, by default `localhost:2019`. It speaks a small REST-shaped API over the config document: - `POST /load` replaces the entire configuration. - `GET /config/...` reads the live config, or any subtree of it. - `POST`, `PUT`, `PATCH` and `DELETE` under `/config/...` mutate a subtree in place. - Objects can carry an `@id` field, which makes them addressable under `/id/...` so automation can target one upstream or one route without knowing its index. `caddy reload --config Caddyfile` is not a signal to the process. It runs the adapter and posts the resulting JSON to `/load` on the admin endpoint. That is why reloading a Caddy you started some other way still works, and why disabling the admin endpoint takes `caddy reload` away with it. ## What "graceful" means here On a config change Caddy provisions the new configuration, starts what it needs, and swaps over; listeners that are unchanged are kept rather than rebound, and connections being served under the old config are not severed. There is no process restart, so no dropped listeners and no cold start. If the new config fails to provision, the load fails and the old config keeps running — a broken config is a rejected API call, not an outage. ```bash curl -s localhost:2019/config/ | head curl -X POST localhost:2019/load \ -H 'Content-Type: application/json' \ -d @caddy.json ``` ## The security posture you must state The admin API is **unauthenticated by default**. Its protection is that it binds the loopback interface. Anything that can reach it can replace your entire server configuration — including where traffic is proxied to and what certificates are served. So: - never bind it to a routable address casually; if you must, put authenticated transport in front of it and treat it as a privileged control plane; - remember that in a container, "localhost" is the container's own loopback, so publishing port 2019 is the mistake to avoid; - `admin off` in the global options disables it entirely, which is a defensible hardening choice for an immutable-image deployment — at the cost of losing `caddy reload` and live introspection. ## When you would write JSON directly Hand-writing JSON for a small site would be perverse. But it is the right layer when a control plane generates config programmatically, when you need something the Caddyfile adapter does not express, or when automation should patch one field rather than regenerate a whole file. Caddy also autosaves the last loaded config so a restart can resume it — in the container image that lives on the `/config` volume, which is why that path exists separately from the certificate store on `/data`. ## The framing an interviewer wants The Caddyfile's brevity is real, and it is the product's selling point. What makes it operationally sound rather than merely cute is that there is a fully expressive layer underneath it and a live API on top of it, so you can inspect precisely what your short config became and change it without a restart.