Backup & Restore

The platform offers two different things, and only one of them is a backup.

The in-app export is not a disaster-recovery backup

The Data Management export in the web interface is a partial tenant export, intended for moving one organisation’s working data to another installation. Every file it produces says so in its own metadata:

"export_scope": {
  "kind": "partial-tenant-export",
  "note": "PARTIAL tenant export for org-to-org migration, NOT a disaster-recovery backup.
           It carries 12 tables; 34 other organisation-scoped tables are intentionally
           excluded (see excluded_org_scoped_tables). For a complete backup use scripts/backup.sh."
}

Among the 34 excluded tables are evidence_files, audit_log, audit_engagements, evidence_assessments, generated_documents, vendors, teams and custom_risk_definitions — for a GRC installation, most of the value. Do not rely on it to recover an installation.

For disaster recovery use host-level backups (scripts/backup.sh), which capture the whole database, the credentials and — on an install that bundles an object store — the evidence volume, together.

	In-app export	scripts/backup.sh
Purpose	Move one organisation between installations	Disaster recovery
Covers	12 tenant tables	Whole database + evidence + credentials
Excludes	34 org-scoped tables, incl. evidence and audit log	See what it does not cover
Restore	Scoped upsert, users/orgs never deleted	scripts/upgrade.sh --rollback <TS>

Tenant export (organisation-to-organisation migration)

The in-app Data Management feature exports one organisation’s working data as JSON.

Where it lives

Go to Settings, then the Backups section in the settings sidebar. The card is titled Tenant Export / Import, and it says the same thing this page does: a partial export for tenant migration, not a disaster-recovery backup.

Exporting

1. Open Settings, Backups
2. Click Download Tenant Export
3. A JSON file downloads automatically, named scf-backup-YYYY-MM-DDTHH-MM-SS.json
4. Store this file securely — it contains your organisation’s working data in the clear

The export carries:

• All scoped controls and their status
• Evidence tracking configurations
• Organisations and users
• Assignments and comments
• Tasks and notifications
• Metadata (timestamp, record counts)

Importing

1. Open Settings, Backups
2. Click Import Tenant Data and select your export JSON
3. Review the Restore Preview, which is computed against your live data before anything is written:
   • Export creation date and creator
   • Which organisations would be written to
   • How many existing records would be removed
   • Total records and per-table counts
4. Click Confirm Restore to proceed, or Cancel to back out

What a restore actually changes

A restore is scoped, not a whole-database replace. It touches only the organisations named in the file, intersected with the organisations you can access. Within that scope it upserts every row the file carries, then deletes the rows the file does not carry — in one transaction.

• Users and organisations are never deleted.
• Restoring a file whose row ids match the database performs zero deletes and destroys nothing.
• The 34 organisation-scoped tables this export does not carry (see below) are not touched, so a restore will not roll them back to the export’s point in time.

This means a restore is not a clean-slate recovery. If you are recovering from corruption, the damaged rows in those 34 tables survive the restore. Use the host-level backups for that.

---

Backup File Format

The platform uses a JSON backup format for portability:

{
  "metadata": {
    "version": "1.1",
    "created_at": "2025-01-15T10:30:00.000Z",
    "created_by": "admin@example.com",
    "table_counts": {
      "organizations": 1,
      "scoped_controls": 150,
      "evidence_tracking": 200,
      "users": 5,
      "assignments": 25,
      "comments": 50
    }
  },
  "data": {
    "organizations": [...],
    "scoped_controls": [...],
    "evidence_tracking": [...],
    ...
  }
}

Field	Description
metadata.version	Backup format version (currently 1.1; 1.0 files still restore)
metadata.created_at	ISO timestamp of backup creation
metadata.created_by	User who created the backup
metadata.table_counts	Record count per table
data	Full data for each table

---

What Gets Backed Up

Data Type	Included	Notes
Organisations	Yes	All organisation records
Scoped Controls	Yes	Control selections and status
Evidence Tracking	Yes	Evidence configurations
Users	Yes	User accounts and roles
Organisation Members	Yes	User-org relationships
Assignments	Yes	Control/evidence assignments
Comments	Yes	All comments and discussions
Evidence Tasks	Yes	Task records
Notifications	Yes	Notification history

Not Included

