Backup & restore

OpsNexus has two ways to back up:

• Settings → Backup & restore: platform backups made by OpsNexus itself. They hold every table, can include secret values, and can be encrypted and copied off-site. Restore them from the same page.
• scripts/backup.sh: a database dump plus an archive of the bundled Vault's data, for the Docker Compose stack.

#Who can use it

Backups contain every organization's data, so only super admins can create, download or restore them. A super admin also needs Full access on Backup & restore, which super admins always have. Other users see a "Super admins only" message on the page.

The first admin created at install time is a super admin.

#What a platform backup contains

A backup is one file named opsnexus-YYYYmmdd-HHMMSS.onxbak. Inside is a gzip'd tar with:

• manifest.json: OpsNexus version, database schema revision, creation time and the row count of each table.
• One JSON-lines file per database table: users, roles, projects, pipelines, builds, settings, dashboards, the audit log and everything else.
• secrets.json: the secret values from the secret store, only when you turn on Include secret values.

These are left out:

• The backup history and backup settings themselves.
• Metrics history (agent_metrics and domain_checks), unless Include metrics history is on. These tables can be large.
• Files on disk, such as pipeline artifacts in the artifacts volume.

#Encryption

When a passphrase is set, the file is encrypted with a key derived from it (PBKDF2-SHA256, then Fernet: AES-128-CBC with HMAC). Without a passphrase, the file is a plain archive.

Secret values can only be included in an encrypted backup. If no passphrase is set, Include secret values fails with a message asking you to set one.

#Set up automatic backups

1. Open Settings → Backup & restore.
2. In Schedule & encryption, set:
   • Automatic backups: Off, Daily or Weekly (Monday).
   • At hour (UTC): 0 to 23. The default is 2.
   • Keep last: how many completed backups to keep, 1 to 365. The default is 14. Older backup files are deleted.
   • Include metrics history: on or off.
   • Encryption passphrase: at least 12 characters. Once set, the field becomes New passphrase (leave empty to keep).
3. Select Save.

The card shows the next run. The scheduler checks every 10 minutes whether a scheduled backup is due. If a scheduled backup fails, OpsNexus sends a high-severity notification titled "Scheduled backup failed".

Scheduled backups don't include secret values. To include them, use Back up now with Include secret values on.

The tiles at the top show the Last backup, Backups kept, Automatic backups and Encryption state.

#Back up now

1. Optionally turn on Include secret values.
2. Select Back up now.

The backup appears in the Backups table with its type (manual, scheduled or pre-restore), size, contents (Encrypted or Not encrypted, Secrets, Metrics), copies and status.

#Where backups are stored

Every backup is written to the server disk first, in BACKUP_DIR. The default is /app/backups inside the API container. Docker Compose mounts the backups volume there, so files survive container rebuilds.

To list the files on the host:

docker compose exec api ls -l /app/backups

Select Download in the Backups table to save a copy.

#Off-site copies

In Off-site copies (optional), fill in one or both destinations, then select Save under Schedule & encryption. Each new backup is then also uploaded to them.

S3 uploads use server-side encryption (AES256). The S3 secret key, Azure SAS token and backup passphrase are kept in the secret store, not in the database.

If an upload fails, the local copy is still kept and the Copies column shows the error. Keep last pruning only deletes files on the server disk. Manage retention of off-site copies with your bucket or container lifecycle rules.

#Restore a backup

1. In the Backups table, select Restore on a backup. To restore a file from elsewhere, select Restore from file… and pick an .onxbak file.
2. Enter the Backup passphrase. For a backup stored on the server, leave it empty to use the configured passphrase.
3. Type RESTORE in Type RESTORE to confirm.
4. Select Replace all data.

What happens:

1. OpsNexus checks the file and its passphrase.
2. It refuses a backup from a different database schema revision. Restore it on the matching OpsNexus version, then upgrade.
3. It takes a safety backup of the current state, of type pre-restore. Pre-restore backups are not removed by Keep last.
4. It replaces every table in one transaction. If anything fails, nothing changes.
5. If the backup includes secret values, it writes them back to the secret store.

When it finishes, the page shows the name of the safety backup. Sign in again if asked: user sessions are part of the restored data.

The restore is written to the audit table as backup.restore. Because a restore affects every organization, that entry isn't tied to one organization, so it doesn't show on the Audit logs page. Creating, downloading and configuring backups are recorded as backup.create, backup.download and backup.config.update.

#Database-level backups with the scripts

For the Docker Compose stack, scripts/backup.sh makes a PostgreSQL dump and an archive of the bundled Vault's data:

./scripts/backup.sh
# or
make backup

It writes two files to ./backups on the host:

backups/opsnexus-YYYYmmdd-HHMMSS.sql.gz
backups/vault-YYYYmmdd-HHMMSS.tar.gz

The dump is made with pg_dump --clean --if-exists, using POSTGRES_USER and POSTGRES_DB from .env.

To restore a database dump:

./scripts/restore.sh backups/opsnexus-YYYYmmdd-HHMMSS.sql.gz

The script asks you to type restore, stops api, worker and scheduler, loads the dump with psql, then starts them again. It doesn't restore the Vault archive.

#Recommendations

• Set a passphrase and turn on daily automatic backups.
• Add at least one off-site copy.
• Back up Vault as well, or include secret values in a manual encrypted backup.
• Test a restore on a separate installation of the same version.
• For production, use managed PostgreSQL with automated backups and point-in-time recovery. See Production.

#Related pages

• Upgrading
• Secrets & variables
• System status