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 system console includes backup plans, artifact inventory, executable PostgreSQL backup runs, non-destructive restore validation, continuity readiness, and operational incidents. Sovereign operators still own the underlying infrastructure backup policy, storage location, retention, key-provider recovery, and cost review.

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. If you use the Novantra system console to execute a backup plan, the run stores encrypted artifact metadata and sanitized failure evidence in the install operations surface.

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.

Novantra restore validation checks that the backup artifact still matches the expected key-custody path before it touches a restore target. If the required key provider or key metadata is unavailable, validation stops instead of attempting a best-effort decrypt.

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. The console will not validate an expired, unavailable, mismatched, unencrypted, or residency-unapproved backup artifact.

Immutable backup evidence

Production profiles can require immutable backup evidence before a backup is considered restore-ready. Acceptable evidence includes Object Lock, WORM storage, immutable snapshots, customer-owned offline media, append-only targets, or an equivalent provider posture inside the approved residency boundary.

Managed Cloud launch cells may use same-region immutability when cross-region or separate-account copies are not yet approved or would break residency. Sovereign operators provide evidence from their own immutable, offline, or append-only target.

Restore validation stops when required immutable evidence is missing, expired, stale, or mismatched. It does not fall back to a mutable-only artifact for strict production profiles.

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 backups inside the regional cell that owns your workspace. Platform records for that cell, tenant databases, backup artifacts, restore validation, and the jobs that produce them are treated as regional operational surfaces. Recovery from infrastructure failure is Novantra’s responsibility; you’ll be informed of any restore that affects your workspace.

Novantra-managed cloud launch cells use RDS automated backups with point-in-time recovery as the default database recovery foundation. Manual snapshots are reserved for explicit risk events such as risky deployments, migrations, incident response, or approved evidence captures. Cross-region copies are not enabled unless the target region is inside the workspace residency envelope and a customer, cell, or framework requires it.

Strict Cloud profiles also require immutable backup evidence for required targets. Novantra records safe posture evidence and restore readiness, not raw bucket paths, provider secrets, or internal backup locations.

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.

Sensitive database fields and operational metadata remain encrypted in backup artifacts. Restore validation checks both artifact integrity and the expected key-custody path before it touches a target; if the required decrypt authority is unavailable or mismatched, validation stops instead of attempting a partial restore.

The global customer portal may show a backup posture summary for each workspace, but it does not store backup artifacts or restore data from the regional workspace.

What’s still your responsibility

Novantra does not replace your infrastructure backup governance. You still need:

an approved backup policy and retention schedule;
backup storage outside the live database;
key-provider recovery;
regular restore exercises;
immutable, offline, or append-only evidence where your production policy requires it;
cost review for retained snapshots, exported dumps, and backup storage;
customer-owned storage backup when Self Managed Storage is enabled.

Cloud Regions & Residency - how regional cells constrain Cloud backup posture.
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.