Skip to content

Backups

Back up Docker volumes and Arcane itself to local storage or S3-compatible storage.

Before your first backup, set up storage and a recovery key. Backups are encrypted Rustic snapshots. They can go to local storage at /backups, an S3-compatible bucket, or both.

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

Host directory:

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

Named volume:

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. If that name collides, set ARCANE_BACKUP_VOLUME_NAME.
  • S3-only backups keep no permanent local copy.
  1. Open System → Backups → S3 Destinations.
  2. Enter the connection details. See S3 destination fields.
  3. Test the destination. The test writes, downloads, verifies, and deletes a temporary object. Create and Save need a passing test.
  4. Save.
  • Destinations sync from the manager to all remote agents.
  • 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 that a schedule or retained remote backup still uses.

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.

Volume backups made before any recovery key use a password derived from ARCANE_ENCRYPTION_KEY.

  • When you set a recovery key, Arcane tries to move its existing volume repositories to the new key.
  • Another instance’s repositories must be moved by that instance.

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

Pick one:

  • Local backup: click Create Backup.
  • Choose a destination:
    1. Open the Create Backup dropdown.
    2. Choose Local, S3, or Local + S3.
    3. For an S3 option, pick 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.
  1. Click Add schedule.
  2. Fill in the settings below.
  3. Save. A volume can have several schedules.
A volume backup schedule: when, how many to keep, and where.
A volume backup schedule set for 2 AM with seven backups retained.A volume backup schedule set for 2 AM with seven backups retained.

A volume backup schedule: when, how many to keep, and where.

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. Otherwise 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 in the Activity Center.
  1. Open the volume and select its Backups tab.
  2. Find a successful backup and open its row menu.
  3. Click Restore for the whole volume, or Restore files to pick files.
  4. Read the Restore Volume warning. It lists any containers Arcane will stop.
  5. Click Restore to confirm.
  • A whole-volume restore deletes files that aren’t 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.

For an existing volume, Arcane:

  1. Stops the volume’s containers.
  2. Takes a local safety backup. If that fails, the restore is cancelled.
  3. Restores the snapshot.
  4. Restarts every container it stopped.

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 comes back slowly, up to two days later:

  • Arcane prunes local system and volume repositories twice a day, in the 04:00 and 16:00 hours of the configured timezone. The exact minute differs per installation.
  • Rustic keeps deleted data about a day before a prune removes it.

Backups that no schedule manages anymore are deleted after a retention window:

  • Backups of a removed volume or a deleted schedule, counted from when they stopped being managed.
  • Safety backups taken before a restore, counted from when they were made.
  • System backups a manager started on a remote agent, counted from when they were made.

Set the window per agent with Unmanaged Backup Retention (days) under Settings → Storage & Limits, or with ARCANE_UNMANAGED_BACKUP_RETENTION_DAYS. New installs default to 7. Installs upgraded from before this setting start at 0, which keeps these backups forever. Cleanup runs twice a day and removes the S3 copies too. System backups are only cleaned up when a recovery key is set.

To back up many volumes with one schedule (admin only):

  1. Open System → Backups and click Create schedule.
  2. Choose Volume.
  3. Set schedule, retention, destination, and stop-containers, as for volume schedules.
  4. Pick a mode, and select volumes if needed:
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 volumes.
  • 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.

System backups save Arcane’s application data and runtime configuration, so you can recover the whole installation.

Requirements:

  • SQLite.
  • Arcane running in Docker, with /app/data mounted.
  • Local Docker daemon access.
  • A recovery key.
  1. As an admin, open System → Backups and click Create schedule.
  2. Choose System.
  3. Set the cron expression, destination (Local, S3, or Local + S3), S3 destination, and retention.
  4. Save.
  • 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.

Each system backup on the manager also starts one on every connected remote agent, with the same destination. Agents store their own data and projects:

Destination Where an agent’s backup goes
Local /backups on the agent host.
S3 arcane-environment-recovery/<instance ID> under the object prefix.
  • Agent backups are listed under System → Backups with their agent.
  • An agent that is offline is skipped. The Activity Center shows it as failed, and the manager’s backup still succeeds.
  • Agent backups show the Manager trigger.
  • The schedule’s retention count applies to the manager only. Agent backups are deleted after the Unmanaged Backup Retention window on that agent, and kept forever when it is 0.
  • An agent’s backup supports Restore files, Upload to S3, and Delete. A full Restore is manager-only.
  • Only the agent that made a backup can restore from it. A replacement agent can’t import one.

Each agent encrypts with its own key, derived from your recovery key and the agent ID. The agent stores that key, so its backups never ask for one.

  • Resetting the recovery key moves each agent to its new key at the next system backup.
  • The first system backup also moves the agent’s existing volume backups to its key.
  1. As an admin, open System → Backups.
  2. Find a successful System backup and open its row menu.
  3. Click Restore.
  4. Read the Restore Arcane warning. If no recovery key is stored, enter it.
  5. Click Confirm.
  6. The page disconnects. Reload once the container is back.
  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.
  1. From a successful backup’s row menu, choose Restore files.
  2. If no recovery key is stored, enter it and click Load files. Remote agent backups skip this step.
  3. Select project files or folders, or use Select all.
  4. Restore.
  • Arcane first takes a full local safety backup. Containers keep running.
  • Selected files overwrite those paths. A restored folder loses files that aren’t in the snapshot.
  • If any file fails, restored files are rolled back.
  • Files from a remote agent’s backup are restored on that agent.
  • Database, settings, and secrets need a full system restore.
  • Browsing needs system-backups:read. Restoring needs system-backups:restore. Both are admin-only.
  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 system and volume snapshots it can decrypt.

  • The search runs 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.
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.
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.