mrhid6
f564dd0479
backups.md kept its store-level table and danger note but now points to vantagectl as the supported path, with mongodump/mongorestore demoted to an explicit fallback and a warning that a plain dump records no key fingerprint. backup-and-restore.md links back for the store-level overview.
4.5 KiB
id, title, sidebar_label
| id | title | sidebar_label |
|---|---|---|
| backups | Backups | Backups |
Two things matter: MongoDB and KEY_ENCRYPTION_KEY. A backup missing
either one restores to something unusable.
What holds what
| Store | Contents | Back up |
|---|---|---|
| MongoDB | Everything durable: servers, keys, assignments, workflows, runs and their logs, monitors, incidents, secrets, settings, audit | Yes |
| Redis | Sessions only | No. Losing it signs everyone out and nothing else |
KEY_ENCRYPTION_KEY |
Not stored anywhere by the app | Yes, separately |
:::danger The database alone is not a backup
Private keys, vault secrets, OIDC client secrets and console credentials are
encrypted with KEY_ENCRYPTION_KEY, which lives in your environment file and
nowhere in the database. Restore the database without it and every one of those
values is permanently unreadable.
Store the key somewhere other than the server it protects. :::
:::info Use vantagectl
Backup and restore is the supported way to take
and restore a backup. It writes an archive that carries a fingerprint of
KEY_ENCRYPTION_KEY — never the key — so a restore taken with the wrong key
refuses rather than silently producing a database whose secrets nobody can
read. It also checksums every archive member before writing anything, and
refuses to restore into a database that already holds data. A plain
mongodump does none of that: it records nothing about which key the data was
encrypted under, so a restore from one succeeds even when the key is wrong and
the failure only shows up later, as unreadable secrets.
The rest of this page, past the table above, describes the mongodump /
mongorestore fallback for an operator who does not have vantagectl
available. Prefer the linked page.
:::
Backing up MongoDB (fallback, without vantagectl)
With the bundled Mongo container:
docker compose exec -T mongo mongodump --archive --gzip --db vantage \
> /backups/vantage-$(date +%F).archive.gz
:::warning
This archive records nothing about which KEY_ENCRYPTION_KEY it was taken
under. Restoring it with the wrong key produces a database that looks intact
and is not — every secret in it is silently unreadable until something tries
to decrypt one.
:::
Restoring:
docker compose exec -T mongo mongorestore --archive --gzip --drop \
< /backups/vantage-2026-07-28.archive.gz
--drop replaces existing collections. Stop the server container first, so
nothing writes during the restore.
Backing up the environment file
cp /opt/vantage/.env /secure-location/vantage.env
Treat it as a credential in its own right, since it holds the encryption key.
What a restore gives you
Everything: server, keys, assignments, workflows and their history, monitors and incidents, secrets, settings and the audit log.
What it does not do is reconcile the world. After a restore:
- Agents reconnect with their existing tokens, since the token hashes are in the database.
- If the restore is older than an enrolment, that server's token hash is missing and the agent will fail to authenticate. Re-enrol it.
- The next agent poll rewrites
authorized_keysto match the restored desired state, which may remove keys added since the backup.
A workable schedule
| What | When |
|---|---|
| Backup | Nightly, retained per your policy |
| Environment file | On change, held in a password manager or secret store |
| Restore rehearsal | Occasionally, into a throwaway host |
Rehearse a restore now and again. It is the step most often skipped, and the one
that finds the problems. See Backup and restore for
the drill, and for verify, which checks a backup is real without a restore.
Cloud instances
We back these up. You do not need to.