Backups

Back up your Docker volumes and Arcane’s own data (database, settings, runtime configuration), on demand or on a schedule, to local storage at /backups, an S3-compatible bucket, or both. Backups are encrypted Rustic snapshots. Before your first backup, set up storage and a recovery key.

Set up backup storage

Mount local storage

Local backups and pre-restore safety backups go to /backups in the Arcane container. Mount a host directory or a named volume there:

services:
  arcane:
    volumes:
      - /srv/arcane/backups:/backups

services:
  arcane:
    volumes:
      - arcane-backups:/backups

volumes:
  arcane-backups:

Removing a named volume deletes its backups. Without a /backups mount, Arcane uses a fallback volume named arcane-backups and warns in the UI; set ARCANE_BACKUP_VOLUME_NAME if that name collides. S3-only backups keep no permanent local copy.

Important

Backups on the same host don’t survive a disk or host failure. Use S3, or copy the Rustic repository under /backups to another system.

Add an S3 destination

1. Open System → Backups → S3 Destinations.
2. Enter the connection details (see S3 destination fields).
3. Test the destination. Create and Save need a passing test (write, download, verify, delete a temporary object).
4. Save.

Destinations sync from the manager to all remote environments. After changing the endpoint, bucket, region, access key ID, SSL, or path-style setting, re-enter the secret access key and test again. You can’t delete a destination a schedule or retained remote backup still uses.

Recovery key

The recovery key encrypts system and volume backups. Without it, snapshots can’t be restored.

1. Open System → Backups → Recovery key and choose Create recovery key. Arcane generates a key of 8 groups of 6 characters.
2. Copy the key and store it outside Arcane. It isn’t shown again.
3. Confirm the key to save it.

Arcane keeps a copy for scheduled jobs. Import recovery key uses a key from another installation; Reset recovery key replaces it.

Warning

Losing the recovery key makes the snapshots unrecoverable. Arcane refuses to reset the key while system backups made with the current key still exist, because they can only be opened with the key that created them.

Volume backups made before any recovery key use a password derived from ARCANE_ENCRYPTION_KEY. Setting a recovery key makes Arcane try to move its existing volume repositories to the new key; another instance’s repositories must be moved by that instance.

Warning

Keep your original ARCANE_ENCRYPTION_KEY until you’ve confirmed older volume backups open with the recovery key. A recovery key imported on a fresh installation can’t unlock a repository that still uses the old password.

Volume backups

Open a volume and select its Backups tab. See also Volumes.

Create a backup

Click Create Backup for a local backup, or use its dropdown to choose Local, S3, or Local + S3 (S3 options ask for a saved destination). The table shows each run’s trigger, destination, size, time, and status. Failed runs show their error and can’t be restored. Only one backup, upload, or delete runs on a volume at a time. A successful backup’s row actions let you Upload to S3 (making it Local + S3) or download it as a tar.gz archive.

Schedule backups

Click Add schedule. A volume can have several schedules:

Setting	What it does
Enabled	Turns the schedule on or off.
Schedule	Five-field cron expression in Arcane’s configured timezone. 0 2 * * * runs daily at 02:00.
Backups to keep	How many restore points to keep, 0 to 3650. 0 keeps all of them.
Destination	Local, S3, or Local + S3. If S3 is included, also pick the S3 destination.
Stop containers during backup	Stops running containers that use the volume, takes the snapshot, then starts them again.

Turn on Stop containers during backup for apps that write constantly, such as databases, or the restore point may be inconsistent. Leaving it off avoids downtime. On-demand Create Backup never stops containers. Scheduled and on-demand runs appear in the same table and the Activity Center.

Choose when to back up a volume, how many snapshots to keep, and where to store them.

×

Choose when to back up a volume, how many snapshots to keep, and where to store them.

Restore a volume

