---
id: backups
title: Backups
sidebar_label: 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.
:::

## Backing up MongoDB

With the bundled Mongo container:

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

Restoring:

```bash
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

```bash
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_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                   |

Rehearse a restore now and again. It is the step most often skipped, and the one
that finds the problems.

## Cloud instances

We back these up. You do not need to.