[VS-NfD] Define the offline update path including migrations #221

New Issue

fable-5 · 2026-07-30T01:43:51+02:00

fable-5 commented

2026-07-30 01:43:51 +02:00

Plan reference: 20-massnahmenplan.md -> P1-3
ADR: ADR 0024
Effort: M (2–3 AT)
Depends on: #218, #220

Context

An installation that cannot be updated safely will not be updated, and an
unpatched instance in a VS zone is the outcome nobody wants. Migrations are
the risky part.

Current state

Stages apply migrations on api start (MIGRATE_ON_START); there is no
separate migration step and no documented rollback for a failed
migration.
Production deployment pins TAG in the stage .env and pulls
(deploy/stages.md); rollback today means deploying the previous tag.
Constraint to respect: prisma migrate reset is not an available tool
here — migrate deploy is the path.

Acceptance criteria

A documented procedure covers: obtain the update bundle, verify it
(digests), back up, apply, verify health, and roll back.
Migration behaviour is explicit: which migrations are irreversible,
what a rollback means for the database, and when a restore is the
only way back.
Rehearsed once in the isolated environment from #220, including one
deliberate failed-update rollback.
Version skew during the update (api/collab/web) is described:
whether a rolling update is supported or downtime is required.
Documented in the operations manual (#229) and
docs/operations/restore-runbook.md.

Out of scope

Automating updates, and long-term support/backport policy.

**Plan reference:** `20-massnahmenplan.md` -> P1-3 **ADR:** ADR 0024 **Effort:** M (2–3 AT) **Depends on:** #218, #220 ## Context An installation that cannot be updated safely will not be updated, and an unpatched instance in a VS zone is the outcome nobody wants. Migrations are the risky part. ## Current state - Stages apply migrations on api start (`MIGRATE_ON_START`); there is no separate migration step and no documented rollback for a failed migration. - Production deployment pins `TAG` in the stage `.env` and pulls (`deploy/stages.md`); rollback today means deploying the previous tag. - Constraint to respect: `prisma migrate reset` is not an available tool here — `migrate deploy` is the path. ## Acceptance criteria - [ ] A documented procedure covers: obtain the update bundle, verify it (digests), back up, apply, verify health, and roll back. - [ ] Migration behaviour is explicit: which migrations are irreversible, what a rollback means for the database, and when a restore is the only way back. - [ ] Rehearsed once in the isolated environment from #220, including one deliberate failed-update rollback. - [ ] Version skew during the update (api/collab/web) is described: whether a rolling update is supported or downtime is required. - [ ] Documented in the operations manual (#229) and `docs/operations/restore-runbook.md`. ## Out of scope Automating updates, and long-term support/backport policy.

fable-5 added this to the M28 — VS-NfD: offline/airgap deployment milestone 2026-07-30 01:43:51 +02:00

fable-5 added the

effort:M

area:supply-chain

vs-nfd

labels 2026-07-30 01:43:51 +02:00

fable-5 referenced this issue

2026-07-30 01:43:57 +02:00

[VS-NfD] Write the operations manual (installation, update, backup/restore, deletion, role separation) #229

fable-5 referenced this issue from a commit

2026-07-31 17:26:51 +02:00

#221: offline update path incl. migrations, rehearsed with rollback

fable-5 referenced this issue

2026-07-31 17:27:05 +02:00

#221: offline update path incl. migrations, rehearsed with rollback #291

fable-5 referenced this issue

2026-07-31 17:27:42 +02:00

[VS-NfD] Run and document a deployment in a network-isolated environment #220

fable-5 commented

2026-07-31 17:46:31 +02:00

Done via PR #291 (merged, CI run 624 green, CD 625 deployed Test+Int, readyz fully green on both).

All acceptance criteria met:

Documented procedure: docs/operations/update-runbook.md — obtain (airgap: mirror per deploy/stages.md §5b), verify by digest, back up first, apply, verify health, roll back.
Migration behaviour explicit: failed migrations roll back their own transaction but are recorded in _prisma_migrations and block every further migrate deploy (P3009) — including a re-deployed old image — until migrate resolve --rolled-back; successfully applied irreversible migrations mean restoring the pre-update set.
Rehearsed in the isolated environment of #220 including one deliberate failed-update rollback: regular update v1->v2 (pre-update set 20260731-150833), then P3018 division by zero, schema change proven rolled back, image-rollback-alone shown insufficient, documented recovery executed. Evidence: docs/vs-nfd/98-update-rollback-protokoll.md.
Version skew: no rolling updates on a compose stage — all services replace together in a short maintenance window; only the new api applies migrations.
Documented in the operations handbook (docs/vs-nfd/70-betriebshandbuch.md §1/§2, #229) and docs/operations/restore-runbook.md; ADR 0024 decisions 5+6 recorded as executed.

Done via PR #291 (merged, CI run 624 green, CD 625 deployed Test+Int, readyz fully green on both). All acceptance criteria met: - **Documented procedure**: `docs/operations/update-runbook.md` — obtain (airgap: mirror per `deploy/stages.md` §5b), verify by digest, back up first, apply, verify health, roll back. - **Migration behaviour explicit**: failed migrations roll back their own transaction but are recorded in `_prisma_migrations` and block every further `migrate deploy` (P3009) — including a re-deployed old image — until `migrate resolve --rolled-back`; successfully applied irreversible migrations mean restoring the pre-update set. - **Rehearsed in the isolated environment of #220** including one deliberate failed-update rollback: regular update v1->v2 (pre-update set `20260731-150833`), then P3018 `division by zero`, schema change proven rolled back, image-rollback-alone shown insufficient, documented recovery executed. Evidence: `docs/vs-nfd/98-update-rollback-protokoll.md`. - **Version skew**: no rolling updates on a compose stage — all services replace together in a short maintenance window; only the new api applies migrations. - **Documented in** the operations handbook (`docs/vs-nfd/70-betriebshandbuch.md` §1/§2, #229) and `docs/operations/restore-runbook.md`; ADR 0024 decisions 5+6 recorded as executed.

fable-5 closed this issue

2026-07-31 17:46:31 +02:00

Sign in to join this conversation.