Backups

1. Overview

Settings → Backups takes a backup of this installation's database and its platform files: avatars, branding, plugin packages and uploaded SBOM documents. Every backup is read back and checked as soon as it's written, and its SHA-256 checksum is published next to it so you can check a downloaded copy. A verified backup can be restored over the installation, or onto a new server in its setup wizard. Available on every license tier, to super admins; test restores need Enterprise.

The page has three tabs: Backups (the list, under a summary of the backup target, encryption and the latest test restore), Restores (every restore and how far it got) and Settings (backup target, encryption and test restores). Change in the summary opens Settings.

Screenshot needed

backups-list.png

Settings → Backups: the summary of target, encryption and latest test restore over the list of backups with status, size, Keep, expiry and actions

2. Take a backup

1. Open — Go to Settings → Backups and choose Take backup.
2. Options — Tick Keep permanently to stop the cleanup job from ever deleting it, and add an optional Note (for example "before upgrading to 1.4").
3. Wait — The backup runs in the background. Its row shows Running, then the result of its check (Checking, then Verified (level 3)). You can leave the page.

Only one backup runs at a time across all servers; starting another while one runs says so. A backup is cancelled if it runs longer than BACKUP_MAX_DURATION (6 hours).

3. The list of backups

The arrow at the start of a row opens its details: the SHA-256 checksum with a button to copy it, the kind and who took it, the note, where an uploaded backup came from, and the newest test restore. What a backup holds, under the list, folds out the notes on contents and the backup jobs.

4. How a backup is checked

Right after a backup is written, Depotex reads the whole file back from storage and checks it in three levels. Check again repeats the check at any time, for example after copying backups between storage locations.

1. Level 1 — checksum: the SHA-256 of the whole file matches the one recorded when it was written (and published in its .sha256 file).
2. Level 2 — structure and signature: the archive opens, its manifest is signed by this installation's backup key, and every file inside matches its own checksum.
3. Level 3 — database dump: pg_restore --list reads the database dump's table of contents.
4. Level 4 — test restore (Enterprise): the dump is loaded into a temporary database and every table's row count compared with the backup's. See Test restores.

A backup encrypted to public keys is checked up to level 2: the server doesn't hold the private key, so its dump is opened only when it's restored or test-restored with the key.

A backup that fails its check is marked Check failed with the reason, and super admins get a critical alert.

5. Download a backup and check it

Download saves the backup as a .dxbak file (a tar archive). Downloads are recorded in the audit log and need the backups:download permission, because a backup holds the whole database. Next to every backup, Depotex keeps a .sha256 file in sha256sum format; check a download against it:

curl -OJ -H "Authorization: Bearer $DEPOTEX_TOKEN" https://depotex.example.com/api/backups/$ID/download
curl -H "Authorization: Bearer $DEPOTEX_TOKEN" https://depotex.example.com/api/backups/$ID/checksum | sha256sum -c

Keep downloaded backups somewhere other than the installation's own storage, or set a separate backup target.

The archive holds a signed manifest.json (versions, checksums), files.json, the database dump db.dump (PostgreSQL custom format) and the platform files under files/; in an encrypted backup the dump and files are inside one encrypted payload.age instead. Settings and plugin secrets in the dump are encrypted with the installation's CONFIG_ENCRYPTION_KEY: keep that key with your backups, since a restore needs the same one.

6. Restore a backup

A restore replaces this installation's database and platform files with a backup's. Everyone is signed out, and every server shows a maintenance screen until it ends. Needs the backups:restore permission (super admins).

Screenshot needed

backups-restore-dialog.png

The Restore dialog: the last pre-checks, what happens, and the installation name and password that confirm it

1. Choose the backup — On Settings → Backups, choose Restore on a verified backup (level 3, or level 2 for one encrypted to public keys).
2. Read the checks — The dialog runs every pre-check (below) and says what will be replaced. Nothing changes yet. Restore stays off while a check fails.
3. Give the key — For an encrypted backup, paste the private key or load it from a file, or type the passphrase (optional when Depotex still holds it). The key is tried on the backup before anything stops.
4. Confirm — For a backup from another installation, tick that you want it anyway. Type the installation's name and your password, then Restore.
5. Wait — Every server shows the maintenance screen with the current step. When it ends, sign in again with an account from the backup.

Screenshot needed

backups-maintenance.png

The maintenance screen every server shows while a restore runs, with the current step

