1 Backup And Restore
Forgejo Actions edited this page 2026-09-25 17:00:22 +00:00

Backup and Restore

A fidelity backup captures three things: a consistent PostgreSQL dump, the library/stored-objects/ directory, and the restore-relevant configuration and secrets (app version, database name and user, library path, public URL, app secret, worker token secret, and timezone).

If reverse place lookup or gazetteer data has been used, the restore target also needs PostGIS. Take backups with Maintenance Mode enabled, or with all write-capable services stopped.

What is in and out:

  • derived/ is optional to back up — it is a regenerable cache.
  • upload-staging/ and worker-artifacts/ are excluded.
  • exports/ is optional.
  • The JSON/JSONL export is inspect-only (restoreSupported: false) and is not a v1 restore source; in particular it does not restore PostGIS-backed provider or cache tables.

There is no automated scheduled backup and no restore UI in v1. The pg_dump and object copy remain operator actions outside the Core API.

Restore runbook: stop the stack, restore the database dump, copy stored-objects/ back, restore .env, start the stack, then verify. Verification includes migrations being current, SELECT postgis_full_version();, object integrity checks, and preserved media, owner, album, sharing, trash, and job state. Expired or running worker leases must be recovered or retried before you declare success. A disposable fixture, deploy/tests/restore-validation.sh, validates this contract.

Details