Backups and restore

Recover the complete data boundary

Backups and restore covers encrypted project-database backups plus complete packaged-host recovery archives, integrity checks, retention, and explicit restore.

Copying a live SQLite file or keeping only PostgreSQL does not recover complete FFDB application state.

Use it before production launch, before upgrades, and during scheduled restore exercises or incidents.

Requirements for Backups and restore

• Prerequisite — A configured independent backup root and backup master key.
• Prerequisite — Separate PostgreSQL, object-storage, and organization-metrics backup/replication plans.
• Required value — Exact organization/project, backup ID, integrity result, encryption key custody, retention, and recovery objectives.
• Required value — A quiescence plan, destination route for project restore, and coordinated PostgreSQL/metrics-ledger recovery point.

Encrypted artifacts

Backups are encrypted before becoming durable. A backup file begins with the FFDB backup envelope rather than a SQLite header. Store the base64-encoded backup master key separately from backup files.

ffdb backup create
ffdb backup list
ffdb backup integrity
ffdb backup restore "$FFDB_BACKUP_ID" --yes

Complete single-host recovery archive

The packaged single-host controller creates a complete, coordinated recovery point directly from the installed host. It quiesces mutation-serving services, logically dumps PostgreSQL, archives project, metrics, encrypted-backup, sync, MinIO, and Mailpit volumes plus root-only configuration, writes a versioned manifest and SHA-256 checksums, publishes at mode 0600, and resumes the stack even when create fails. It never overwrites an archive.

sudo ffdb-host backup create /secure/ffdb-host-2026-08-03.tar.gz

# Restore requires the exact FFDB version, a stopped host, and explicit confirmation.
sudo ffdb-host stop
sudo ffdb-host backup restore /secure/ffdb-host-2026-08-03.tar.gz --yes

Validation before destructive restore

Restore refuses a running host and validates the complete archive before replacing anything: safe paths and regular file types, exact profile/version, all checksums with no unverified files, archived Compose configuration, PostgreSQL dump readability, and SQLite quick_check for every project and organization ledger. It restores PostgreSQL transactionally, rechecks restored SQLite volumes, restores ownership, starts the full stack, and requires compiled-gateway readiness.

• Native systemd installs ffdb-backup and uses the same create/restore syntax; stop ffdb-api and ffdb-sync-worker before restore.
• Native archives include local state, PostgreSQL, configuration, and object metadata; external S3 object bytes still require a provider backup at the same recovery point.
• The external-provider Compose profile fails closed because FFDB cannot atomically copy operator-owned PostgreSQL and S3 providers.

sudo ffdb-backup create /secure/ffdb-native-2026-08-03.tar.gz
sudo systemctl stop ffdb-sync-worker.service ffdb-api.service
sudo ffdb-backup restore /secure/ffdb-native-2026-08-03.tar.gz --yes

Preserve the organization billing ledger

Project backup artifacts alone do not contain the per-organization usage ledger below FFDB_METRICS_ROOT. The complete host workflow captures it at a coordinated recovery point with PostgreSQL billing state. For an external-provider deployment, quiesce the API, snapshot both sides, encrypt and replicate them off host, and test the pair together. A project restore must not roll the metrics ledger backward because later successful operations remain billable history.

• Packaged Compose uses the metrics-data named volume mounted at /var/lib/ffdb/metrics.
• Native systemd uses /var/lib/ffdb/metrics with mode 0700 and grants write access only to ffdb-api.
• After disaster recovery, validate each organization database with SQLite quick_check and reconcile reads, writes, storage byte-hours, and MAU before reopening billable writes.

Backups and restore workflow

• 1. Create a project backup through the trusted operation.
• 2. For complete host recovery, run ffdb-host backup create on packaged single-host or ffdb-backup create on native systemd.
• 3. Encrypt and replicate the resulting mode-0600 archive off host.
• 4. Run integrity checks and isolated restore drills on schedule.
• 5. Stop mutation services before restore and pass --yes only after resolving the exact versioned archive.
• 6. Verify schema, RLS, storage metadata, sync behavior, usage summaries, reporting reconciliation, and both API and gateway readiness.

Verify backups and restore

A documented restore recreates the intended project database without exposing durable plaintext.

Troubleshoot backups and restore

• Integrity fails — quarantine the artifact and select a known-good backup.
• The backup key is unavailable — restore is impossible; fix key escrow before production.

Continue from Backups and restore

• Record restore evidence against recovery objectives.
• Review key rotation and incident response.