Docker/self-host: backup volume name, atomic site-build, tag-after-gates in docker.yml, guide and compose fixes #166

Findings from the adversarial review of the 0.6.3 Docker image, compose stack, self-host guide and docker.yml (#143, #148). The CLI/API side (setup token, Better Auth origins, --no-auth, rate-limit IP) is #165.

High

1. The documented backup archives an empty volume. docs/guides/self-host.md:88 runs docker run --rm -v cloudhal-data:/data … tar czf …, but deploy/docker/compose.yml:46-47 declares volumes: cloudhal-data: without name:, so the stack's volume is <project>_cloudhal-data (cloudhal_cloudhal-data after the quick start's mkdir cloudhal). docker run -v auto-creates an empty cloudhal-data, tar archives nothing, exit 0; the restore lands in a volume the stack never mounts. This is the guide's only pre-upgrade rollback path. Fix: name: cloudhal-data on the volume (and say so), or make the backup command use docker compose run/$(docker compose ... ).

Medium

2. site-build empties /data/dist before rendering (deploy/docker/bin/site-build:13): the Caddy-served site is a bare 404 for the length of each build, and the guide's 15-minute cron makes that recurring; a failed build leaves the site empty. Build into /data/dist.next, then swap atomically (rename), keep the previous output on failure.
3. Release tags are pushed and attested before the smoke test and Trivy (.github/workflows/docker.yml:111): a failing gate leaves a broken latest/X.Y live. Also latest is skipped for a release started via Actions › Release › Run workflow, and a dispatch backfill of an older patch moves X.Y backwards (docker.yml:93-94). Fix: build and push by digest (or sha- tag) first, smoke + Trivy against that digest, then add the version tags with docker buildx imagetools create; compute latest/X.Y from the highest released version, not from the event.

Low (docs and compose riders)

4. BETTER_AUTH_SECRET from .env never reaches the container: compose.yml:14 does not pass it, while the guide (self-host.md:62) tells operators to set it.
5. Guide (self-host.md:21) and .env.example say invites and reset links are printed to the logs; the container prints nothing unless cloudhal.json has mail — document the mail setting or make the terminal sender the default when no mail transport is configured.
6. compose.yml:38: :? interpolation in the inactive caddy profile fails docker compose up unless both Caddy variables are set; use :- with a comment, or move the check into the Caddy entrypoint.
7. .env.example:1 says "No secrets live here" while asking for the Workers AI token; the guide says it is "never stored". Say what is a secret and point at Docker secrets / an env file outside the repo.
8. .env.example:9: changing CLOUDHAL_PORT without CLOUDHAL_BASE_URL leaves Studio loading but sign-up/sign-in failing with 403 (Better Auth origin). Couple the two in the comments, and after Self-host: auth hardening after the 0.6.3 review (setup token, Better Auth origins, --no-auth guard, rate-limit IP) #165 lands, say CLOUDHAL_BASE_URL is required for any non-localhost origin.
9. self-host.md:68: nothing says how the static build learns the public site origin, so canonical links, sitemap and feeds say localhost. Document CLOUDHAL_SITE_URL/the site's baseUrl (whichever the build reads) and pass it in site-build.
10. Dockerfile:6: the build example names 0.6.2, whose CLI rejects the entrypoint's --init-if-empty; use 0.6.3/latest or a placeholder.
11. Critic gaps worth a line each: site-build before the first publish builds the latest or a live snapshot (drafts) — until RFC-0043 PR 2's --published mode, the guide must not claim "published only"; the Caddyfile's handle_errors → /404.html is dead for the default starter (no /404 page) and _headers is ignored by Caddy (add header /media/* Cache-Control …); the guide's "previews are visible" claim is wrong on Node (no ApiDeps.preview).
12. Smoke coverage (scripts/docker-smoke.ts): add GET / → Studio index.html, POST /mcp → 401, and an arm64 run under QEMU before tags move.

Done when

• Items 1–3 fixed with the workflow verified by a dispatch run against an existing version (re-tag only, no new release).
• Guide, .env.example, compose and Dockerfile updated for 4–11; smoke test extended for 12.
• pnpm check green (docker-smoke needs Docker; run it locally once).

Source: adversarial review run after the 0.6.3 release (178 agents, 47 confirmed findings).