Restore data

You restore on the server with sudo arcula restore. There is no restore wizard in the panel: the panel shows where a backup is saved and to what level it was checked.

General rules:

• Nothing existing is overwritten. If the path, volume or database already exists, the check fails, and arcula tells you what to do: move the old one aside, restore next to it, or extract it as files.
• Services are not started. Databases are started only temporarily, in a container without network. Starting services is your decision.
• Nothing changes until you confirm. First a readiness check and the plan, then the question “Run the plan? [y/N]”.

Wizard

sudo arcula restore

The wizard asks step by step:

1. “Restore from where?” — this server's storages or a recovery kit.
2. “Recovery point:” — which backup, the latest by default. Each one lists the storages that hold it.
3. “What do we do?” — the mode.
4. The component, or the paths and a directory.

Then a readiness check: restic, the storages and the backup, OS and architecture, Docker, disk space, conflicts with what already exists. Then the plan step by step and confirmation.

The wizard runs only when there are no flags. With flags, arcula checks and shows the plan right away. To only check and see the plan without changing anything, add --dry-run:

sudo arcula restore --mode component --component support/postgres --dry-run

If the restore was interrupted, continue from where it stopped. arcula prints the run ID when it breaks off:

sudo arcula restore --resume <id>

Restore a component

For example, a database as it was before a failed migration. In the wizard, choose “One component (component)” and the component from the list. Or with flags:

sudo arcula restore --mode component --component support/postgres

--component is the resource key, a path, a volume name, project/service or a database project. Another backup — --point (the ID or at least its first 8 characters), a storage — --from.

What you get:

• PostgreSQL database, service running. Each database is imported into a new one — <db>_restored_<date>_<time> — in the same container. The live database is not touched: compare the data and move what you need yourself.
• Database, service not running. A temporary container on its own volume. After the check it is stopped but not removed — you can look at the data.
• Directory or volume. To its original place. If the place is taken, the wizard asks for another directory; with flags — --target /srv/restore.

Extract files

When you need individual files: a config, user uploads. In the wizard, choose “Extract files (files)”: arcula shows the paths from the backup — enter numbers or paths, then a directory. With flags:

sudo arcula restore --mode files --path /opt/support/uploads --target /srv/restore

• --path can be repeated. A path as on the original server, volume NAME for a volume, or a path inside the backup (db/support/…).
• --target is an empty or new directory. Files land with their full path: /srv/restore/opt/support/uploads; volumes — in /srv/restore/volumes/<volume>.

Nothing on the server is overwritten: take what you need from the directory yourself.

Bring up a server on a clean machine

The server is lost and you need a new machine. The agent has no access to other servers' repositories, so another server can be brought up only with the recovery kit. The panel issues the kit: “Settings” → “Recovery without the panel” → “Recovery kit”.

On the new machine you need:

• arcula and restic 0.18.1. If the panel is alive, install them with the install line from “+ Server”, as in Connect a server. If there is no panel, see Restore without the panel.
• Docker Engine with Compose v2, if volumes and databases are restored. arcula doesn't install it.
• The recovery kit and its password.

What else this server will need — Vault unseal keys, the same GitLab version — the panel shows on the server: “Overview” → “Needed for a restore”.

Check the kit — whether it opens and the repositories are readable:

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

Start the wizard. The new machine has no access to the storages, so the wizard asks for the kit file right away, then its password:

sudo arcula restore

Or without the wizard: with --kit, arcula prepares the server (prepare) from the latest backup. It still shows the plan and asks for confirmation:

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

If the kit has several servers and the new machine's host name is different, name the server: --server prod-db-01.

prepare goes in order: users and groups with the original UIDs and GIDs, Compose project directories and files, service images, databases, volumes. Host settings — cron, services, proxy — are only extracted to /var/lib/arcula/restore/<id>/host: you turn them on yourself, after checking.

The report lists what is left for you in “Left for you to do”. Usually that's starting the projects:

cd /opt/support && docker compose up -d

Then cron and services from the extracted host settings, and DNS. You can connect the new machine to the panel later too: install.sh doesn't touch restored data.

Report and verification level

At the end arcula prints a report: which backup and from which storage, what was restored, what failed or was skipped, what is left for you to do. And the level — based only on what was actually checked:

Level 4 is possible only if the restore includes a PostgreSQL database. Level 5 — “project restored” — this version doesn't give: starting services is up to you.

The full report and steps are in /var/lib/arcula/journal/restore-<id>/run.json.

What the panel shows

If the server is connected to the panel, progress and the report go to the panel:

• while it runs — under the server name, “Restoring the backup as of … from “…”” and the stage;
• server → “Backups” → the “Restore” column: the level and date. Hover over it to see what exactly was checked and what is left for you. The “restored only” checkbox leaves only such backups in the list;
• server → “Log”, the “Restore” filter: “Restored: component”, “Restore failed” or “Restore cancelled” — with steps and log lines.

If the panel is unavailable, the restore still runs. The log will be sent later by the arcula-agent service or by sudo arcula restore --resume <id>.

On the server the same marks are shown by sudo arcula points, in the “Restore” column.