1 Backup Restore Export
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

Backup, Restore, and Export

Fidelity backup unit

A v1 fidelity backup is all of the following captured consistently:

  • PostgreSQL dump of the Memories database.
  • library/stored-objects/ containing immutable original bytes.
  • Restore-relevant configuration and secrets, including app version, database name/user, library path, public URL, app secret, worker token secret, and timezone.
  • If reverse place lookup is enabled or any place lookup provider/cache data has been imported, a PostgreSQL target with the PostGIS extension available.

Take the backup with Maintenance Mode enabled or with all write-capable services stopped.

Included and excluded library paths

  • Required: stored-objects/
  • Optional cache: derived/
  • Excluded: upload-staging/
  • Excluded unless debugging: worker-artifacts/
  • Optional exit artifacts: exports/

Originals are authoritative bytes. Derived assets are cache and should be regenerable.

Inspectable export

The Backup/Export UI can create library/exports/<export-id>/manifest.json and metadata.json. This export is for inspection and exit, not v1 fidelity restore. The manifest intentionally reports restoreSupported: false.

Export generation is currently Core API-owned and synchronous. It records an export_jobs row, writes metadata.json, writes a manifest with checksums, and marks the job completed. Worker-assisted or chunked export generation remains deferred until the Core-owned export contract needs to scale.

The Admin operator dashboard exposes maintenance-mode state, recent export jobs, and a fidelity-backup reminder. It is visibility only; taking the actual PostgreSQL dump and copying stored-objects/ remain operator actions outside the Core API.

Restore validation

After restoring, validate:

  • Database migrations are current.
  • PostGIS is installed and available before claiming reverse place lookup fidelity. Validate with SELECT postgis_full_version(); on the restored Memories database.
  • stored-objects/ exists and hash/size integrity checks pass.
  • Media item IDs, owner IDs, album membership, sharing state, trash state, and worker jobs are preserved.
  • Processing issues and failed/queued worker jobs are preserved well enough for operator inspection and recovery.
  • Derived assets are either present or can be regenerated.
  • Imported local gazetteer rows, cached place labels, provider attribution, and generated-title provenance are preserved when reverse place lookup has been used. JSON/JSONL export remains inspectable, but it is not the v1 restore source for PostGIS-backed provider/cache tables.