docs(deploy): caddy conf bind mounts are inode-pinned — recreate, not reload

Document the gotcha hit fixing distribution CORS: caddy/conf.d/*.caddy are
single-file bind mounts pinned to the host inode at container creation. git pull
rewrites tracked files via atomic rename (new inode), so a running caddy keeps
the old config; `restart`/`caddy reload` reuse the stale inode. Apply conf
changes with `docker compose up -d --force-recreate caddy` (or the --hard
down/up). Added to plan/14-deploy.md and the deploy skill guardrails.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 02:26:42 +02:00
parent db63aa7d10
commit 8a71709048
2 changed files with 20 additions and 1 deletions

View File

@@ -73,6 +73,14 @@ invoking this skill is the authorization to proceed, but:
- Never `git reset --hard` or discard changes on `cochi` without telling the user
first — there may be host-local edits.
- **Caddy conf changes need a recreate, not reload/restart.** If the deploy
touched any `caddy/conf.d/*.caddy` or the Caddyfile and you did a *rolling*
`update-all.sh` (not `--hard`), the change WON'T apply: those are single-file
bind mounts pinned to the host inode, and `git pull` gives the file a new inode.
`restart`/`caddy reload` reuse the stale inode. Run
`docker compose up -d --force-recreate caddy`, then verify with
`docker compose exec caddy cat /etc/caddy/conf.d/<file>`. The `--hard` path
(full `down`/`up`) already recreates, so it's unaffected.
- Volumes (`mc_data`, `drasl_state`, `kuma_data`) persist across `down`; the
world and monitors are safe. Do NOT pass `-v`/`--volumes` to `down`.
- If a step fails, STOP and surface the exact error + the failing command. Do not