railiance-apps/docs/app-data-backup-restore-handoff.md

# App Data Backup And Restore Handoff

This document defines the S5 app release boundary for data durability. It does
not create backup jobs, authorize a live restore drill, or move platform
backup ownership into `railiance-apps`.

## Current App Data

`vergabe-teilnahme` stores relational app data in `vergabe_db` on the shared
CloudNativePG cluster `apps-pg` in the `databases` namespace. The cluster is an
S3 platform service owned by `railiance-platform`; see
`/home/worsch/railiance-platform/docs/apps-pg.md`.

The app currently has no durable media PVC enabled. `persistence.media.enabled`
is `false`, so uploaded media is deferred rather than an S5 durability promise.

## Ownership Matrix

| Concern | S5 app repo owns | Upstream owner |
| --- | --- | --- |
| App database request | App name, namespace, database name, role name, intended use, and production-readiness need | `railiance-platform` reviews and provisions the role/database |
| Runtime DB Secret use | Secret name in the app namespace and URL-encoded DSN rebuild helper | `railiance-platform` owns platform credential source and future secret delivery |
| Database backup job | Readiness gate and consumer evidence requirement | `railiance-platform` owns CNPG backup and restore implementation |
| App restore verification | App-specific post-restore checks, migrations, login/smoke path, and rollback note | `railiance-platform` restores the backing database |
| Forge images/packages | Artifact identity and consumer evidence cited by app runbooks | `railiance-forge` owns registry/package restore evidence |
| App media/blob data | PVC declaration and app-level restore checks if enabled | `railiance-platform` owns storage backup mechanism once media is production-critical |

## Production Readiness Gate

Before an app release treats data as production-critical, the app runbook should
record:

- data class: disposable, externally reproducible, or production-critical;
- owning platform workplan or doc for the backup mechanism;
- latest non-secret backup evidence reference;
- latest restore-drill evidence reference, ideally from an isolated
  environment;
- app-specific post-restore checks, such as migrations, health endpoint,
  login/admin path, and representative business workflow;
- rollback or disable path if restore fails;
- assertion that no secret material was copied into Git, logs, screenshots, or
  State Hub notes.

If this gate is missing, the app can still be used for smoke, development, or
migration validation, but promotion beyond that should create or link a
`railiance-platform` workplan.

## Production cluster inventory (2026-07-10)

Custodian delivery-lane snapshot
(`the-custodian/docs/evidence/vergabe-teilnahme-delivery-lane-20260710.json`)
confirmed all four production CNPG clusters on railiance01 have
`spec.backup=null` and no `ScheduledBackup` resources:

| Cluster | Consumer impact |
| --- | --- |
| `apps-pg` | `vergabe_db` and future S5 app databases |
| `forgejo-db` | Forgejo metadata and package registry state |
| `net-kingdom-pg` | Net Kingdom relational data |
| `state-hub-db` | State Hub API persistence |

Check current posture:

```bash
make cnpg-backup-status
```

Operator-ready barman `ObjectStore` and `ScheduledBackup` templates live in
`manifests/cnpg-backup-readiness.yaml`. Apply only after platform supplies
object-store credentials and retention decisions. Phase 1 platform backup lane
may still use logical `pg_dump` for some clusters; see
`disaster-control/BackupPickupQueue.md` item 6.

## `vergabe-teilnahme` Gate

Current posture (2026-07-12):

- database: `vergabe_db` on `databases/apps-pg`;
- app role Secret: `vergabe-app-credentials`;
- env Secret: `vergabe-teilnahme-env`;
- **Phase 1 backup lane:** `make apps-pg-backup` uploads encrypted logical dumps
  to the platform offsite lane (latest:
  `apps-pg-vergabe_db-20260711T231430Z.dump.age`);
- **CNPG barman posture:** `make cnpg-backup-status` still reports degraded — no
  `ScheduledBackup` on production clusters as of 2026-07-10; Phase 1 logical
  lane satisfies the interim S5 gate per this handoff;
- **restore drill:** isolated restore with row-count gate 195/195 pass
  (`docs/evidence/apps-pg-restore-drill-20260711T230725Z.json`);
- **S5 production-trust gate:** **satisfied for Phase 1** — backup + restore
  evidence recorded in `docs/evidence/apps-pg-backup-lane-20260711.json`;
  app migration smoke on drill DB deferred (row gate sufficient for interim gate).

Evidence index (`RAILIANCE-WP-0013`):

| Check | Evidence |
| --- | --- |
| Backup lane auth + upload | `docs/evidence/apps-pg-backup-lane-20260711.json` |
| Isolated restore drill | `docs/evidence/apps-pg-restore-drill-20260711T230725Z.json` |
| Operator commands | `make apps-pg-backup`, `make apps-pg-restore-drill` |

Remaining before full production-critical promotion (post–Phase 1):

- `vergabe-teilnahme` migration smoke on restored database;
- health endpoint and HTTPS smoke checks after restore;
- representative tender-management workflow verification;
- CNPG `ScheduledBackup` wiring when platform supplies object-store credentials
  (`manifests/cnpg-backup-readiness.yaml`);
- any app media path remains disabled or has its own storage restore evidence.

## Forge Artifact Evidence

S5 runbooks may cite forge-owned package and blob restore evidence, but must not
own Gitea package backup procedures or registry credentials. Use
`/home/worsch/railiance-forge/docs/backup-restore-secret-handoff.md` for the
forge artifact boundary.

For app releases, cite:

- image repository, tag, and digest when available;
- source commit and package version;
- forge publish job or evidence reference;
- package/blob restore drill evidence when the artifact is production-critical;
- namespace-local pull Secret or approved workload secret path, without token
  values.

## Filing Upstream Gaps

When the missing durability item is not local to S5:

1. Keep the S5 task focused on the app release impact.
2. Create or link the platform/forge workplan that owns the missing mechanism.
3. Mark the S5 task `blocked` only when the app release cannot safely continue
   without that upstream evidence.
4. Record the State Hub workstream/task id in the app runbook or workplan.
5. Revisit the S5 promotion gate after upstream evidence exists.