• SCF catalog data (controls, evidence requirements) — reference data, seeded into the database from the catalogue JSON on the host. It is not shipped with the platform on a self-hosted install and no backup captures it — see the caution below
• System configuration — Managed by the platform
• The credential directory (SCF_SECRETS_DIR) and SCF_SECRET_KEY — the in-app JSON backup never contains them. SCF_SECRET_KEY encrypts the integration credentials stored in the database, so a database restored onto a host that does not hold the same key cannot read its encrypted integration credentials. Back the credentials up with scripts/backup.sh (below). On a legacy install whose credentials are still in .env, back up .env separately

The catalogue is not in any backup — keep your workbook

Nothing the platform backs up contains the SCF catalogue source. Neither the in-app export, nor scripts/backup.sh, nor the pre-upgrade backup taken by scripts/upgrade.sh captures webclient/public/data.

It survives day to day for one reason: the catalogue JSON sits in your checkout, the generated files are gitignored, and git checkout does not touch gitignored files — so an upgrade leaves them alone. That is a side effect, not a backup. Only four small curated files in that directory are tracked in git; the nine that carry the catalogue itself (control_guidance.json, frameworks.json, domains.json, erl.json, assessment_objectives.json, catalog_meta.json, controls_mapping.json, controls_v3.json, scoped_controls.json) are generated by the catalogue importer from your own SCF workbook and exist only on that host’s filesystem.

What this means for disaster recovery. Restoring onto a fresh host gives you a complete database — the catalogue tables are inside the pg_dump, so the platform starts and looks correct. But the JSON directory comes back holding only the four tracked files. Two things then go quietly wrong:

• Framework display names fall back to a title-cased version of their key, everywhere they appear — including in generated policies, SSPs and audit deliverables. There is no error; one warning is written to the backend log.
• The reported catalogue version falls back to a built-in default, so the platform can report one catalogue version while serving the controls of another.

Keep your SCF workbook (catalog-source/scf.xlsx, or wherever SCF_XLSX points) somewhere you back up. It is the only way to regenerate the catalogue, and the platform neither ships it nor captures it. After a fresh-host restore, re-run the importer before trusting any generated document:

docker compose --profile init run --rm catalog-importer
docker compose restart backend celery-worker

The restart is required, not optional: the backend reads frameworks.json once at start-up and does not re-read it, so an importer run alone does not fix a process that already started without it.

On Linux, check the directory’s group before you run the importer. A fresh host is a fresh git clone, so webclient/public/data comes back owned by whoever cloned it, and the importer — container root with cap_drop: ALL, holding gid SCF_APP_GID only as a supplementary group — cannot write into it. The import fails with PermissionError: /app/data/json/.... scripts/install.sh sets this on a normal install and scripts/upgrade.sh re-checks it on every upgrade, but a restore onto a bare host runs neither, so do it once by hand:

docker run --rm -v "$PWD/webclient/public/data:/d" alpine:3 \
  sh -c 'chgrp -R 1001 /d && chmod 2775 /d'

Use your own SCF_APP_GID if you overrode it in .env. This is a chgrp, not a chown: you stay the owner of the checkout. It applies to every self-hosted install — the catalogue JSON is on this host’s filesystem whether your database and evidence store are bundled or external.

---

Host-level backups (self-hosted)

On a self-hosted install, scripts/backup.sh takes one complete backup set into ./backups. It uses the same file names as the pre-upgrade backup taken by scripts/upgrade.sh, so either set can be restored with scripts/upgrade.sh --rollback <TS>:

File	Contents
<TS>_v<version>.dump	Whole-database Postgres dump, including Keycloak’s schema and the audit log
<TS>_v<version>_minio.tgz	MinIO evidence volume. Only on an install that bundles an object store — see Installs that bundle no object store
secrets-<TS>.tar.gz	Every credential file from SCF_SECRETS_DIR, written with mode 0600. The wizard’s .provision-token is excluded: it authorises the installer and has no restore value
<TS>_ref.txt, <TS>_checksums.sha256	Git ref at backup time, and checksums of the data files

scripts/upgrade.sh --rollback <TS> restores both data stores and, when secrets-<TS>.tar.gz is present, unpacks it into SCF_SECRETS_DIR after setting the current credentials aside — so a rolled-back database and the key that encrypted it move together.

The set is also the rollback point an upgrade carries with it. An upgrade hands over to the target release’s copy of the script after checking the tag out, and the process that takes over locates <TS>_v<version>.dump and <TS>_ref.txt on disk and refuses to build or migrate until it has found them. So a set you move or delete mid-upgrade stops the upgrade rather than quietly costing it its ability to roll back. Copy sets out of ./backups, never out from under a running upgrade.

