Backups and recovery

All hub state lives in one volume mounted at /app/data: the SQLite database and its write-ahead log. Back up that volume and one secret, and you can rebuild the hub anywhere.

What the entrypoint does for you

On every startup the entrypoint snapshots the database into /app/data/backups/ before running migrations, keeping the last five:

• Directory/app/data

  • app.db SQLite database
  • app.db-wal write-ahead log
  • Directorybackups/ last 5 pre-migration snapshots

    • …

These snapshots exist to recover from a migration failure — they are not a disaster-recovery backup, because they live inside the same volume. If the volume is lost, the snapshots go with it. Keep an off-box backup of the volume on whatever schedule fits your data.

The master key matters most

Caution

The single most important thing to back up is RUNAWAY_MASTER_KEY. It is not stored in the data volume — it comes from the hub’s environment — and it encrypts every GitHub token at rest. Lose it and every stored token becomes permanently unreadable. A restored database is only usable with the same key it was encrypted under, so keep a copy in a password manager, separate from the volume.

Restoring

1. Stop the stack so nothing is writing to the database.

2. Restore the volume or the database file from your off-box backup into /app/data.

3. Set the same RUNAWAY_MASTER_KEY the data was encrypted under. Without it the restored tokens stay unreadable.

4. Start the stack again. The entrypoint runs migrations and serves the restored state.

Note

SQLite is single-writer. Restore into a stopped stack and run a single instance — never two containers against the same volume.

What’s next

Docker Compose deploy The data volume and how the stack is laid out.