Backup And Restore
Protect and restore PostgreSQL, object storage, Keycloak, environment configuration, and generated artifacts.
Backup And Restore
Backups are an operations responsibility. The repository provides the data layout and runtime services, but the final backup tooling depends on the target host or Kubernetes platform.
What To Back Up
| Asset | Why it matters |
|---|---|
| PostgreSQL application database | Tenants, organizations, users, proofs, certificates, jobs, DLQ, audit, receipts, licenses, idempotency, verification logs. |
| Keycloak database/config | Realms, clients, users, roles, federation, credentials metadata. |
| Object storage buckets | Raw .der proofs, PDFs, canonical JSON, binaries, exports, monthly reports. |
| Environment and secrets | Runtime config, DB/S3/SMTP/Keycloak credentials, signer mTLS material, frontend session secret. |
| Signer key custody records | Production signer owns cryptographic keys; back up according to signer/HSM policy, not application DB policy. |
| Nginx/TLS config | Public routing, certificates, redirects, callback behavior. |
| Generated release artifacts | Image tags/digests, SBOM/provenance, Swagger/client versions. |
Do not place API key raw secrets, JWTs, signer private keys, or production license signing material in application backups.
PostgreSQL Backup
For the local compose database:
docker compose exec postgres pg_dump -U wipe -d wipe -Fc -f /tmp/wipe.dump
docker compose cp postgres:/tmp/wipe.dump ./wipe.dump
For production, use managed snapshots or pg_dump/WAL archiving according to
the RPO/RTO target. The cahier target is RPO <= 15 minutes and RTO <= 4 hours.
Object Storage Backup
Back up all configured buckets:
| Bucket | Contents |
|---|---|
S3_BUCKET_PROOFS | Submitted .der proof payloads. |
S3_BUCKET_CERTIFICATES | Certificate PDFs and canonical JSON. |
S3_BUCKET_BINARIES | Agent binaries or static download metadata targets. |
S3_BUCKET_EXPORTS | Billing exports and monthly reports. |
S3_BUCKET_BILLING_DROP | Optional write-only billing delivery target. |
Keep bucket versioning and retention policy aligned with legal and contractual requirements. WORM/Object Lock is not active in this repository, so enforce any immutability at the storage provider only after product approval.
Restore Order
- Restore PostgreSQL and run migrations to the expected application version.
- Restore object storage buckets and verify object keys referenced by database rows.
- Restore Keycloak realms/clients/users or connect to the managed Keycloak backup.
- Restore environment secrets and frontend session secret.
- Start API first, then workers.
- Verify
/readyz, login, proof list, certificate PDF download, canonical JSON download, billing report download, and/verify. - Resume workers and inspect DLQ before replay.
Consistency Checks After Restore
| Check | Expected result |
|---|---|
| Proof object keys | Every recent proof row has a readable object in the proofs bucket. |
| Certificate artifacts | PDF and canonical JSON keys resolve for sampled certificates. |
| Consumption receipts | Sequence continuity and hash-chain verification pass. |
| Audit log | Maintenance worker reports no unexpected chain breaks. |
| Idempotency keys | Recent in-progress keys are resolved or expired before replaying writes. |
| Queue state | Jobs/DLQ are reviewed before workers are scaled up. |
Restore Drill Cadence
Run restore drills before production launch and after any change to database schema, object storage policy, Keycloak realm structure, signer integration, or release pipeline. Keep drill evidence with the operations log.