Skip to content
CatalystCatalyst Docs

Backups

Two different things need backing up, with different tools and rhythms. The panel and its database are the operator’s job; each server’s files are the owner’s — but the storage backend and retention rules are set here.

1. The panel database

Section titled “1. The panel database”

PostgreSQL holds users, servers, roles, audit logs — everything except the game files themselves. If it is gone, the fleet is unmanageable. The exact pg_dump and restore commands live in disaster recovery; this page owns the schedule and the fleet-wide storage settings.

  • Take automated dumps on a schedule (daily minimum) and ship them off the panel host.
  • Retain enough history to survive a weekend discovery (7–30 days is typical).
  • Restore-test quarterly into a scratch environment (the recovery drill).

2. Choose the fleet-wide backup backend

Section titled “2. Choose the fleet-wide backup backend”

Backups are stored by the backend; pick the default in the panel’s .env (the file the installer wrote next to docker-compose.yml) and apply it:

Terminal window
# edit .env, then:
docker compose up -d backend
Terminal window
BACKUP_STORAGE_MODE=local   # local | s3 | stream | sftp
  • local (default) — files under the backend’s backup directory (BACKUP_DIR, /var/lib/catalyst/backups in the Compose stack).
  • s3 — an S3-compatible bucket. Also set BACKUP_S3_BUCKET, BACKUP_S3_REGION, BACKUP_S3_ACCESS_KEY, BACKUP_S3_SECRET_KEY, and optionally BACKUP_S3_ENDPOINT / BACKUP_S3_PATH_STYLE=true.
  • stream — the agent streams each archive to the panel’s scratch directory (BACKUP_STREAM_DIR), useful when no persistent backup volume is mounted.
  • sftp — upload to a per-server SFTP target, configured on the server.

All four modes are selectable in Admin → Environment. Values outside them fall back to local.

Set BACKUP_CREDENTIALS_ENCRYPTION_KEY (32-byte base64, e.g. openssl rand -base64 32) before storing per-server S3 or SFTP credentials — without it, saving them fails, except outside production with ALLOW_PLAINTEXT_CREDS=1. Rotating the key makes stored credentials undecryptable.

3. Per-server overrides

Section titled “3. Per-server overrides”

Each owner manages backups in the server’s Backups tab, and Backup settings there overrides the fleet default — storage mode, Keep last N, and Max age (days). User backups documents that tab; the backend enforces retention from a six-hourly job and again inline as each backup completes.

With local or stream storage and no backup allocation, the create call fails 403 — Backup allocation disabled. Configure S3 or SFTP to enable backups. S3 and SFTP servers skip that quota entirely.

Pinning needs the backup.pin permission (Pin backups (ignore retention limit) in the role editor). Server ownership does not imply it: grant it through a role (roles) or to an individual subuser; admin.write and * satisfy it too.

Rules

Section titled “Rules”
  1. 3-2-1: three copies, two media, one off-site — for the database at least. Server backups stored on the same node die with the node.
  2. Encrypt off-site copies. Backups contain credentials and private player data.
  3. Monitor failures. A backup task that has errored for a month is the same as no backup. Failures surface in the server’s Backups tab and the panel system errors view.
Section titled “Related”