Gatehouse
Sign inGet started
DocsDeploy and operate

Backups and restore

Encrypted scheduled backups to disk and S3, and how to restore one.

Gatehouse keeps everything in one SQLite database. The backup service takes a consistent copy while Gatehouse keeps running, encrypts it, and stores it on the server and, optionally, in an S3 or Lightsail bucket.

How backups are protected

Each backup is compressed, then encrypted with AES-256-GCM using a key derived from the master key. A stolen backup is useless without it, and restoring needs the same master key, which you also need to read the credentials inside. Keep the master key somewhere other than the backups.

Backup files are named gatehouse-<time>.ghbk.

Scheduled backups

The backup service in deploy/lightsail/docker-compose.yml runs node src/ops/backup-job.ts. Configure it in .env:

Variable Default Purpose
BACKUP_INTERVAL_HOURS 24 How often to back up.
BACKUP_KEEP_DAYS 30 Older backups are deleted, on disk and in the bucket.
BACKUP_DIR /backups Where backups are kept on the server.
BACKUP_S3_BUCKET unset Bucket for the off-site copy.
BACKUP_S3_REGION us-east-1 Bucket region.
BACKUP_S3_ACCESS_KEY_ID, BACKUP_S3_SECRET_ACCESS_KEY unset Credentials that can put, list and delete in the bucket.
BACKUP_S3_PREFIX gatehouse/ Folder inside the bucket.
BACKUP_S3_ENDPOINT, BACKUP_S3_PATH_STYLE unset For S3-compatible stores such as MinIO.

Settings → General → Data protection shows the last backup and whether it was copied off-site. It turns amber when the last backup is more than two days old.

On Lightsail, also keep the automatic instance snapshots on. They capture the whole server, including .env and the master key.

Back up now

docker compose exec backup node src/cli.ts backup-now /backups

Without Docker: npm run cli -- backup-now ./backups. update.sh takes one before every update.

Restore

  1. Download the backup you want (from deploy/lightsail/backups/ or the bucket).
  2. Decrypt it with the same master key:
    docker compose run --rm -v "$PWD/restore:/restore" backup node src/cli.ts restore-backup /restore/gatehouse-<time>.ghbk /restore/gatehouse.db
  3. Stop Gatehouse: docker compose stop gatehouse backup.
  4. Replace the database in the gatehouse-data volume with the restored file, and delete its -wal and -shm files.
  5. Start again: docker compose up -d. Check Settings → General: the audit integrity check should pass.

Test a restore on a spare server once, so you know it works before you need it.