The database is inert without its key

Integration credentials (Settings, Integrations) are stored encrypted under SCF_SECRET_KEY, and evidence download links are signed with DOWNLOAD_TOKEN_SECRET. A database restored onto a host that does not hold the same SCF_SECRET_KEY cannot read its encrypted integration credentials, and there is no recovery path. Always restore the credential tarball alongside the dump.

Legacy .env installs

When no SCF_SECRETS_DIR is configured, scripts/backup.sh says so and writes no credential tarball: your credentials, SCF_SECRET_KEY included, are in .env. Back that file up separately, and store it somewhere the backup set is not. To move onto file-backed credentials, run scripts/install.sh --import-env — see Credentials and secrets.

Installs that bundle no object store

Installing with scripts/install.sh --no-minio bundles no object store: evidence lives in the S3-compatible bucket you configure under Settings, Evidence storage, and there is no minio_data volume on the host to tar.

Both scripts detect this and skip the evidence half of the set, loudly, rather than failing or producing a tarball of nothing. The test is a non-empty MINIO_ROOT_USER, read from .env or from SCF_SECRETS_DIR — the --no-minio installer writes that credential file deliberately empty, and the bundled MinIO cannot start without one, so an empty value really does mean “this install has never run a bundled object store”. On such an install:

• scripts/backup.sh prints SKIPPING the evidence backup: no bundled object store on this install, and the set it writes is the database dump plus the credential tarball only. The _minio.tgz file is absent, and the checksum file lists only the files that exist.
• scripts/upgrade.sh prints the same warning and proceeds with the upgrade. Its pre-upgrade backup covers the database only, so a subsequent --rollback rewinds the database and leaves your external store exactly as it is.
• Neither script starts a MinIO container. Naming a profiled service on a docker compose up command line activates its profile, so both scripts omit minio from that command when the storage profile is off.

Your external store is your responsibility

Nothing in the platform backs up an external bucket or container. Use bucket versioning, cross-region replication, provider snapshots or your own scheduled copy — and, because the database half is rewound independently, decide in advance how you would reconcile the two after a rollback.

An install that does bundle an object store is unaffected: the evidence tar stays mandatory and symmetric with the database dump, and both scripts still refuse to continue without it.

External database and external object storage

backup.sh and upgrade.sh only cover the bundled services

Both scripts are hard-wired to the bundled Postgres container and the bundled MinIO volume. If you chose an external database at install time, that database is outside every backup the platform takes, and neither script warns you.

Object storage is better covered. scripts/backup.sh skips the evidence tar loudly when the install bundles no object store (see above), and on every run it also counts the organisations that have configured a store of their own and warns that their evidence is outside the set. scripts/upgrade.sh does neither count nor warning.

External database. scripts/backup.sh runs docker compose exec -T postgres pg_dump and derives the user and database from the compose postgres service, not from your DB_HOST / DB_NAME / DB_USER. Because the bundled postgres service starts on every install — including the external one — that command succeeds, produces a non-empty dump of the unused bundled database, passes validation and reports success. scripts/upgrade.sh shares this logic, including its --rollback restore path.

If you run an external database you must take your own backups, using your provider’s mechanism (RDS snapshots, Cloud SQL backups, pg_dump against your host) or your own scheduled job. Verify a restore end to end before you rely on it.

External object storage. scripts/backup.sh captures evidence by tarring the minio_data Docker volume. The volume is the only thing it can tar, so a store that is not that volume is never in the set — but the script now tells you when that is the case, in two different ways.

• No bundled store at all. An install made with --no-minio skips the evidence tar loudly, as described above.
• Organisations on their own stores. On every run, bundled or not, the script counts the organisations whose evidence storage configuration points somewhere of their own and warns that their files are outside the set. A bundled install is not covered merely because its volume was tarred: each of those organisations keeps its evidence somewhere this script has never heard of. When the count cannot be taken — an older schema, or Postgres unreachable — it says so rather than reporting zero.

One gap remains, and the warnings above do not close it: an install that bundles MinIO and has had its platform-wide store repointed at an external bucket, by setting AWS_ENDPOINT_URL to real S3 in .env while MINIO_ROOT_USER is still set. There the script tars the now-unused MinIO volume, reports success, and your live evidence is not in the backup set.

For any store that is not the bundled volume, use bucket versioning, cross-region replication or your provider’s backup tooling, and do not read a green backup run as covering it. Settings, Evidence storage names the provider and bucket for each organisation, which is where to start that list.

