What's missing
There is no operate/upgrading page, and it can't be written yet. Every other planned reference page can be derived from the code; this one can't, because the behaviour it would describe hasn't been decided.
Why it's blocked rather than just unwritten
A reconnaissance pass over the gateway found no upgrade procedure anywhere in the shipped tree — not in README.md, docs/SETUP.md, docs/README.md, CONTRIBUTING.md, or docs/runbooks/. That means every sentence on an upgrade page would be invented rather than transcribed, which is the one thing this project's documentation rules forbid.
What the code does tell us:
- Migrations run automatically at boot and each is individually transactional, but a multi-migration upgrade that fails partway leaves the schema at an intermediate version. There is no down-migration path.
POSTERN_VERSION defaults to latest. It is documented only in a comment inside docker-compose.yml — it has no entry in .env.example, which claims to document every variable.- No git tags exist in the tree, so there is no version a user can pin to by name.
Decisions needed before this page can be drafted
- Is
:latest a supported channel, or should users pin a version? If pinning, what is the tag scheme and where is it published?
- Rollback policy. The schema cannot be reversed by code. Is the supported answer "restore from backup", or is rollback simply unsupported? Both are legitimate; the page has to say one of them plainly.
- Backup before upgrade — recommended, or required?
docs/runbooks/backup-restore.md already documents the procedure; this only decides how the upgrade page points at it.
- Postgres major-version upgrades. The image is pinned to
postgres:16. Moving off it is not a docker compose pull — it needs a dump-and-restore. Is that in scope for this page or its own runbook?
- Downtime expectations. How long is the gateway unavailable during a migrating boot, and what should a user expect to see while it happens?
Suggested shape once those are answered
Prerequisites (backup) → pull → recreate → verify (/healthz plus a Console check) → what to do if a migration fails. Roughly 2–3 hours of writing once the five answers exist.
Related
.env.example and docker-compose.yml disagree about which variables are honoured — POSTGRES_HOST_PORT and DOZZLE_HOST_PORT are documented in the former but absent from the latter. Worth reconciling while this area is open, since a configuration page will hit the same contradiction.
What's missing
There is no
operate/upgradingpage, and it can't be written yet. Every other planned reference page can be derived from the code; this one can't, because the behaviour it would describe hasn't been decided.Why it's blocked rather than just unwritten
A reconnaissance pass over the gateway found no upgrade procedure anywhere in the shipped tree — not in
README.md,docs/SETUP.md,docs/README.md,CONTRIBUTING.md, ordocs/runbooks/. That means every sentence on an upgrade page would be invented rather than transcribed, which is the one thing this project's documentation rules forbid.What the code does tell us:
POSTERN_VERSIONdefaults tolatest. It is documented only in a comment insidedocker-compose.yml— it has no entry in.env.example, which claims to document every variable.Decisions needed before this page can be drafted
:latesta supported channel, or should users pin a version? If pinning, what is the tag scheme and where is it published?docs/runbooks/backup-restore.mdalready documents the procedure; this only decides how the upgrade page points at it.postgres:16. Moving off it is not adocker compose pull— it needs a dump-and-restore. Is that in scope for this page or its own runbook?Suggested shape once those are answered
Prerequisites (backup) → pull → recreate → verify (
/healthzplus a Console check) → what to do if a migration fails. Roughly 2–3 hours of writing once the five answers exist.Related
.env.exampleanddocker-compose.ymldisagree about which variables are honoured —POSTGRES_HOST_PORTandDOZZLE_HOST_PORTare documented in the former but absent from the latter. Worth reconciling while this area is open, since a configuration page will hit the same contradiction.