mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-17 07:42:23 +00:00
Merge remote-tracking branch 'origin/release/v1.46.0' into fix/v146-move-safety
This commit is contained in:
commit
0085915a56
53 files changed
+1620
-246
No files matched your search
@@ -79798,6 +79798,7 @@ components:
|
||||
- local-empty
|
||||
- local-unsupported
|
||||
- decrypt-error
|
||||
- resource-limit
|
||||
- raster-failed
|
||||
- provider-error
|
||||
- pdf-needs-anthropic
|
||||
@@ -80370,6 +80371,7 @@ components:
|
||||
- local-empty
|
||||
- local-unsupported
|
||||
- decrypt-error
|
||||
- resource-limit
|
||||
- raster-failed
|
||||
- provider-error
|
||||
- pdf-needs-anthropic
|
||||
|
||||
@@ -21,8 +21,8 @@ The weekly, pre-wipe and off-host copies carry the whole record, document
|
||||
files and ECG traces included, with the database's ciphertext inside them as
|
||||
stored. An uploaded copy holds whatever its file held. The personal
|
||||
export is portable: readable values, and documents as metadata only. It is
|
||||
meant for the person to keep and read. A restore refuses it when the account
|
||||
holds any document, because the file has no document content to put back.
|
||||
meant for the person to keep and read. A restore refuses it when the file
|
||||
lists any document, because it carries no document content to put back.
|
||||
|
||||
Two kinds of data are not in any account copy: workout GPS routes and sample
|
||||
series. Credentials, devices, share links and account grants are left out on
|
||||
|
||||
+17
-15
@@ -36,12 +36,13 @@ docker compose up -d app
|
||||
```
|
||||
|
||||
Step 2 takes the pre-migration dump too, in the one-off container, before it
|
||||
migrates. When the backups directory is writable and that dump fails (a full
|
||||
disk, most often), the entrypoint stops before migrating and says so; free
|
||||
the space and run the step again, or set `DB_BACKUP_BEFORE_MIGRATE=false` for
|
||||
one start without the dump. Without a writable directory (an install that
|
||||
runs the image without the `backups` volume) the log carries a warning, no
|
||||
dump is taken, and the migrations run.
|
||||
migrates. When the backups directory is on its volume and that dump fails (a
|
||||
full disk, most often), the entrypoint stops before migrating and says so;
|
||||
free the space and run the step again, or set `DB_BACKUP_BEFORE_MIGRATE=false`
|
||||
for one start without the dump. Without the `backups` volume the directory
|
||||
is not writable, or it is the image's own and sits inside the container that
|
||||
the update replaces; either way the log carries a warning, no dump is taken,
|
||||
and the migrations run.
|
||||
|
||||
Use `docker compose run` rather than a plain `docker run` for step 2. A
|
||||
plain `docker run` starts outside the stack's network, where `db` does not
|
||||
@@ -236,19 +237,20 @@ roll back:
|
||||
app version reads forward-compatible-ish shapes for nearly every
|
||||
release pair shipped on the v1.4.x line.
|
||||
3. If a column-drop migration ships in the rollback target, hand-roll
|
||||
the column back via a fresh forward migration (`pnpm prisma migrate
|
||||
dev --create-only --name vX_Y_Z_rollback_<col>`), edit the SQL,
|
||||
commit, and re-deploy. Never `migrate resolve --rolled-back` against
|
||||
the column back via a fresh forward migration
|
||||
(`pnpm prisma migrate dev --create-only --name vX_Y_Z_rollback_<col>`),
|
||||
edit the SQL, commit, and re-deploy. Never `migrate resolve --rolled-back` against
|
||||
production unless you've taken a fresh `pg_dump` first.
|
||||
4. Rolling back from v1.40.2 or later to v1.40.1 or earlier: an account
|
||||
that saved the Coach lookback "Last year" reads its whole Coach
|
||||
preference blob as defaults on the older version, metric exclusions
|
||||
included, until the setting is saved again. Ask affected accounts to
|
||||
pick another lookback before the rollback, or re-save their exclusions
|
||||
after it.
|
||||
|
||||
When the data itself has to go back to before the update, restore the
|
||||
pre-migration dump with the previous image; the steps are in
|
||||
[`disaster-recovery.md`](disaster-recovery.md#going-back-to-before-a-migration). 4. Rolling back from v1.40.2 or later to v1.40.1 or earlier: an account
|
||||
that saved the Coach lookback "Last year" reads its whole Coach
|
||||
preference blob as defaults on the older version, metric exclusions
|
||||
included, until the setting is saved again. Ask affected accounts to
|
||||
pick another lookback before the rollback, or re-save their exclusions
|
||||
after it.
|
||||
[`disaster-recovery.md`](disaster-recovery.md#going-back-to-before-a-migration).
|
||||
|
||||
## Catalog templates
|
||||
|
||||
|
||||
@@ -40,14 +40,22 @@ A dump holds every account that existed when it was taken, including one
|
||||
deleted since. Deleted accounts leave the dumps as they age out: after
|
||||
`DB_BACKUP_KEEP` nights on the server, and after your lifecycle rule in the
|
||||
bucket. Give that rule a prefix that covers `database/` too; the admin
|
||||
backups page reads the bucket's rules and says when none does. This is the
|
||||
backups page reads the bucket's rules and says when none does, and the
|
||||
recovery readiness card calls it attention and tells the admins once. This is the
|
||||
retention period to state where you tell people that deleting their account
|
||||
deletes their data.
|
||||
|
||||
Without a writable `DB_BACKUP_DIR` (an install that runs the image without the
|
||||
`backups` volume), the nightly dump is uploaded off-host and nothing is kept
|
||||
on the server, and no dump is taken before migrations; with no bucket either,
|
||||
no dump is taken at all. The start log and the admin page say so.
|
||||
A dump is kept on the server only when `DB_BACKUP_DIR` survives the container
|
||||
being replaced: a mounted volume or bind mount, or any writable directory when
|
||||
HealthLog does not run in a container. The image creates the default
|
||||
directory, so an install that runs it without the `backups` volume can write
|
||||
there, but the directory sits in the container's own layer and the next update
|
||||
throws it away. HealthLog reads the container's mount table to tell the two
|
||||
apart and treats such a directory, or one on a tmpfs, like one it cannot
|
||||
write: the nightly dump is uploaded off-host and nothing is kept on the
|
||||
server, and no dump is taken before migrations; with no bucket either, no
|
||||
dump is taken at all. The start log, the admin backups page and the recovery
|
||||
readiness card say so.
|
||||
|
||||
The per-account copies (the weekly in-database copy, the nightly per-account
|
||||
objects) roll one account back on the same server. They cannot rebuild a
|
||||
@@ -149,10 +157,32 @@ docker compose up -d
|
||||
```
|
||||
|
||||
The dump before a migration is taken while the new image starts. If it fails
|
||||
on a writable directory (a full disk, most often), the start stops before
|
||||
on a directory that keeps it (a full disk, most often), the start stops before
|
||||
anything is migrated and the log names the switch: `DB_BACKUP_BEFORE_MIGRATE=false`
|
||||
starts without it, once.
|
||||
|
||||
## Knowing the copies are there
|
||||
|
||||
Nobody opens the backups page until the day it matters, so the server tells
|
||||
the admins instead:
|
||||
|
||||
- The **Recovery readiness** card, on the admin overview and on Admin,
|
||||
Backups, judges every copy in one verdict each: the database dump (fresh,
|
||||
failed, or kept nowhere that survives the container), the weekly account
|
||||
copies, the off-host copies, the last restore drill, whether the bucket is
|
||||
set up, whether its lifecycle rule ever removes the dumps under
|
||||
`database/`, and the recovery kit.
|
||||
- The **recovery kit** under Admin, Encryption lists every key a restore
|
||||
needs (the table above), by id and fingerprint, and lets an admin check a
|
||||
saved copy and confirm it. It is due again after any key change.
|
||||
- An hourly check sends each admin a **Backup health** notification
|
||||
(`BACKUP_HEALTH`) when a signal on the card turns to needs attention or at
|
||||
risk, a reminder once a day while one stays at risk, and one more when it
|
||||
recovers. Each admin chooses the channels for it under Notifications.
|
||||
|
||||
[Getting started](../self-hosting/getting-started.md#save-the-recovery-kit)
|
||||
walks through saving the kit.
|
||||
|
||||
## How this is tested
|
||||
|
||||
`scripts/compose-dr-drill.sh` plays this page against real containers: it
|
||||
|
||||
@@ -295,7 +295,8 @@ key, a re-keyed install. The kit also links the
|
||||
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
|
||||
are set up, whether the bucket ever removes old database dumps, 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.
|
||||
|
||||
@@ -16,17 +16,18 @@ tailnet with no extra container. See
|
||||
|
||||
## Pre-flight — env vars the proxy interacts with
|
||||
|
||||
| Variable | Required for | Notes |
|
||||
| --------------------- | ---------------------------------------------- | ---------------------------------------- |
|
||||
| `NEXT_PUBLIC_APP_URL` | Every public-facing absolute URL the UI emits | Must match the hostname the proxy serves |
|
||||
| `APP_URL` | Server-side absolute URLs from background jobs | Mirror of the above; both must match |
|
||||
| `TRUST_PROXY_HOPS` | `X-Forwarded-For` chain trust | Defaults to `1` — one trusted hop |
|
||||
| Variable | Required for | Notes |
|
||||
| ------------------------ | ---------------------------------------------- | ---------------------------------------- |
|
||||
| `NEXT_PUBLIC_APP_URL` | Every public-facing absolute URL the UI emits | Must match the hostname the proxy serves |
|
||||
| `APP_URL` | Server-side absolute URLs from background jobs | Mirror of the above; both must match |
|
||||
| `TRUST_PROXY_HOPS` | `X-Forwarded-For` chain trust | Defaults to `1` — one trusted hop |
|
||||
| `TRUST_CF_CONNECTING_IP` | Reading the visitor address Cloudflare sends | Off unless `1`; see the warning below |
|
||||
|
||||
Set the URL pair to the public origin (`https://your-instance.example.com`)
|
||||
and restart the `app` container. The image reads both at startup; no
|
||||
rebuild needed.
|
||||
|
||||
All three variables are on the shipped `docker-compose.yml`
|
||||
All four variables are on the shipped `docker-compose.yml`
|
||||
`environment:` whitelist, so a value in `.env` reaches the container
|
||||
without editing the compose file. (Before v1.37.33 the whitelist was
|
||||
missing `TRUST_PROXY_HOPS`; on those versions add
|
||||
@@ -51,18 +52,45 @@ A misconfigured count logs a one-shot warning to stderr and collapses
|
||||
every anonymous caller into one shared rate-limit bucket. Match the
|
||||
value to the actual hop count.
|
||||
|
||||
Forwarding headers are believed only from a connection that could come
|
||||
from a proxy: loopback, a private or unique-local network, or CGNAT (a
|
||||
Tailscale address). A request that reaches HealthLog straight from a public
|
||||
Forwarding headers are believed only from a connection whose own address
|
||||
is not a public one, which is where a proxy you run connects from:
|
||||
|
||||
- IPv4: loopback (`127.0.0.0/8`), `0.0.0.0/8`, the private ranges
|
||||
(`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), CGNAT
|
||||
(`100.64.0.0/10`, Tailscale), link-local (`169.254.0.0/16`), the reserved
|
||||
blocks `192.0.0.0/24` and `198.18.0.0/15`, and everything from
|
||||
`224.0.0.0` up (multicast and reserved);
|
||||
- IPv6: `::` and `::1`, link-local (`fe80::/10`), site-local (`fec0::/10`),
|
||||
unique-local (`fc00::/7`, Tailscale), multicast (`ff00::/8`), and an
|
||||
IPv4-mapped or embedded address from one of the IPv4 ranges above.
|
||||
|
||||
The reserved and multicast blocks are in the list because no host on the
|
||||
internet can open a connection from them, so a peer there sits on a network
|
||||
you run. A request that reaches HealthLog straight from a public
|
||||
address carries headers its sender wrote, so HealthLog ignores them and
|
||||
uses the connection's own address, and says so once in the log. A proxy on
|
||||
the same host or Docker network connects from a private address, so the
|
||||
usual setups above need nothing. If your proxy reaches HealthLog over a
|
||||
public address, put it on a private network with HealthLog instead (or, for
|
||||
Cloudflare straight to the origin, use `TRUST_CF_CONNECTING_IP=1`). The log
|
||||
public address, put it on a private network with HealthLog instead. The log
|
||||
line also shows up when the published port is open to the internet beside
|
||||
the proxy; bind it to the proxy's network or to `127.0.0.1` then.
|
||||
|
||||
### `TRUST_CF_CONNECTING_IP` — only when the origin takes Cloudflare only
|
||||
|
||||
With `TRUST_CF_CONNECTING_IP=1` HealthLog takes the visitor's address from
|
||||
the `CF-Connecting-IP` header, before any of the checks above: from every
|
||||
connection, whatever its address, and whatever `TRUST_PROXY_HOPS` says.
|
||||
Cloudflare sets that header on every request through its edge, but any
|
||||
client can send it too. So the flag is safe only when nothing but
|
||||
Cloudflare can reach the origin: a Cloudflare Tunnel with no published
|
||||
port, or a firewall that admits only
|
||||
[Cloudflare's address ranges](https://www.cloudflare.com/ips/) to the port
|
||||
HealthLog or its proxy listens on (Authenticated Origin Pulls on top is
|
||||
better still). If the origin also answers on its own public address, a
|
||||
caller who finds it chooses the address every per-IP rate limit, the audit
|
||||
log and the sign-in locations record, and changes it on every request.
|
||||
Without Cloudflare in front, leave the flag unset.
|
||||
|
||||
`X-Real-IP` gets the same trust as `X-Forwarded-For`. It is read only
|
||||
when `TRUST_PROXY_HOPS` is exactly `1` and the request carries no
|
||||
`X-Forwarded-For`, which covers a single proxy that sets only
|
||||
|
||||
@@ -101,5 +101,6 @@ and host names before it is shown.
|
||||
|
||||
`docker compose logs app` prints every wide event as one JSON line;
|
||||
`LOG_LEVEL=debug` adds debug events. With `LOKI_ENDPOINT` set the same events
|
||||
go to Loki, and GlitchTip (Admin, General) receives unexpected server errors.
|
||||
go to Loki, and GlitchTip (Admin, Integrations, once a DSN is set there)
|
||||
receives unexpected server errors.
|
||||
Each line carries `request_id`, so an error id finds its line there too.
|
||||
@@ -54,6 +54,15 @@ example `UPDATE_CHECK_DISABLED=1`. The full list is in
|
||||
To use your own GeoLite2 databases, add the directory under Additional Storage
|
||||
and point `GEOLITE2_DIR` at its mount path ([geolite2.md](geolite2.md)).
|
||||
|
||||
HealthLog writes a whole-database dump every night, and one before each update
|
||||
that brings migrations, into `/var/lib/healthlog/backups` inside the app
|
||||
container. Give that path a dataset of its own (a host path or an ixVolume,
|
||||
writable by uid `1001`), under Additional Storage if the form has no field for
|
||||
it. Without one the directory sits inside the container, which an update
|
||||
replaces, so HealthLog keeps no dump there: the start log, the admin backups
|
||||
page and the recovery readiness card say so, and with an off-host bucket the
|
||||
nightly dump goes to the bucket only.
|
||||
|
||||
## Plain HTTP on the LAN
|
||||
|
||||
Most NAS installs are reached over `http://`. Leave **Secure Cookies** off for
|
||||
@@ -113,6 +122,10 @@ back.
|
||||
The file lands in the Postgres Data Storage dataset, next to the database
|
||||
files, so copy it off the NAS as well.
|
||||
|
||||
- **The nightly dump.** With a dataset on `/var/lib/healthlog/backups` (see
|
||||
above), the newest seven nightly dumps and the last two taken before a
|
||||
migration stay there; [disaster-recovery.md](../ops/disaster-recovery.md)
|
||||
restores one onto a new server.
|
||||
- **Off-host.** HealthLog can push encrypted nightly backups to any
|
||||
S3-compatible bucket; see [backup-restore.md](../ops/backup-restore.md).
|
||||
|
||||
@@ -216,7 +229,7 @@ the menu next to Custom App, Install via YAML, using these values:
|
||||
| Health check | `GET /api/health`, `200` when ready |
|
||||
| Start period | 10 min, like the image: migrations run at every boot and wait out a held lock |
|
||||
| Database | PostgreSQL 18 (16 works too), no extensions, in its own container with its own dataset |
|
||||
| Volumes | none for the app; the database gets its own dataset |
|
||||
| Volumes | `/var/lib/healthlog/backups` for the database dumps (uid `1001`); the database its own |
|
||||
|
||||
| Variable | Required | Notes |
|
||||
| ----------------------- | -------- | ---------------------------------------------------------------------------------------- |
|
||||
|
||||
@@ -6,10 +6,13 @@ self-contained install (app + database as one unit) and is recommended. The
|
||||
Unraid UI, but because CA templates describe a single container you install
|
||||
PostgreSQL separately and wire the two together.
|
||||
|
||||
HealthLog stores all persistent state in PostgreSQL — the app container itself is
|
||||
stateless (the offline geo-IP databases are either baked in at build time or
|
||||
mounted read-only; replaceable either way, not state). A backup of
|
||||
the database is a backup of everything.
|
||||
HealthLog stores all persistent state in PostgreSQL. The app container keeps one
|
||||
more thing, its database dumps: every night, and before each update that brings
|
||||
migrations, it writes a whole-database dump to `/var/lib/healthlog/backups`
|
||||
(the offline geo-IP databases are either baked in at build time or mounted
|
||||
read-only; replaceable either way, not state). A backup of the database is a
|
||||
backup of everything, and those dumps are that backup, so that path needs a
|
||||
share of its own.
|
||||
|
||||
## What you need
|
||||
|
||||
@@ -103,12 +106,20 @@ Fill in the fields:
|
||||
| `SESSION_COOKIE_SECURE` | `false` for plain-HTTP LAN access |
|
||||
| `NEXT_PUBLIC_APP_URL` | `http://tower:3000` (or your domain) |
|
||||
| `APP_URL` | same as `NEXT_PUBLIC_APP_URL` |
|
||||
| Database dumps | `/mnt/user/appdata/healthlog/backups` (the default) |
|
||||
|
||||
Replace `<password>` and `<postgres-host>` with the values from Step 1. Apply,
|
||||
then open `http://tower:3000` — the first registered user becomes the admin.
|
||||
Replace `<password>` and `<postgres-host>` with the values from Step 1. The
|
||||
dumps folder must be writable by the app's user, uid `1001`; create it once
|
||||
from the terminal with
|
||||
`mkdir -p /mnt/user/appdata/healthlog/backups && chown 1001:1001 /mnt/user/appdata/healthlog/backups`.
|
||||
Apply, then open `http://tower:3000` — the first registered user becomes the
|
||||
admin.
|
||||
|
||||
The HealthLog container has no persistent volume of its own; all state is in the
|
||||
PostgreSQL container you installed in Step 1. Back that one up.
|
||||
All account data is in the PostgreSQL container you installed in Step 1, and
|
||||
the nightly dumps of it land in the dumps folder. Without that path the dumps
|
||||
would sit inside the HealthLog container, which every update replaces, so
|
||||
HealthLog keeps none: the start log, the admin backups page and the recovery
|
||||
readiness card say so. Back up both.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -63,4 +63,6 @@
|
||||
<Config Name="ENCRYPTION_KEYS" Target="ENCRYPTION_KEYS" Default="" Mode="" Description="Optional. Key-rotation map, e.g. {"v1":"<hex>","v2":"<hex>"}. Leave empty unless rotating; use ENCRYPTION_KEY instead." Type="Variable" Display="advanced" Required="false" Mask="true"/>
|
||||
|
||||
<Config Name="ENCRYPTION_ACTIVE_KEY_ID" Target="ENCRYPTION_ACTIVE_KEY_ID" Default="" Mode="" Description="Optional. Active key id for the ENCRYPTION_KEYS map (e.g. v2). Leave empty when using ENCRYPTION_KEY." Type="Variable" Display="advanced" Required="false" Mask="false"/>
|
||||
|
||||
<Config Name="Database dumps" Target="/var/lib/healthlog/backups" Default="/mnt/user/appdata/healthlog/backups" Mode="rw" Description="Where HealthLog keeps its nightly database dump and the one it takes before each update that brings migrations. Without this path the dumps would sit inside the container, which an update replaces, so none is kept. Must be writable by uid 1001 (chown 1001:1001 the folder once)." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/healthlog/backups</Config>
|
||||
</Container>
|
||||
Reference in new issue
Block a user