Config volume for Docker

In the recommended Caddy configuration for Docker

It suggests doing:

caddy_config:/config

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.

What is the advantage I’m missing?

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.

As I don’t personally use the API myself (I usually keep my configuration inline with Docker inline configs or lucaslorentz/caddy-docker-proxy), I never persist this volume.

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.

2 Likes

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.

3 Likes

Yeah, I figured this would be the case. Really no need to throw that part out until you know the new config is good so it’d be a bit weird if it did.

1 Like

Thanks for the answers, now makes sense.

Maybe this API thing could be commented on the documentation page just to have everything in place.

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.