From what I can read, this is simply a JSON-format of the /etc/caddy/ we are already passing in another mount point.
Here it says it’s important to be persistent, but reading the logs I see that it’s created everytime a new docker container is mounted. It’s not like data directory which happens to store the super critical letsencrypt certs, that should not be regenerated every run.
But in this case, the config file is regenerated every run, so I can’t find any advantages to persisting it.
It’s very important for API users. These users typically make many small changes over time to sometimes very large and complicated Caddy configuration. They want this configured state to persist between restarts and upgrades - if they wanted Caddy to load a whole new config, they would post a whole new config.
Off the top of my head I’m not sure if it’s used as fallback config if you try to hot reload a bad Caddyfile. It might not be necessary for that but even if it is, it’s “persistent enough” for my needs just inside the container without a volume; it’ll stay put until the container is destroyed and recreated anyway.
The caddy_data:/data volume is obviously quite critical to all users by comparison.
It’s a little ambiguous what you mean here, but just to be clear, yes I expect the JSON to be recreated each time Caddy successfully loads a new config (such as reading in a Caddyfile at startup). But the volume itself definitely shouldn’t be getting created every time you create a container. Docker Compose should definitely be ensuring the volume persists, even through docker compose down.
It’s not read at all, unless you use the --resume flag when starting Caddy.
But using that is fundamentally incompatible with the idea of using a Caddyfile, so it’s not recommended. The --resume option only makes sense if you’re actually using Caddy’s API directly to make config changes (not using a config file, except for maybe initial startup).
If you use a Caddyfile, then yeah persisting /config is not necessary. But we document it anyway just in case someone does want to use the API, so they don’t shoot themselves in the foot and “lose data” (i.e. their ephemeral in-memory config changes).
If you try to push a bad Caddyfile, the already-existing config that’s loaded in memory remains. Remember that when a config reload happens, two configs are loaded at the same time for a short moment, the new config is provisioned and started, and if successful, then and only then the old config is torn down and thrown away. If the new config fails to load without error, then the new one is thrown away and the old one remains as-is.