Docs Backup and Disaster Recovery

Backup and Disaster Recovery

This guide shows how to take a backup you can rebuild a Mockarty node from, how
to check it, and how to restore it after a failure.

What you need to protect

What Where it lives How it is backed up
Database PostgreSQL, or a SQLite file mockarty --backup (below) or the scheduled backups in the admin panel
Stored files: attachments, report files A folder on disk, or object storage mockarty --backup includes the folder; back up an object-storage bucket with the storage’s own tools (versioning or mirroring)
Encryption keys Your secret store Keep them yourself — a backup never contains them
Configuration Environment, Compose or Helm values Keep them in version control

The encryption keys are MOCKARTY_PII_ENCRYPTION_KEY, MOCKARTY_PII_HMAC_PEPPER
and CHAOS_ENCRYPTION_KEY, when you use them. Data written with a key can only
be read with the same key: a database restored without its keys loses every
encrypted value. Store each key version with the date it was introduced, so you
can match it to a backup. After a key rotation, keep the previous key in
MOCKARTY_PII_ENCRYPTION_KEY_PREVIOUS on the node you restore into until the
rotation has finished: a backup taken earlier still needs it, and the restore
names it when it is missing. Set CHAOS_ENCRYPTION_KEY before you take backups:
without it, stored chaos-cluster credentials are tied to the original database
connection, and a restore into a different database server reports a different
chaos credential key. To restore anyway, add --restore-ignore-key-mismatch and
connect the chaos clusters again afterwards.

Two kinds of backup

  • Scheduled backups in Admin Panel > Backup copy the database while
    Mockarty runs. Use them for everyday protection against mistakes. See
    Administration Guide.
  • Full node backup with mockarty --backup takes the database and the
    stored files into one folder with a manifest that pins every file by checksum
    and records which encryption keys the data was written with. Use it for
    disaster recovery: a lost server, a broken disk, a move to new hardware.

Take a full backup

Run the Mockarty binary with the same settings the server uses (DB_USE,
DB_DSN, MOCKARTY_BLOB_BACKEND, MOCKARTY_BLOB_FS_ROOT and the keys), and
give it a new, empty folder:

mockarty --backup /backups/mockarty-2026-09-26

Backup written to /backups/mockarty-2026-09-26: pg database at schema version 438.
Stored files (attachments, reports): 1204, included.
Encryption keys are not in the backup. Keep them, from the same moment, in your secret store: a restore needs the same keys.

The backup is consistent while Mockarty keeps running: for PostgreSQL it uses
pg_dump, for SQLite a transactional snapshot. PostgreSQL backups need the
PostgreSQL client tools (pg_dump, pg_restore) of the server’s major version
or newer on the machine that runs the command — the official Mockarty image
already has them. On Kubernetes, run the command inside an admin pod and write
to a mounted volume:

kubectl exec deploy/mockarty -- /app/mockarty --backup /app/data/backups/2026-09-26

The folder contains manifest.json, the database (database.dump or
database.sqlite) and, with a file store, blobs.tar.gz. Copy the whole folder
to storage outside the server.

Check a backup

A backup you have never checked is a hope, not a backup. Verify each one after
copying it, and restore one into a spare node from time to time:

mockarty --verify-backup /backups/mockarty-2026-09-26

The check fails if any file is missing, altered or unexpected; for SQLite it
also runs the database’s own integrity check.

Restore after a failure

  1. Prepare the node: the same Mockarty release as the backup or a newer one,
    the same encryption keys, and the database and file-store settings it will
    use. For PostgreSQL, create an empty database.

  2. Stop Mockarty on that node.

  3. Restore:

    mockarty --restore /backups/mockarty-2026-09-26

  4. Start Mockarty. It applies the database changes of its own release, if the
    backup came from an older one.

  5. Open the web interface and check recent mocks, test runs and attachments.

Mockarty checks everything before it changes anything. It refuses to restore
when:

Message says What to do
the backup does not match its manifest The copy is damaged. Use another backup
pg_restore cannot read the backup Install the PostgreSQL client tools of the server’s major version or newer, or use another backup
the encryption keys differ Configure the keys the backup was taken with. --restore-ignore-key-mismatch restores anyway, but encrypted values stay unreadable
the database is newer than this binary Install the release the backup was taken with, or a newer one
the target database already has tables Point DB_DSN at an empty database, or add --restore-replace to replace the existing one
a different kind of database or file store Restore into a node with the same kind (PostgreSQL or SQLite; folder or object storage)

A SQLite database file and a file store that already exist are not deleted: the
restore moves them aside and prints where they are. Delete them once the node
works.

Restore a single backup file (SQLite)

The admin panel’s scheduled backups of a SQLite node are single database files.
Download one, stop Mockarty, and restore it the same way:

mockarty --restore backup_daily_20260926_020000_4f1c2a.db

A single file holds the database only: attachments and report files are not in
it, and the encryption keys cannot be checked.

Before an upgrade

Take a full backup before every upgrade. If a new release has to be rolled back
and the rollback cannot keep the database, this backup is the way back — see
Upgrades and Rollbacks.

Previous
Licensing Model