Backups and the registry's calendar

An archive is one directory: the registry and the linkage store, the registry’s configuration, and a manifest naming every file with its size and digest. The key store is never in an archive. Copy it on its own, or keep its passphrase and make it again with nils key add NAME, because a registry restored without its key cannot give a subject the same code again. The desk’s Keys panel on Backups makes it again too, for an admin.

Back up now

nils backup --keep 14 --rehearse

With no --dir the archive goes to the backup place the registry’s place names, else backups in the registry’s directory. --keep N keeps the newest N archives of this registry in that directory and removes the others. A directory that holds another registry’s archive, or no manifest, is never removed, and with --rehearse nothing is removed unless the new archive passes.

--rehearse rehearses a restore without applying it: every file is checked against the manifest, and every store is opened as a restore would open it, a SQLite store read only with its integrity checked, a Postgres dump read back by pg_restore --list.

From the desk, Settings, Backups does the same with one button. At the door it is a job:

curl -X POST http://127.0.0.1:8437/api/jobs \
  -H 'content-type: application/json' \
  -d '{"command": ["backup", "--keep", "14", "--rehearse"]}'

On a schedule

With work on Backups, the schedule is set on the desk’s Backups page, or at the door:

curl -X PUT http://127.0.0.1:8437/api/backups/schedule \
  -H 'content-type: application/json' \
  -d '{"every": "day", "at": "02:00", "keep": 14}'

every is off, day or week, and a week names its day, such as sunday. The time is read in the registry’s timezone, so every day at 02:00 is two in the morning where the registry is, whatever the host’s clock says. The schedule is kept in the registry, so it moves with a restore.

nils serve with --backup-dir and --worker queues a backup each time the schedule comes round, rehearsed and kept to the number. A machine that was off at the hour queues one backup when it is back, not one for every hour it missed, and a scheduled backup waits while another backup is queued or running.

GET /api/backups lists the archives, newest first, each with its size, how long it took, whether it is this registry’s and its last check, and says when the schedule next comes round.

The folder the archives go to is the engine’s --backup-dir. From the desk, a person with work on the install gives the engine one, or another one, on Settings, Backups: the supervisor writes the engine’s service again with it and starts the engine alone again.

Check an archive later

nils verify /srv/nils/backups/3f9c2a1b-20260913020000 --rehearse

The outcome of every check is kept beside the manifest, in checked.json, and the list of archives shows it.

The registry’s calendar

Every answer with a date is read in the registry’s timezone, and a week starts on the registry’s day, never the browser’s:

nils settings set timezone Europe/Stockholm
nils settings set week_start sunday

The desk’s Backups page, and PUT /api/settings, change the same two. A timezone the engine does not know is refused, a change is audited, and the epoch moves, since a dated answer may change with it.

Restore

nils restore /srv/nils/backups/3f9c2a1b-20260913020000 --yes

Stop nils serve first. The archive is verified, and the registry as it stands is archived to backups-before-restore in the registry’s directory before the stores are replaced. A restore is audited as restore, which moves the epoch; --by NAME names who asked.

From the desk, Put it back on Settings, Backups does the same through the supervisor: it stops the engine, runs nils restore as the engine’s account, and starts the engine again. It needs work on the install. The key store stays as it is.

Next: installing the desk.