What the restore does, in order: every server stops taking requests (they answer 503 restore_in_progress) and pauses its jobs; a safety backup of the current database is taken; the backup is checked again and staged; the current database is set aside; the backup is loaded and brought up to this version; the platform files are written back (files added since the backup stay); signed-in sessions, OAuth tokens and plugin caches are reset, and people erased since the backup (GDPR) are erased again; then every server restarts on the restored database. API tokens from the backup keep working.

The Restores tab lists every restore (a running one with a bar of its steps) with its outcome. After a successful restore the previous database is kept for 24 hours (BACKUP_RESTORE_KEEP_PRIOR) in case you need it; Discard previous database frees the space sooner.

7. Encryption

Under Encryption on the Settings tab of Settings → Backups, switch on Encrypt new backups (off by default) to encrypt the database dump and platform files of every new backup. The manifest stays readable, so the list still shows what each backup is. Existing backups aren't changed.

Screenshot needed

backups-encryption.png

The Encryption section: Encrypt new backups, public keys or passphrase, and Generate a key pair

Generate a key pair makes a new age key pair in the browser's session: copy or download the private key and keep it safe, then tick that you stored it to add the public key. The private key is shown once and stored nowhere. You can also add a public key made with the age-keygen tool.

8. Add a backup from elsewhere

To restore a backup that isn't in the list (downloaded earlier, or from another installation), choose Add a backup at the top of Settings → Backups. Needs backups:restore.

Screenshot needed

backups-add-upload.png

The Add a backup dialog, Upload tab: choose a .dxbak file and, optionally, its expected SHA-256

• Upload: choose the .dxbak file and, optionally, paste its SHA-256 (or the line of its .sha256 file). The file goes up in 16 MiB pieces (BACKUP_UPLOAD_CHUNK_SIZE), each checked on arrival; pause and resume at any time, and if the connection drops, choosing the same file again carries on where it stopped. An unfinished upload is dropped after 24 hours (BACKUP_UPLOAD_EXPIRY).
• Import folder: for a file too large for the browser, an operator copies it into backups/import/ in the backup storage (with its .sha256 file if there is one). The Import folder tab lists the files there with what each one is; Check adds one to the list.

Screenshot needed

backups-add-import.png

The Add a backup dialog, Import folder tab: files with their version, date and state, and Check

Either way the backup is checked like any other, then offered for Restore. A backup from another installation shows Signed by another installation; restoring it needs your consent and the same CONFIG_ENCRYPTION_KEY. Uploaded and imported backups are never deleted by the cleanup job.

9. Disaster recovery

When the installation itself is lost, restore a backup onto a new server in one of two ways. Both need the backup's CONFIG_ENCRYPTION_KEY.

10. In the setup wizard

Start a new server as for a fresh installation and go through the setup wizard with the same license, database server and storage as before (a new, empty database). On the last step choose Restore from a backup instead of creating an administrator:

Screenshot needed

setup-restore-step.png

The setup wizard's last step with Restore from a backup: the chosen backup's summary, key field and consent box

1. Choose the backup — Upload the .dxbak file (sent in pieces; a broken connection resumes), or pick one already in backups/import/ of the storage you entered.
2. Check it — The wizard shows when and by which version it was made, and whether it's encrypted. It must have been made with this server's CONFIG_ENCRYPTION_KEY.
3. Key and consent — Give the key of an encrypted backup, tick that you want to restore it, and choose Complete.
4. Wait and sign in — The server restores the backup on its first start and then shows the sign-in page. Sign in with an administrator from the backup.

The wizard's license, storage, Redis and installation ID are kept; everything else (people, settings, data) is the backup's. If the restore fails, the server opens the wizard again with the reason; retry, or create an administrator instead. An uploaded backup waits on the setup server's disk (SETUP_UPLOAD_DIR, default ./data/setup-upload) until setup completes, so that disk needs room for it. A backup kept on a separate backup target must be uploaded or copied into the import folder of the installation's storage.

11. From the command line

On an installation that is already set up, restore a file without the web app. Stop every other server first: the command refuses while others are running, unless --restore-force.

# check only: prints every pre-check, changes nothing
CONFIG_ENCRYPTION_KEY=... ./server --restore-file /backups/depotex-2026-10-11.dxbak
# restore
CONFIG_ENCRYPTION_KEY=... ./server --restore-file /backups/depotex-2026-10-11.dxbak --yes

The command exits when it's done; start the servers normally afterwards. The first one to start finishes the restore (sessions reset, erasures replayed).