Bundled Keycloak with an external database. Keycloak’s connection is pinned to the bundled Postgres (KC_DB_URL is a literal in docker-compose.yml) and does not follow DB_HOST. Running the idp profile alongside an external application database therefore splits your data across two servers: identity in the bundled container, application data in your external instance. Use an external OIDC provider instead, or keep the bundled database.

Rotating DB_PASSWORD on an external database. The procedure in Credentials and secrets targets the bundled container. On an external database, run the ALTER ROLE against your own server instead — see the note there.

---

Backup Best Practices

Recommended Backup Schedule

Frequency	When	Purpose
Weekly	End of week	Regular checkpoint
Before major changes	As needed	Safety net before bulk operations
Before audits	Before audit period	Preserve audit-ready state
Monthly archive	First of month	Long-term retention

Storing Backups Securely

1. Keep multiple copies — Store backups in at least two locations
2. Use secure storage — Encrypt backup files or store in secure cloud storage
3. Document your backups — Keep a log of what each backup contains
4. Test periodically — Verify backups can be restored successfully

Before Major Changes

Always create a backup before:

• Bulk importing or deleting controls
• Major configuration changes
• User cleanup operations
• Organisation restructuring

---

Testing Your Backups

Regularly verify backups are restorable:

1. Monthly test — Download a backup and review its contents
2. Quarterly drill — Restore to verify data integrity
3. After major updates — Create and verify a new backup

Verifying Backup Contents

After downloading a backup:

1. Open the JSON file in a text editor
2. Check metadata.table_counts matches expected record counts
3. Verify metadata.created_at shows the correct timestamp
4. Spot-check a few records in the data section

---

Disaster Recovery

If Data Is Lost or Corrupted

1. Stop writes. Take the stack down or stop the backend and workers so the damage stops spreading and the restore is not racing live traffic.
2. Identify the scope. Which organisations and which tables are affected decides which mechanism you need — see the table below.
3. Choose the mechanism. A host-level backup set is the only complete recovery path. The in-app export can only return the 12 tenant tables it carries, for the organisations it carries.
4. Restore. scripts/upgrade.sh --rollback <TS> restores both data stores and, when the credential tarball is present, the credentials that decrypt them.
5. Verify. Confirm row counts, then confirm evidence files actually open — a database restored without its SCF_SECRET_KEY cannot read its encrypted integration credentials, and evidence links signed with a different DOWNLOAD_TOKEN_SECRET will not resolve.

Which mechanism recovers what

Scenario	Mechanism	Notes
Whole installation lost, or data corruption	scripts/upgrade.sh --rollback <TS>	The most complete path: database + evidence + credentials. It does not restore the catalogue JSON — see the row below
SCF catalogue JSON missing after a fresh-host restore	Re-run the catalogue importer against your own workbook	No backup contains it. Restart backend and celery-worker afterwards — see the caution above
Reverting a bad upgrade	scripts/upgrade.sh --rollback <TS>	upgrade.sh takes this backup automatically before it migrates
One organisation’s working data needs re-seeding from another install	In-app restore	12 tables only; users and organisations are never deleted
Accidental deletion inside the 34 excluded tables (evidence, audit log, assessments, vendors)	scripts/upgrade.sh --rollback <TS>	The in-app export never carried these
External database or external object storage	Your provider’s tooling	Not covered by either mechanism — see above

Recovery time depends on database size and evidence volume; measure it on your own install rather than assuming. Test the restore path before you need it — see Testing Your Backups.

---

Troubleshooting

Backup Button Disabled

Cause: Another backup/restore operation is in progress.

Solution: Wait for the current operation to complete.

“Invalid backup file” Error

Causes:

• File is not valid JSON
• Missing metadata or data sections
• Unsupported backup version

Solutions:

1. Verify the file wasn’t corrupted during download or transfer
2. Check that you selected an SCF backup file (not some other JSON)
3. For older backups, check version compatibility

Restore Fails Mid-Process

Cause: Network interruption or server error during restore.

Solution:

1. Wait a moment and try again
2. If issues persist, contact support
3. Try restoring with a different backup file

Restore Shows Wrong Data

Cause: Restored wrong backup file.

Solution:

1. Check the backup file’s metadata.created_at timestamp
2. Restore the correct backup
3. Keep backups organised with clear naming

---

Related Guides

• Configuration — Platform settings
• Monitoring — System health
• Troubleshooting — Common issues