arculaDocumentation

Restore

Restore without the panel

Backups are ordinary restic repositories in your S3. You can bring them up without the panel, without a subscription and without our API: you need the recovery kit. While there is no panel, the other servers keep backing up on their own schedules: each server keeps its plan.

Recovery kit

The kit is the file arcula-recovery-kit-<date>.age: storage addresses, S3 keys and restic repository passwords of all servers, including disconnected ones whose backups are still there. The file is encrypted with a password you set when it's issued. The panel master key, the panel settings and the Vault unseal keys are not in the kit.

To download it: panel → “Settings” → “Recovery without the panel” → “Recovery kit” → “Download”. You'll need the panel password and a new password for the file.

Keep the kit offline: the file — on your own computer in a protected folder, the file password — in a password manager. Not on the servers and not in the backup storages: the kit is needed exactly when they are gone. If storages or keys change, the panel will remind you to save the kit again.

Check the kit from time to time. Root is not needed; any Linux machine with arcula and restic will do:

arcula kit verify ./arcula-recovery-kit-2026-10-24.age

The command opens the kit and, for every repository of every server, reads the list of snapshots and the manifest of the latest backup. It changes nothing. If everything is fine — “Emergency access is set up: the kit opens, all repositories are readable.” The result is shown only in the terminal; it isn't sent to the panel.

Where to get arcula without the panel

There's nowhere to get install.sh from, so install by hand:

  • arcula — from any live server (/usr/local/bin/arcula) or from the release directory downloads/arcula/<version>/linux-<arch>, checked against SHA256SUMS;
  • restic 0.18.1 — from GitHub or from the release;
  • Docker Engine and Compose v2 — if volumes and databases are restored.

For example, on amd64:

scp live-server:/usr/local/bin/arcula .
sudo install -m 0755 arcula /usr/local/bin/arcula
curl -fsSLO https://github.com/restic/restic/releases/download/v0.18.1/restic_0.18.1_linux_amd64.bz2
bunzip2 restic_0.18.1_linux_amd64.bz2
sudo install -d -m 0700 /var/lib/arcula
sudo install -D -m 0755 restic_0.18.1_linux_amd64 /var/lib/arcula/bin/restic

Restore with the kit

arcula kit verify ./arcula-recovery-kit-2026-10-24.age
sudo arcula restore --kit ./arcula-recovery-kit-2026-10-24.age

With --kit, arcula runs without the wizard: it prepares the server (prepare) from the latest backup, shows the plan and waits for confirmation. It asks for the kit password without echo. If you need a component or files, add --mode component --component … or --mode files --path … --target …. For the step-by-step wizard, run sudo arcula restore without flags: on a machine without access to the storages it asks for the kit file itself.

  • --server NAME — which server from the kit. Not needed if the kit has one server or the host name matches.
  • --from NAME — the storage. Without it — the first one that has the backup.
  • --password-file FILE — the kit password from a file, for scripts.

Services are not started. More on the modes and the report — Restore data.

Plain restic by hand

Without arcula, restic itself can bring up the data. The kit is an age file with a password; decrypt it:

age -d arcula-recovery-kit-2026-10-24.age > kit.json

In kit.json, each server's repositories hold the repository address (repository) and its password (repository_password). The S3 key and region are in the storage, under storages. If the storage has its own key for each server, the key is in the server's repository.

export RESTIC_REPOSITORY='<repository from the kit>'
export RESTIC_PASSWORD='<repository_password from the kit>'
export AWS_ACCESS_KEY_ID='…'
export AWS_SECRET_ACCESS_KEY='…'
export AWS_DEFAULT_REGION='…'
restic snapshots
restic restore latest --target /srv/restore

Inside a backup:

  • /arcula-manifest.json — what is included and in what order to bring it up;
  • /db/<project>/<service>/ — database dumps (pg_dump -Fc of each database and globals.sql), the Vault snapshot, the GitLab archive;
  • /files/<path> — directories;
  • /volumes/<volume> — Docker volumes;
  • /host/<path> — host settings.

A database is brought up from its dump with pg_restore into PostgreSQL of the same version. When you're done, delete kit.json — it holds all the keys:

shred -u kit.json

On a live server you don't need the kit: access to this server's repositories is in /etc/arcula/repos/. As root:

set -a; . /etc/arcula/repos/<storage id>.env; set +a
/var/lib/arcula/bin/restic snapshots

Panel and Vault on the same server

The panel takes its settings from Vault on the same server, so it won't start without Vault. If such a server is lost, the order is: Vault first, then the panel. No extra changes are needed for this.

You'll need the kit and its password, the panel master key from the password manager, and the Vault unseal keys.

1. New machine

Install arcula, restic and Docker as above, and check the kit:

arcula kit verify ./arcula-recovery-kit-2026-10-24.age

2. Server data

sudo arcula restore --kit ./arcula-recovery-kit-2026-10-24.age --server <panel server>

One prepare run brings everything back at once: project directories, volumes, Vault data and the panel's PostgreSQL database from the dump. arcula doesn't start services — start them yourself, in order.

3. Vault first

  • If Vault was copied as files, the data is already in place. Start Vault and unseal it with the original unseal keys.
  • If Vault was backed up as a Raft snapshot, the snapshot is extracted to /var/lib/arcula/restore/<id>/vault. Restore it as in Vault: Raft snapshots.

Check vault status and that the panel's secrets are in place.

4. Then the panel

  1. The master key — from the password manager: a file with 0600 permissions at the path from ARCULA_MASTER_KEY_FILE, or the ARCULA_MASTER_KEY variable.
  2. Settings — from the restored Vault.
  3. Start the panel: docker compose up -d in its directory.
  4. The panel's static web files — from the release's web-<version>.tar.gz, if their directory wasn't in the plan. The Caddy settings on the host are extracted to /var/lib/arcula/restore/<id>/host. Then DNS.
  5. Check https://<domain>/api/web/v1/health and sign in to the panel.

The agents of the other servers will reconnect on their own and send the logs collected while there was no panel.

The same article is in the panel, under “Help”.