Automatic backups
Production Docker Compose runs an automatic full backup every 24 hours, starting five minutes after startup. Configure the schedule and retention in Cockpit → Backups → Backup settings. To keep offsite copies, enable Cloudflare R2 under Cockpit → Integrations.
What a backup includes
Cockpit creates two kinds of backups:
- Database-only backup: A single SQLite online snapshot (
.db). - Full backup: A
.ziparchive with amanifest.jsonand four parts:- SQLite online snapshot (
stellarr.db) - Uploaded objects (
objects/) - Data-protection keys (
keys/) - Instance files (
secrets/,tls/,releases/)
- SQLite online snapshot (
IMPORTANT
Automatic backups always create full backups and fail if any referenced upload is missing. Because .env is never stored inside archives, keep a separate copy of .env alongside your backups.
Schedule and configuration
- Cockpit: Changes under Backups → Backup settings apply within one minute without a restart. Updating the policy requires a fresh second factor if MFA is enabled on the owner account. Use Restore deployment defaults to fall back to
.env. - Environment defaults: Set defaults in
.envand rundocker compose up -d. Direct API deployments opt in withBackups__Enabled=true.
STELLARR_BACKUP_ENABLED=true
STELLARR_BACKUP_INTERVAL_HOURS=24
STELLARR_BACKUP_RETRY_MINUTES=15
STELLARR_BACKUP_INITIAL_DELAY_MINUTES=5How the scheduler works:
- Intervals run in UTC from the last successful completion, not on a wall-clock cron. A missed run triggers once after restart without catching up skipped cycles.
- Manual and scheduled backups share one lock, so a manual run defers the scheduled job. Automatic entries appear in the audit log under the owner account tagged
[automatic]. - With an offsite destination enabled, a cycle succeeds only after the offsite upload also finishes. Failed uploads retry the same local
.zipat the retry interval (tracked in${DataRoot}/automatic-backup.json). - Stellarr does not send email alerts on backup failure. Monitor Cockpit → Backups (and container logs) or watch completion timestamps externally.
- Run only one API process per
/data/stellarrvolume so the process-local lock stays exclusive.
Restoring a backup
The operator CLI restores full backups automatically. Test restores periodically on an isolated instance before relying on them.
Copy the archive into
/data/stellarr/backups/if Cockpit does not already list it. For archives downloaded from R2, verify the SHA-256 against the remotesha256metadata first:bashdocker compose cp ./backup-20261114-030000-<id>.zip stellarr:/data/stellarr/backups/Stage the restore. The CLI checks
manifest.json, entry paths, SQLite integrity, and every entry's CRC-32 and size, then copies the archive torestore/staged.zip:bashdocker compose exec stellarr stellarr backup restore backup-20261114-030000-<id>.zip --yesRestart the container. Before services start, the entrypoint replaces
db/,files/,keys/,secrets/,tls/, andreleases/, moving the old folders torestore/previous-<time>/:bashdocker compose restart stellarr(
logs/,backups/, andautomatic-backup.jsonare preserved.)Verify owner login, message history, downloads, avatars, integrations, and creating a fresh backup. Delete
restore/previous-<time>/once verified; moving those folders back undoes the restore.
Restore safeguards
| Behavior | Detail |
|---|---|
| Status record | restore/last-restore.json logs what the last container start did. |
| Cancel before restart | Run docker compose exec stellarr stellarr backup cancel. |
| Corrupted staged archive | Live data stays untouched, the archive moves to restore/refused-<time>.zip, and the container boots normally. |
| Interrupted folder swap | If rollback also fails, startup creates restore/broken and refuses to boot until you repair the volume and delete that marker. |
| Disk space | /data/stellarr needs room for live data, restore/staged.zip, and unpacked files at once. previous-* and refused-* files are not auto-pruned. |
| Sub-mounts | Automatic restore refuses if subdirectories such as files/ are separate mounts. Restore manually instead. |
| Version match | Restore onto the same Stellarr release that wrote the backup. |
Restoring a partial or database-only backup
A standalone .db file or an archive missing any of the four full-backup parts must be restored manually with the container stopped:
- Stop the container (
docker compose stop) and keep a copy of/data/stellarr. - Place the
.dbfile atdb/stellarr.dband remove any leftoverdb/stellarr.db-walordb/stellarr.db-shm. - Copy
keys/alongside the database so encrypted TOTP seeds and Cockpit secrets remain readable. - Copy
objects/intofiles/, keeping relative paths. - Copy
instance/into/data/stellarr/, keeping relative paths, and keepsecrets/andtls/readable by owner only. - Start the container (
docker compose start) and verify data and login.
Consistency and recovery expectations
- SQLite uses an online snapshot taken before listing objects. Files uploaded mid-backup are not covered by a cross-system transaction, and missing referenced objects are recorded in
manifest.json(and rejected for automatic backups). - Entry CRC-32 and uncompressed sizes are checked both during staging and while unpacking at startup.
- A 24-hour interval gives roughly a 24-hour maximum data-loss window (plus backup duration). Measure actual recovery time during a test drill.