vantage-docs/docs/operations/backups.md

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, monitors, incidents, secrets, settings, audit	Yes
Redis	Sessions only	No. Losing it signs everyone out and nothing else
./data bind mount	Workflow run logs	Optional
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. :::

Backing up MongoDB

With the bundled Mongo container:

docker compose exec -T mongo mongodump --archive --gzip --db vantage \
  > /backups/vantage-$(date +%F).archive.gz

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 it holds the encryption key.

Run logs

Workflow run logs live in the ./data bind mount, not in the database. They are swept on the retention schedule anyway, so most people do not back them up. If you keep them for compliance, set retention to 0 (forever) and include the directory.

What a restore gives you

Everything: fleet, 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_keys to match the restored desired state, which may remove keys added since the backup.

A workable schedule

What	When
MongoDB dump	Nightly, retained per your policy
Environment file	On change, held in a password manager or secret store
Restore rehearsal	Occasionally, into a throwaway host

The rehearsal is the part that gets skipped and the part that finds the problems.

Cloud instances

We back these up. You do not need to.