Backup & Restore

A Sovereign install holds state in three places. To recover the install after hardware loss or corruption, you need a current copy of all three, and you need to know how they relate.

The operator-facing backup orchestration UI in the system console is not fully built out in v1. Backup foundations exist inside the product (backup-plan inventory, scheduled PostgreSQL backup runs, non-destructive restore validation), but day-to-day backup work today happens through the infrastructure tools you already use (pg_dump, your file-system backup, your KMS provider’s own export/recovery procedures). This page is what to back up; the orchestration UI will land in a subsequent release.

What you back up

1. Databases

A Sovereign install holds two database scopes:

Install database. One per install. Holds: bootstrap state, license, install settings, mailer config, key-management metadata, the list of organizations, backup plan inventory, audit chain for install-level actions.
Tenant databases. One per organization on the install. Each holds that organization’s members, roles, audit log, forms, classifications, public sessions, artifacts metadata, and key-version records.

Back up all of them. Tenant databases are the bulk of customer data; the install database is the connective tissue without which the tenant databases can’t be opened.

Use your standard PostgreSQL backup tooling: pg_dump, pg_basebackup, your managed-Postgres provider’s continuous backup, or a filesystem snapshot of the data directory.

2. Key material

This is the part operators get wrong most often. Novantra does not hold a usable copy of the encryption keys that protect your databases. The keys live in the key provider you configured at install:

HashiCorp Vault (Transit engine).
A PKCS#11 HSM.
AWS KMS or Azure Key Vault (if you chose a cloud KMS to back your on-prem install).

A database backup is useless without the key provider that wraps its contents. If you back up a database but lose the keys, the backup is encrypted noise.

What “backing up keys” actually means depends on the provider:

Provider	What to back up
Vault Transit	Vault snapshots (your existing Vault backup strategy). The Transit key cannot be exported; recovery is recovery of Vault itself.
PKCS#11 HSM	Whatever export/recovery procedure your HSM vendor supports. Network HSMs typically replicate to a peer; you need to verify the peer is healthy.
AWS KMS	The KMS key cannot be exported; recovery means recovery of AWS account access to that key. The key’s metadata and policy can be reproduced from infrastructure-as-code; the key material itself is in AWS’s custody.
Azure Key Vault	Soft-delete and purge-protection on the vault. Same custody model as AWS KMS.

If you’re using Self Managed Secret Keys for organizations, that’s your own KMS — same backup considerations apply. Novantra never holds those keys.

3. Files (storage)

Files uploaded into Novantra live in either:

The install’s bundled storage (default on .deb and Docker if you didn’t configure customer storage).
A customer-configured S3 bucket (per Self Managed Storage).
The local filesystem (Sovereign supports a local_filesystem_dedicated binding).

Back up wherever your active storage binding points. For customer S3 you already have bucket-level lifecycle, replication, and object lock — keep using them. For local filesystem, include the directory in your filesystem backup.

4. Configuration on disk

Small but important:

Install bootstrap config: /etc/novantra/bootstrap.env on Linux installs (bind address, setup port). Trivially small; back up with the rest of your /etc.
Persistent install state directory: /var/lib/novantra/onprem/ on Linux; the data volume in Docker. Holds bootstrap state and any in-progress setup secrets.

These files don’t have user data in them — they describe how the install starts. Losing them is recoverable, but you’ll have to re-bootstrap setup and rotate the setup token.

What you do not back up

The binary or installed package — you reinstall from the artifact when restoring; don’t try to back up the application files.
Cached/derived artifacts in .next/ or similar — regenerated on start.
Logs — back them up if you need them for compliance retention, but they don’t participate in recovery.

Validating a backup

A backup that you’ve never validated is a wish, not a backup. At minimum:

Smoke-test restores of the install and at least one tenant database in a non-production environment, against the same Novantra version and the same key provider configuration (or a key-provider snapshot).
Run the audit chain verification on the restored tenant database. A successful chain verification (see Audit Log) is the cleanest signal the data is intact and consistent.
Confirm you can sign in as a known member and reach the workspace.

How often you do this is up to you. Quarterly is a reasonable baseline for production installs. After major upgrades is always worth it.

Recovering after a loss

Assume the worst case: install host destroyed.

Stand up a replacement host with the same operating system family.
Install the same Novantra version as was running before. Don’t try to upgrade during recovery.
Restore the install bootstrap config and state directory to the new host.
Restore the key provider’s state (Vault snapshot, HSM peer activation, KMS access). Without this, the rest fails.
Restore the install database to a fresh PostgreSQL of the supported version.
Restore each tenant database.
Point Novantra at the restored databases by configuring the same connection strings. The install reads them, recognizes the license, and starts.
Validate as described above before declaring recovery complete.

If your storage binding pointed at customer S3, that bucket is already external and survives the host loss — Novantra resumes reading from it as soon as the install is back up.

Cloud customers

In Cloud, Novantra runs continuous backups of platform and tenant databases against managed infrastructure. Storage uses managed object storage with cross-AZ durability. Recovery from infrastructure failure is Novantra’s responsibility; you’ll be informed of any restore that affects your workspace.

If you’ve enabled Self Managed Storage in Cloud, the files in your bucket are governed by your bucket’s own backup posture — Novantra cannot back up data we don’t hold.

If you’ve enabled Self Managed Secret Keys in Cloud, your provider’s backup posture governs the keys — same story.

What’s coming

The deferred work that will land in subsequent releases:

A backup orchestration page in the system console showing scheduled runs, last-run status, expected next run, and a “test restore” action.
A documented recovery runbook for common failure shapes (single-database corruption, lost install database, lost key provider access).
Automated restore validation that pulls a backup, verifies it can be restored to an isolated database, runs audit chain checks, and reports.

Until these land, this page is the contract: know where state lives, take your own backups, validate them yourself.

Sovereign Installation — where the install state directories were configured.
Self Managed Secret Keys — key custody.
Self Managed Storage — file custody.
Storage Migration — moving existing data into a new storage binding.