Restore the whole volume or selected files. For an existing volume, Arcane stops its containers and takes a local safety backup first (if that fails, the restore is cancelled), then restarts every container it stopped. A whole-volume restore deletes files not in the snapshot. If a restore fails partway, roll back with the safety backup. Restoring to a volume that doesn’t exist creates it, with no safety backup.

Delete backups and retention

Retention runs per schedule, and separately for local and S3 copies. Expired restore points lose their local and S3 snapshots where possible.

Manual deletes also try every stored copy. If local deletion succeeds but S3 fails, the row stays as S3-only with the error. If any remote copy can’t be deleted, the row stays. Disk space returns slowly, up to two days. Arcane prunes local system and volume repositories at 04:15 and 16:15 daily (configured timezone), and Rustic keeps deleted data about a day before a prune removes it.

System-managed volume backups

To back up many volumes with one schedule, an admin opens System → Backups, clicks Create schedule, and chooses Volume. Set schedule, retention, destination, and stop-containers as above, then pick volumes:

Mode	Included volumes
All volumes	Every current and future volume, except Arcane’s internal ones.
Allowlist	Only the selected volumes. New volumes are left out until you select them.
Blocklist	Every volume except the selected ones. New volumes are included automatically.

Each run reads Docker’s current volume list. Ignore anonymous volumes skips unnamed ones. Run now reports matched, successful, failed, and skipped volumes. Results appear in each volume’s Backups tab as System-managed, next to Volume-managed backups.

Back up Arcane itself

System backups save Arcane’s application data and runtime configuration to recover the whole installation. They need SQLite, Arcane in Docker with /app/data mounted, local Docker daemon access, and a recovery key.

Create and schedule system backups

As an admin, open System → Backups, click Create schedule, and choose System. Set its cron expression, destination (Local, S3, or Local + S3), S3 destination, and retention. For a one-off backup, reuse a saved schedule’s configuration or pick a destination. Local backups can be uploaded to S3 later. If one copy of a Local + S3 backup can’t be read, restores and file browsing use the other.

Restore Arcane

Caution

A system restore replaces Arcane’s current database, users, settings, destinations, secrets, and other application data with the selected restore point.

1. Arcane creates and records a local safety backup.
2. A detached recovery helper stops the Arcane container.
3. Rustic restores the snapshot into /app/data.
4. The helper recreates Arcane with the recovered runtime configuration.
5. Arcane starts, and the backup and Activity Center records are finalized. The page disconnects meanwhile; reload once the container is back.

Restore selected project files

1. Choose Restore files from a successful backup’s row menu.
2. If no recovery key is stored, enter it and click Load files.
3. Select project files or folders, or use Select all, and restore.

Arcane first takes a full local safety backup; containers keep running. Selected files overwrite those paths, and a restored folder loses files not in the snapshot. If any file fails, restored files are rolled back. Database, settings, and secrets need a full system restore. Browsing needs system-backups:read and restoring needs system-backups:restore; both are admin-only.

Recover backups on another installation

1. Import the original key under System → Backups → Recovery key → Import recovery key.
2. Add the S3 destination with the same bucket and object prefix.
3. Open System → Backups to see the restore points Arcane found.

With a recovery key stored, Arcane searches each instance directory in the destination for decryptable system and volume snapshots whenever you save an S3 destination or open the Backups page. A failure in one directory doesn’t stop the others. Find S3 backups runs the same search on demand for system backups.

Reference

S3 destination fields

Field	Notes
Name	Display name.
Endpoint URL	The S3 or S3-compatible endpoint.
Bucket	Bucket that holds the backups.
Region	Required for AWS S3. Can be empty for endpoints that don’t need one.
Access key and secret key	Credentials for the bucket.
Object prefix	Optional path inside the bucket.
SSL and path-style access	Connection options for S3-compatible services.

Environment variables

Variable	Default	Purpose
ARCANE_BACKUP_VOLUME_NAME	arcane-backups	Name of the fallback volume used when /backups isn’t mounted. Doesn’t affect bind mounts or S3.