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:

- database: `vergabe_db` on `databases/apps-pg`;
- app role Secret: `vergabe-app-credentials`;
- env Secret: `vergabe-teilnahme-env`;
- current backup status: no CNPG `ScheduledBackup` on `apps-pg` as of
  2026-07-10; `make cnpg-backup-status` reports degraded until platform or
  operator wiring completes;
- restore status: no app-level restore drill evidence is recorded in this repo.

Minimum evidence before production-trust use:

- platform confirms `apps-pg` backup coverage for `vergabe_db`;
- an isolated restore drill proves the database can be restored;
- `vergabe-teilnahme` runs migrations successfully after restore;
- health endpoint and HTTPS smoke checks pass;
- operator verifies the app can complete a representative tender-management
  workflow after restore;
- 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.