Backups & restore
Snapshot the vault, restore from a snapshot, and snapshot before risky changes.
Updated
Because all your data is one file, backups are simple and fast: a snapshot is a
byte-exact copy of the .vault file. This page covers taking, listing, and
restoring snapshots — from the CLI and from the admin.
Take a snapshot
./railbase backup
This writes a copy to <data-dir>/backups/backup-<UTC>.vault. Choose your own
path with --out:
./railbase backup --out /backups/railbase-2026-06-04.vault
List local snapshots (newest first):
./railbase backup list
./railbase backup list --dir /backups
Important
A snapshot is only the encrypted .vault file — it carries neither key
needed to use it. Back up both, 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.vaultcopy can't be opened at all. pb_data/.secret, the 32-byte master key Railbase uses to hash session tokens, sign cookies, and encrypt sensitive settings. A snapshot restored without the matching.secretopens, but every existing session/token is invalidated and encrypted settings can't be read.
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.
The admin Settings → Backups screen deliberately keeps restore CLI-only — a one-click restore button in a browser is the kind of thing that wipes production at 3 a.m. by accident. The one in-app exception is the marketplace console, whose Restore rolls the vault back to a chosen snapshot and then re-execs the server so the restored data is live immediately — it exists 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 under Settings → Backups with the
+ New schedule drawer (it defaults to the backup job; pick a cron expression
and, optionally, a retention window). The backups directory defaults to
<data-dir>/backups and can be overridden with RAILBASE_BACKUPS_DIR. 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:
# 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.