Legend

Backup and Restore

Because you host Legend yourself, keeping your map safe is your responsibility. The good news is that a self-hosted instance is straightforward to protect with regular backups of two things: the database and any uploaded files.

Why back up

Your map becomes a reference the whole organization relies on. Backups protect that investment against hardware failure, mistakes, and the ordinary risks of running any system. A recent backup turns a bad day into a minor inconvenience.

What to back up

  • The database, which holds your Agents, Landmarks, and relationships.
  • Uploaded files, if your instance stores them.
  • Your configuration, including environment variables and any secrets, kept in your secret store.

Backing up the database

For PostgreSQL, pg_dump produces a portable snapshot. Running it against the database container from the example deployment looks like this:

  • docker compose exec -T db \
  • pg_dump -U legend -d legend \
  • > legend-backup-$(date +%F).sql

Run this on a schedule that matches how often your map changes. A daily dump is a reasonable starting point for most teams.

Backing up uploaded files

If uploads live on a mounted volume, copy that volume’s contents to your backup location. If they live in object storage, use that provider’s snapshot or sync tooling. Include the files in the same schedule as the database so the two stay consistent.

  • tar czf legend-uploads-$(date +%F).tar.gz \
  • /path/to/legend/uploads

Storing backups safely

  • Keep copies somewhere separate from the instance itself, ideally off the host.
  • Retain several days or weeks of history, not just the latest copy.
  • Protect backups the way you protect the live data, since they contain the same information.

Restoring

A backup you have never restored is a hope, not a plan, so practice the restore before you need it. To restore the database from a dump:

  1. Stand up a database, either a fresh one or the existing one you intend to overwrite.
  2. Load the dump into it.
  3. Restore uploaded files to the same location the instance expects.
  4. Start the application and confirm your Agents, Landmarks, and relationships are all present.
  • cat legend-backup-2026-01-15.sql | \
  • docker compose exec -T db \
  • psql -U legend -d legend

Test a restore into a scratch environment on a schedule, for example quarterly, so you know the procedure works and how long it takes.