From ed51211e820e819f5fa0b2207dbb43d769725400 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Sun, 25 Oct 2026 13:32:43 +0100 Subject: [PATCH] docs(self-hosting): describe the recovery kit and the readiness push The key backup sections become "Save the recovery kit": which keys the kit lists and why, the fingerprint of the token key, and the readiness card with its Backup health notification. --- docs/self-hosting/getting-started.md | 40 +++++++++++++++++++++------- docs/self-hosting/truenas.md | 19 ++++++------- docs/self-hosting/unraid.md | 14 +++++----- 3 files changed, 49 insertions(+), 24 deletions(-) diff --git a/docs/self-hosting/getting-started.md b/docs/self-hosting/getting-started.md index f4fb5d208..c4c337468 100644 --- a/docs/self-hosting/getting-started.md +++ b/docs/self-hosting/getting-started.md @@ -270,14 +270,35 @@ ps` — the `app` healthcheck polls `/api/health` every 30 seconds `pull_policy: always` on the `app` service, and verify the running build with `GET /api/version` (it returns `version` + `buildSha`). -## Back up your encryption key +## Save the recovery kit -`ENCRYPTION_KEY` (or the `ENCRYPTION_KEYS` map) is not stored in the database. -Without it, the encrypted parts of the database and every in-database backup -cannot be read. Keep a copy outside the server, then confirm it under Admin, -Encryption: the step shows the key id and a fingerprint (the first 12 hex -characters of SHA-256 over the key) and can check a pasted copy without -storing it. Admins see a dashboard reminder until the active key is confirmed. +No key HealthLog encrypts with is stored in the database. Without them the +encrypted parts of the database, a database dump and every backup copy cannot +be read. The recovery kit under Admin, Encryption lists every key a restore of +this server needs: + +- `ENCRYPTION_KEY` (or each id in the `ENCRYPTION_KEYS` map), including a + retired id for as long as a stored or off-host backup copy still needs it; +- `BACKUP_ENCRYPTION_KEY` and any `BACKUP_ENCRYPTION_PREVIOUS_KEYS`, when + off-host copies are set up; +- `API_TOKEN_HMAC_KEY`, without which every session, token and share link ends + (no data is lost). + +Each key is shown by id and a fingerprint (the first 12 hex characters of +SHA-256 over the key), never the key itself, and **Check my copy** compares a +pasted copy without storing it. Keep a copy of each outside the server, then +confirm the kit. Admins see a dashboard reminder until it is confirmed, and the +kit is due again whenever a key it needs changes: a rotation, a new backup +key, a re-keyed install. The kit also links the +[disaster recovery guide](../ops/disaster-recovery.md). + +The **Recovery readiness** card on the admin overview and the Backups page +judges every backup signal in one place: the database dump, the weekly account +copies, the off-host copies, the last restore drill, whether off-host copies +are set up, and the recovery kit. An hourly check sends each admin a +**Backup health** notification when a signal turns to "needs attention" or "at +risk", once a day while it stays at risk, and once when it recovers. Route or +switch it off per channel under Notifications. | Platform | Where the key is set | | --------- | -------------------------------------------------------------------------------------------------- | @@ -288,12 +309,13 @@ storing it. Admins see a dashboard reminder until the active key is confirmed. | Portainer | the stack's Environment variables | Set `HEALTHLOG_PLATFORM` (`compose`, `truenas`, `coolify`, `unraid`, -`portainer`) to open the step on your platform's instructions. +`portainer`) to open the kit on your platform's instructions. -To compute the fingerprint of your copy: +To compute the fingerprint of your copy of a hex key, and of the token key: ```bash echo -n "" | xxd -r -p | sha256sum | cut -c1-12 +printf %s "" | sha256sum | cut -c1-12 ``` **HealthLog refuses to serve: encryption key does not match this database.** diff --git a/docs/self-hosting/truenas.md b/docs/self-hosting/truenas.md index d312e4fb7..422efd68a 100644 --- a/docs/self-hosting/truenas.md +++ b/docs/self-hosting/truenas.md @@ -20,7 +20,7 @@ database dataset and in one value you must keep yourself: the encryption key. ``` Each run prints 64 hex characters. Put both in your password manager - before you continue; see [Back up your encryption key](#back-up-your-encryption-key). + before you continue; see [Save the recovery kit](#save-the-recovery-kit). 2. Open Apps, Discover Apps, search for **HealthLog** and choose Install. 3. Fill in the form: @@ -61,7 +61,7 @@ and the login page says so before you type a password: "Signing in cannot complete on this page". Turn it on only when HealthLog is served over `https://`, and set App URL to that `https://` address. -## Back up your encryption key +## Save the recovery kit HealthLog encrypts tokens, notes, documents and in-database backups with the Encryption Key. The key is not stored in the database. If the app is deleted @@ -75,9 +75,10 @@ password manager or another place outside the NAS. 1. Open Apps, select HealthLog and choose Edit. The key is the Encryption Key field under HealthLog Configuration. -2. Sign in as the admin and open Admin, Encryption. The **Back up your - encryption key** step shows the active key id and a fingerprint, the first - 12 hex characters of SHA-256 over the key. Compare it with your copy: +2. Sign in as the admin and open Admin, Encryption. The **Recovery kit** lists + every key a restore needs (the Encryption Key, the token key and, with + off-host copies, the backup key), each with an id and a fingerprint, the + first 12 hex characters of SHA-256 over the key. Compare it with your copy: ```bash echo -n "" | xxd -r -p | sha256sum | cut -c1-12 @@ -86,10 +87,10 @@ password manager or another place outside the NAS. or paste the copy into **Check my copy**. It is compared and dropped, never stored or logged. -3. Press **I have backed up this key**. Until you do, admins see a reminder on - the dashboard. After a key rotation the step comes back for the new key. +3. Press **I have a copy of every key**. Until you do, admins see a reminder on + the dashboard. After a key rotation or a new backup key the kit is due again. -The catalog app sets `HEALTHLOG_PLATFORM=truenas`, so the step opens on these +The catalog app sets `HEALTHLOG_PLATFORM=truenas`, so the kit opens on these instructions. ## Backups and restore @@ -224,7 +225,7 @@ the menu next to Custom App, Install via YAML, using these values: | `NEXT_PUBLIC_APP_URL` | yes | the address people open, for example `http://truenas.local:30180` | | `APP_URL` | yes | the same address | | `SESSION_COOKIE_SECURE` | no | `false` for a LAN install served over plain `http://`; leave unset behind an HTTPS proxy | -| `HEALTHLOG_PLATFORM` | no | `truenas`: the admin's key backup step opens on the TrueNAS instructions | +| `HEALTHLOG_PLATFORM` | no | `truenas`: the admin's recovery kit opens on the TrueNAS instructions | `HEALTHLOG_PROCESS_TYPE` stays unset (`all`): one container serves the web app and runs the background jobs. In a YAML install the key sits in the diff --git a/docs/self-hosting/unraid.md b/docs/self-hosting/unraid.md index 87c0e91df..9f861bcba 100644 --- a/docs/self-hosting/unraid.md +++ b/docs/self-hosting/unraid.md @@ -123,13 +123,15 @@ Set `SESSION_COOKIE_SECURE=true` (or leave it unset) only when a TLS reverse proxy serves HealthLog over HTTPS. In that case also point `NEXT_PUBLIC_APP_URL` and `APP_URL` at the public `https://` URL. -## Back up your encryption key +## Save the recovery kit -Copy `ENCRYPTION_KEY` from the template into your password manager, then -confirm it under Admin, Encryption (set `HEALTHLOG_PLATFORM=unraid` so the step -opens on the Unraid instructions). A reinstall with a new key over the old -database makes the data unreadable; HealthLog then refuses to serve and says -so. See [Getting started](getting-started.md#back-up-your-encryption-key). +Copy `ENCRYPTION_KEY`, `API_TOKEN_HMAC_KEY` and, with off-host copies, +`BACKUP_ENCRYPTION_KEY` from the template into your password manager, then +confirm the recovery kit under Admin, Encryption (set +`HEALTHLOG_PLATFORM=unraid` so the kit opens on the Unraid instructions). A +reinstall with a new key over the old database makes the data unreadable; +HealthLog then refuses to serve and says so. See +[Getting started](getting-started.md#save-the-recovery-kit). ## Updates