diff --git a/docs/ops/rite-calendar-migration-runbook.md b/docs/ops/rite-calendar-migration-runbook.md index 45e8ab066..e98d00f4c 100644 --- a/docs/ops/rite-calendar-migration-runbook.md +++ b/docs/ops/rite-calendar-migration-runbook.md @@ -90,6 +90,39 @@ itself is left in the model unchanged — it is only removed at the prune milest the latest authorization model already in that store (it does not create or upload one), and — with `--update-env` — writes the resulting `OPENFGA_STORE_ID` and `OPENFGA_MODEL_ID` into the `.env.*` file(s) and Docker Compose `.env` files in this repo and its siblings. + + **That command is for a checkout, not for the deployed vhost, and running it in the wrong place + re-pins the wrong store.** The deployed API's pin against the PRODUCTION store lives in exactly + one file — `api/dev/.env.staging` on the VPS, the only `.env*` that deployment has, so there is + no Dotenv precedence to reason about. `api/v4` and `api/v5` carry no `OPENFGA_*` keys at all. + Run from a local checkout the command above resolves whatever store that checkout points at + (a local dev store, not production) and writes those values, so edit the one VPS file instead. + + Edit it as its owner, and never point a shell redirect at the live file: a redirect truncates + its destination BEFORE the command on its left runs, so `sed ... > .env.staging` or + `cat tmp > .env.staging` leaves the file EMPTY if that command then fails. A zero-byte + `.env.staging` takes the API down immediately, since phpdotenv reads it per request (observed + 2026-09-01). + + Write a temp copy in the SAME directory instead, validate it, and `mv` it into place. `cp -p` + seeds the temp with the live file's owner, group and mode, so the replacement keeps them; the + redirect then truncates only that temp; and `mv` within one directory is an atomic rename, so + no in-flight request can read a half-written file. Build the temp as the same user that + performs the write — a `mktemp` file made by `ubuntu` is mode 600 and unreadable to the user + performing the write. + + ```bash + sudo -u bash -c 'cd \ + && cp -p .env.staging .env.staging.bak.