12. Backup target

By default backups are kept in the installation's own storage, under backups/, and Settings → Backups and the system check warn about it: losing the storage loses the backups too. On the Settings tab, under Backup target, choose A separate location (a local path shared by every server, Amazon S3, MinIO or Azure Blob Storage) for backups, checksum files, the import folder and uploads.

Screenshot needed

backups-target.png

The Backup target section: a separate S3 location with Test and Save, and the warning shown while the installation's storage is used

• Test checks that Depotex can write, read and delete there; Save tests again and writes a marker file, backups/.depotex-target. Every server checks that marker before writing, so a local path that isn't the same shared volume on every server is refused.
• An installation's file storage can't be a backup target. A location another installation uses asks you to take it over; one this installation used before becomes its target again, with its backups.
• Backups stay where they were written: one in another target is marked In another backup target, and can't be downloaded, checked or restored until that target is set again. Open uploads are dropped when the target changes.
• The platform files inside a backup still come from, and are restored to, the installation's storage.

13. Test restores

A test restore proves a backup really restores, without touching anything in use. Enterprise license; backups:manage. Choose Test restore in a verified backup's ⋯ menu (an encrypted one asks for its key): Depotex loads the dump into a temporary database on the same PostgreSQL server, compares every table's row count with the counts recorded when the backup was taken, and drops the temporary database. The row marks the newest result and opens on it, with any tables whose counts differ; the summary above the list shows the latest one.

Screenshot needed

backups-test-restore.png

A backup row with its test restore result: passed, tables and rows compared, duration

• The weekly Backup test restore job (backup-test-restore, Sundays at 04:00, BACKUP_TEST_RESTORE_SCHEDULE) tests the newest verified backup it can open. A failure alerts super admins, and the system check warns when the last one failed or none passed in 15 days.
• One test restore runs at a time across all servers. The database user needs CREATEDB, and the database server needs room for a second copy while it runs.
• Owners and permissions, and platform files, aren't tested; a real restore checks those in its pre-checks.
• Count rows for test restores (on by default) counts every table while each backup is taken. On a very large installation, switch it off to save a full read of the database per backup: test restores then check only that the dump loads. Backups made before row counting existed are tested the same way.

14. Scheduled backups and cleanup

Two jobs in Settings → Advanced → Scheduled jobs look after backups:

Switching a job on or off, or changing its schedule, applies on every server of a cluster within one tick of the job.

15. Backing up artifact storage

Artifacts are usually by far the largest part of an installation and change all the time, so Depotex leaves them to your storage platform, which can copy them incrementally. Back up the storage location set in Settings → Storage, and leave out the backups/ folder (it holds the Depotex backups themselves; copy those separately).

Take the Depotex backup and the storage backup close together in time: the database lists the artifacts the storage holds.

16. Permissions

No role holds them: super admins can do everything, and API tokens they create can be given these permissions for automation. Changing encryption, the backup target and row counting needs backups:manage.

17. Events, alerts and metrics

• Events backup.create, backup.update, backup.delete, backup.download, backup.restore, backup.upload, backup.settings.update, backup.target.update and backup.test_restore (before and after: policies and plugins can refuse them), backup.verify and backup.fail (after). See Events.
• A failed restore or test restore sends super admins a critical alert with the reason.
• System checks Backup target (warns while backups share the installation's storage, fails when the target can't be reached or its marker is wrong) and Test restores (Enterprise).
• A failed backup or check sends super admins a critical alert, "The scheduled backup failed its integrity check" or "couldn't be written", with the reason. The scheduler's own "job is failing" alert applies to the scheduled backup too.
• Prometheus metrics: depotex_backup_runs_total, depotex_backup_verifications_total, depotex_backup_duration_seconds, depotex_backup_last_size_bytes, depotex_backup_last_success_timestamp_seconds and depotex_backup_cleanup_deleted_total, depotex_backup_restore_runs_total, depotex_backup_restore_duration_seconds, depotex_backup_test_restore_runs_total and depotex_backup_test_restore_last_success_timestamp_seconds. Alert on the last success timestamps to catch backups or test restores that stopped.

18. When a backup fails

19. Configuration

Set on each server; schedules and retention saved in Scheduled jobs win over these.

On Kubernetes, the server pod's /tmp is where backups are staged: set backend.tmpSize in the Helm chart larger than a compressed dump of your database, or set BACKUP_TEMP_DIR to a larger volume. See Docker & Kubernetes.

20. API