Docs: deploy gotchas and post-upgrade runbook
1 changed file +17 −0
modified
docs/DEPLOY.md
+17 −0
@@ -264,3 +264,20 @@ ssh BHS64 tunnelctl status # routes + WireGuard peers | ||
| 264 | 264 | |
| 265 | 265 | Local validation without servers: `docker compose -f deploy/compose.data.yml --env-file deploy/.env.data.example config -q` |
| 266 | 266 | and `docker build -f deploy/docker/Dockerfile.worker .` from the repo root. |
| 267 | + | |
| 268 | +## 2026-09-12 upgrade — post-deploy data repair and gotchas | |
| 269 | + | |
| 270 | +- Deploy order when the API contract changes: the web image prerenders `/` and other static routes against the **live** API | |
| 271 | + (`NEXT_PUBLIC_API_URL` build arg). Either keep pages tolerant of missing fields (done for the home page) or build/up | |
| 272 | + `api scheduler worker-maint` first, then `web` (see `/tmp/dci-redeploy.sh` pattern: `compose build api …`, `run --rm migrate`, | |
| 273 | + `up -d api …`, then `compose build web`, `up -d web edge`). | |
| 274 | +- `deploy/rsync-exclude.txt` and `.dockerignore` must exclude only the root `coverage/` report directory (`/coverage`): a bare | |
| 275 | + `coverage` pattern silently dropped the `/coverage` web route from the image. | |
| 276 | +- `compose run --rm cli <cmd>` passes `<cmd>` as the entrypoint ROLE — run `dci` commands as `run --rm -T cli cli <cmd>`. | |
| 277 | +- `scripts/` is not baked into the worker image; run repair scripts with bind mounts: | |
| 278 | + `run --rm -T -v /srv/dci/app/scripts:/app/scripts -v /srv/dci/app/packages/core/src:/app/packages/core/src cli node /app/node_modules/tsx/dist/cli.mjs /app/scripts/quality-apply.ts …`. | |
| 279 | +- `deploy/bin/post-upgrade.sh [baseline|repair|reprocess|unbacked|refresh|audit]` runs the whole repair sequence from the laptop: | |
| 280 | + quality sweep + snapshot, hide vetoed / unconfirmed projects, fix slugs, link campuses, `dci reprocess <id> --stale` for every | |
| 281 | + connector (offline, archived bodies), null figures no site-scoped claim backs, refresh stats + rankings, print the largest values. | |
| 282 | +- API/edge health probes use `/api/ready` (Postgres-aware). `DCI_WORKER_URL=http://worker-maint:8320` lets the API proxy the | |
| 283 | + extraction debugger (`/api/admin/documents/:id/trace`) and `/api/admin/data-gaps`. | |
| 267 | 284 | |