Railbase
GPTClaude

Backups & restore

Snapshot the vault, restore from a snapshot, and snapshot before risky changes.

Updated

Video guide —watch on YouTube ↗

Because records live in one Vault file, snapshots are simple and fast: a snapshot is a byte-exact copy of the .vault file. Uploaded blobs live in the storage directory and should be backed up alongside the Vault snapshot. This page covers taking, listing, and restoring snapshots — from the CLI and from the admin.

Take a snapshot

./railbase backup

Like every CLI command that opens the vault, backup takes the vault file lock, so stop the server first (or take the snapshot from the admin console, which runs in-process). This writes a copy to <data-dir>/backups/backup-<UTC>.vault (or RAILBASE_BACKUPS_DIR if set). Choose your own path with --out:

./railbase backup --out /backups/railbase-2026-06-04.vault

List local snapshots (newest first). This lists both the .vault snapshots railbase backup writes and the scheduled job's backup-<UTC>.tar.gz archives, and honors RAILBASE_BACKUPS_DIR (so archives on an off-host mount show up too):

./railbase backup list
./railbase backup list --dir /backups

Important

A snapshot is the encrypted .vault file — it carries neither key needed to use it and it does not include uploaded blobs from <data-dir>/storage. Back up the Vault snapshot, file storage, and both secrets separately and securely:

  • the vault password that decrypts the file (Argon2id unlock material, from RAILBASE_VAULT_PASSWORD, RAILBASE_VAULT_PASSWORD_FILE, or <data-dir>/.vault_password). Without it the .vault copy can't be opened at all.
  • pb_data/.secret, the 32-byte master key Railbase uses to hash session tokens, sign cookies, seal the audit chain, and derive the field-level encryption KEK. A snapshot restored without the matching .secret opens, but every existing session/token is invalidated and any field-encrypted values (and, with RAILBASE_ENCRYPT_STORAGE, encrypted file blobs) become permanently undecryptable — real data loss, not just re-login. Back it up.
  • the storage directory (<data-dir>/storage by default, or RAILBASE_STORAGE_DIR) if you use File() / Files() fields. The Vault stores file metadata; the blob bytes live in the storage directory.

Restore

Restore replaces the live data with a snapshot:

./railbase backup --restore /backups/railbase-2026-06-04.vault

There is no separate restore command — restore is the --restore flag on backup. Stop the server first: restore needs the vault file lock, so it won't overwrite a path a running instance still holds open. Restore writes to the default vault location (<data-dir>/railbase.vault); if you run with a custom RAILBASE_VAULT_PATH, move the restored file into place afterward.

The admin Settings → Backups screen keeps destructive restore gated. CLI restore is always available while the server is stopped. Browser restore is only enabled when the operator explicitly sets RAILBASE_ENABLE_UI_RESTORE=true and the admin holds the admin.backup.restore permission; it then requires a dry-run, confirm-by-filename, and maintenance mode. Marketplace-driven rollback uses the same snapshot discipline to recover from a failed plugin install/update.

Caution

Restoring overwrites current data with the snapshot's contents. Take a fresh snapshot of the current state first if you might need to come back to it.

Snapshot before risky operations

Make a habit of snapshotting before anything irreversible:

  • a core self-update (so you can roll back across a bad upgrade),
  • a plugin purge (which permanently deletes that plugin's collections — the console takes its own backup first, but a manual one is cheap insurance),
  • bulk data imports or migrations.

The console's Backup action takes an on-demand snapshot for exactly these moments. See Installing plugins and Updating.

Scheduled backups

For unattended snapshots, Railbase ships a built-in scheduled_backup job. It is not on by default — turn it on from the Settings → Scheduler screen with the New schedule drawer (it defaults to the backup job; pick a cron expression and, optionally, a retention window and output directory). The scheduled job writes compressed .tar.gz archives; like the CLI, it defaults to <data-dir>/backups and honors RAILBASE_BACKUPS_DIR (a per-schedule output directory overrides both). The same thing from the CLI:

# create + enable a nightly (02:00 UTC) scheduled backup
./railbase cron upsert scheduled_backup "0 2 * * *" scheduled_backup
./railbase cron enable scheduled_backup

Pair it with off-box copies:

The Backups screen in the Railbase admin
Settings → Backups: on-demand snapshots and the archive list. Recurring schedules live on the Scheduler screen.
# e.g. a nightly rsync of the backups dir to object storage / another host
rsync -a /var/lib/railbase/backups/ backup-host:/railbase/

Tip

Keep at least one copy off the box. A snapshot that lives only on the same disk as the original doesn't protect you from losing that disk.

Was this page helpful?Thanks for your feedback!
← PreviousDeploying to productionNext →Security hardening