Backups

OpenFault backs itself up to any S3-compatible bucket: Cloudflare R2, AWS S3, MinIO and the like. Set it up in Settings → Backups (admins only) or in step 3 of the setup wizard.

What’s in a backup

Everything. OpenFault keeps all its state in one SQLite file, /data/openfault.db: issues, events, projects, members, teams, tokens, settings and uploaded source maps. A backup is a consistent snapshot of that file, compressed with zstd.

The snapshot is taken online, so the server keeps accepting events while it runs.

Settings

Field	Default	Notes
Endpoint	empty	Empty means AWS: `https://s3.<region>.amazonaws.com`.
Region	`us-east-1`
Bucket		Required.
Prefix	empty	Folder inside the bucket, for example `openfault`.
Access key / Secret key		The secret is never shown again after saving. Leave it blank to keep the stored one.
Hour (UTC)	`3`	When the daily backup runs, `0`–`23`.
Keep	`14`	How many backups to keep. Older ones are deleted after each successful upload.
Path-style URLs	on	`<endpoint>/<bucket>/<key>` instead of `<bucket>.<host>`. R2 and MinIO need it.

Presets fill in Amazon S3 for each region, and Cloudflare R2.

Cloudflare R2

Endpoint: https://<account-id>.r2.cloudflarestorage.com
Region: auto
Path-style: on

Create an R2 API token with Object Read & Write on the bucket and use its access key and secret.

Environment overrides

Env vars win over the stored settings, field by field. Setting the bucket also turns backups on and makes the form read-only.

Variable	Field
`OPENFAULT_BACKUP_S3_ENDPOINT`	Endpoint
`OPENFAULT_BACKUP_S3_REGION`	Region
`OPENFAULT_BACKUP_S3_BUCKET`	Bucket (also turns backups on)
`OPENFAULT_BACKUP_S3_PREFIX`	Prefix
`OPENFAULT_BACKUP_S3_ACCESS_KEY`	Access key
`OPENFAULT_BACKUP_S3_SECRET_KEY`	Secret key
`OPENFAULT_BACKUP_S3_HOUR`	Hour (UTC)
`OPENFAULT_BACKUP_S3_KEEP`	Keep

Schedule and buttons

Once a day at the set hour, OpenFault uploads <prefix>/openfault-<YYYYMMDDTHHMMSSZ>.db.zst, then deletes all but the newest keep backups.

Test connection writes a marker object to the bucket and deletes it again. Use it before you rely on the settings.
Back up now runs one backup straight away. The page waits up to 30 seconds. A bigger backup keeps running in the background; check the log.

Run log

Every run is logged. The Backups page shows the last 20 runs (time, key, size, result) and calls out any failures since the last good one.

CLI

The CLI uses the same data directory (OPENFAULT_DATA) and the settings saved in the database, or the env vars.

openfault backup now    # run one backup, print its key
openfault backup list   # list backups: key, bytes

Restore

openfault restore <key> (or s3://bucket/key) downloads a backup, decompresses it, checks its integrity and writes it to <data>/openfault.db. The database it replaces is kept as openfault.db.pre-restore-<time>.

It reads credentials from env vars only, since the database being replaced may be gone. The Backups page shows the exact command for the latest backup.

Stop the server. restore refuses to run while /healthz answers.
Set the OPENFAULT_BACKUP_S3_* env vars.
Run openfault restore <key>.
Start the server.

With Docker Compose:

docker compose stop openfault
docker compose run --rm \
  -e OPENFAULT_BACKUP_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com \
  -e OPENFAULT_BACKUP_S3_REGION=auto \
  -e OPENFAULT_BACKUP_S3_BUCKET=openfault-backups \
  -e OPENFAULT_BACKUP_S3_ACCESS_KEY=... \
  -e OPENFAULT_BACKUP_S3_SECRET_KEY=... \
  openfault restore openfault/openfault-20261020T030000Z.db.zst
docker compose start openfault

Limits

Uploads are a single PUT, so a backup can be at most 5 GB compressed. Bigger ones fail with a clear error in the log.
Listing and pruning read only the first 1000 keys under the prefix. Keep keep well below that, and give OpenFault its own prefix.