mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
ed51211e82
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.
445 lines
23 KiB
Markdown
445 lines
23 KiB
Markdown
# Getting started — self-host HealthLog
|
|
|
|
This walkthrough takes a fresh host from `git clone` to a running
|
|
instance with a working first user. About fifteen minutes if Docker is
|
|
already installed, longer if a TLS-fronted public hostname is in scope
|
|
(see the reverse-proxy guide for that).
|
|
|
|
## Prerequisites
|
|
|
|
- **Docker 24+ with Compose v2.** The bundled `docker-compose.yml`
|
|
pulls a multi-arch image from GitHub Container Registry (linux/amd64
|
|
- linux/arm64), so a Raspberry Pi 5 or an x86 VPS both work
|
|
unchanged.
|
|
- **3 GB RAM (4 GB recommended), 10 GB free disk.** The Postgres data
|
|
volume grows with measurement history; the Apple Health import worker
|
|
can briefly hold a 1.5 GB upload in `/tmp` while it parses. The app
|
|
container is capped at `APP_MEMORY_LIMIT`, `1536m` by default (Node
|
|
then sizes its heap at about 792 MB), and Postgres and the system need
|
|
the rest. 1536 MB is the supported floor for the app container: do not
|
|
lower it to fit a smaller host. Below it, a long-used account or a large
|
|
import can fill the heap and restart the app; the app still starts, but
|
|
the boot log, the support report and Admin > System status say it runs
|
|
below the supported floor. On a busy instance, raise it.
|
|
- **Outbound HTTPS** to `ghcr.io` (image pulls) plus whichever
|
|
integration endpoints you plan to enable (Withings, OpenAI, etc.).
|
|
The opt-in environmental-context module additionally reaches
|
|
`archive-api.open-meteo.com` and `geocoding-api.open-meteo.com` for
|
|
weather and daylight; it stays off until you
|
|
enable it and set a home location, and every outbound call goes
|
|
through the SSRF-guarded egress wrapper.
|
|
Three requests happen by default without anything connected: the
|
|
HaveIBeenPwned range query when a password is set (only the first five
|
|
characters of the password's SHA-1 are sent), a daily check of the
|
|
GitHub releases API for the update badge, and the online IP
|
|
geolocation lookup for login events. `PASSWORD_BREACH_CHECK_DISABLED`,
|
|
`UPDATE_CHECK_DISABLED` and `IP_GEO_LOOKUP_DISABLED` turn each off; see
|
|
`.env.production.example`.
|
|
- **Optional but recommended:** a reverse proxy that terminates TLS
|
|
and forwards to `http://localhost:3000` (Caddy, Traefik, Nginx
|
|
Proxy Manager, Coolify, or bare Nginx — see `reverse-proxy.md`).
|
|
|
|
## 1. Clone the repository
|
|
|
|
```bash
|
|
git clone https://github.com/MBombeck/HealthLog.git
|
|
cd HealthLog
|
|
cp .env.example .env
|
|
```
|
|
|
|
`.env.example` is a short starter with the variables most self-hosts
|
|
touch. The complete reference, with every variable the app reads and what
|
|
it does, is `.env.production.example`; CI checks that file against
|
|
`scripts/env-manifest.json`. Anything you do not set falls back to a sane
|
|
default or leaves the optional subsystem off.
|
|
|
|
## 2. Generate the three required secrets
|
|
|
|
HealthLog needs three secrets before it will boot. Generate them with
|
|
`openssl` and append to `.env`:
|
|
|
|
```bash
|
|
echo "POSTGRES_PASSWORD=$(openssl rand -hex 32)" >> .env
|
|
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
|
|
echo "API_TOKEN_HMAC_KEY=$(openssl rand -hex 32)" >> .env
|
|
```
|
|
|
|
| Variable | Purpose | Rotation cost |
|
|
| -------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
| `POSTGRES_PASSWORD` | Bundled Postgres password — used by both the `db` service and `DATABASE_URL` | Database restart + connection-string update |
|
|
| `ENCRYPTION_KEY` | AES-256-GCM key for at-rest secrets (Withings tokens, AI provider keys, VAPID secrets) | Coordinated; see `docs/ops/encryption-key-rotation.md` |
|
|
| `API_TOKEN_HMAC_KEY` | HMAC-SHA256 key for hashing Bearer API tokens and web session cookies before storage | Invalidates every issued `hlk_*` token and signs out every browser session |
|
|
|
|
You do **not** edit `DATABASE_URL` on the bundled `docker-compose.yml`
|
|
stack: compose constructs the connection string inside the `app`
|
|
service from `${POSTGRES_PASSWORD}` (its `environment:` block overrides
|
|
any `DATABASE_URL` in `.env`), so the `openssl` line above is the only
|
|
password step. `DATABASE_URL` only matters if you run a **bare Node**
|
|
process (`pnpm dev` against a host Postgres) or a **custom compose** that
|
|
does not derive it — in that case uncomment and set `DATABASE_URL`
|
|
explicitly in `.env` (see the commented example there).
|
|
|
|
### Using an existing or shared Postgres
|
|
|
|
HealthLog can live in a database on a Postgres instance you already run,
|
|
version 16 or newer; the compose file ships 18, and every release is tested
|
|
on both.
|
|
It stores every time as UTC and pins each connection it opens to UTC
|
|
(`TimeZone=UTC`, sent with the libpq `options` startup parameter), so the
|
|
server's or the database's own `timezone` setting does not matter: an
|
|
instance set to `Europe/Berlin` works the same as one set to UTC. The app
|
|
checks the setting at startup and logs a warning naming the zone if a
|
|
connection still reports something else.
|
|
|
|
Behind PgBouncer with `DATABASE_SESSION_OPTIONS_DISABLED=1` (see
|
|
[Scaling](./scaling.md#postgres-connection-pool-sizing)) the app pins the
|
|
zone with `SET TIME ZONE 'UTC'` on each new connection instead; PgBouncer
|
|
keeps that setting per client in transaction pooling too. If the startup
|
|
warning still appears, set the database default as well:
|
|
|
|
```sql
|
|
ALTER DATABASE healthlog SET timezone TO 'UTC';
|
|
```
|
|
|
|
## 3. Bring the stack up
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Compose starts two services and one short-lived step:
|
|
|
|
- `db` — PostgreSQL 18 with a named volume for persistence.
|
|
- `db-upgrade` — moves a Postgres 16 database from v1.45 or earlier into
|
|
the new one, once, and exits; on a new install it has nothing to do. See
|
|
[Moving to a newer Postgres major](../ops/postgres-major-upgrade.md).
|
|
- `app` — HealthLog itself, listening on `localhost:3000`. The image
|
|
runs `prisma migrate deploy` on boot so the schema lands
|
|
automatically; subsequent restarts no-op when the database is
|
|
already current.
|
|
|
|
The first boot pulls the image (a few hundred megabytes) and runs
|
|
migrations. Once `docker compose logs -f app` shows the Next.js
|
|
banner, the instance is live.
|
|
|
|
## 4. Create the first user
|
|
|
|
Open `http://localhost:3000` in a browser. The registration flow asks
|
|
for a username, email, and password. **The first user that registers
|
|
is promoted to admin automatically.** Every subsequent registration
|
|
creates a regular user.
|
|
|
|
After the first user lands, you can:
|
|
|
|
- Open `/admin` to review the worker status, audit log, and any
|
|
optional channels you want to configure (Telegram bot, ntfy, Web
|
|
Push VAPID keys, AI fallback key).
|
|
- Open `/measurements` and add a weight or blood pressure to confirm
|
|
the data path is wired end-to-end.
|
|
|
|
> **Close public registration if you expose the instance to the
|
|
> internet.** Registration stays **open** after the first admin so you
|
|
> can invite the rest of your household — but on a publicly reachable
|
|
> host that means strangers can still sign up. Once everyone who needs
|
|
> an account has one, turn it off in **`/admin` → registration toggle**
|
|
> (or keep it open and hand out invite links instead). The admin
|
|
> settings show a reminder underneath the toggle while registration is
|
|
> open.
|
|
|
|
> **No email is configured out of the box** — a deliberate first-boot
|
|
> simplicity win, but it also means password reset has no self-service
|
|
> path until you set SMTP (see `docs/self-hosting/notifications.md`). If
|
|
> you are the sole admin, **save your password in a manager now**: a
|
|
> locked-out solo admin with no SMTP recovers only via the CLI script in
|
|
> `docs/ops/password-reset.md`.
|
|
|
|
## 5. Point the instance at a public hostname
|
|
|
|
Local-only is fine for a single-user trial. For anything more — and
|
|
to unlock OAuth callbacks, webhook deliveries, and Web Push — set the
|
|
public URL pair before restarting:
|
|
|
|
```env
|
|
NEXT_PUBLIC_APP_URL="https://your-instance.example.com"
|
|
APP_URL="https://your-instance.example.com"
|
|
```
|
|
|
|
Both vars must match. `NEXT_PUBLIC_APP_URL` lands in the client bundle
|
|
at build time and drives every absolute URL the UI emits (OAuth
|
|
redirects, share links, manifest icons). `APP_URL` is the server-side
|
|
mirror used by background jobs that have no request context.
|
|
|
|
Restart the app container after editing:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
The pre-built image reads both values at startup; no rebuild needed.
|
|
|
|
## 6. Pick a reverse-proxy
|
|
|
|
The bundled stack exposes plain HTTP on `localhost:3000`. Production
|
|
deployments terminate TLS in front of the container. The
|
|
`docs/self-hosting/reverse-proxy.md` guide carries copy-paste
|
|
configurations for Caddy, Traefik, Nginx Proxy Manager, Coolify, and
|
|
bare Nginx — including the `X-Forwarded-For` chain shape that the
|
|
rate-limiter trusts and the `TRUST_PROXY_HOPS` env var that pins how
|
|
many hops to read back.
|
|
|
|
## Build-time feature toggles
|
|
|
|
A small number of toggles are `NEXT_PUBLIC_*` variables: the framework
|
|
inlines them into the client bundle at **build time**, so the pre-built
|
|
GHCR image cannot read them at runtime. Setting them in `.env` or the
|
|
compose `environment:` block has no effect — they only take hold when
|
|
you build your own image. They are intentionally absent from the
|
|
compose runtime whitelist for that reason.
|
|
|
|
| Variable | Default | Effect when set |
|
|
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `NEXT_PUBLIC_DASHBOARD_SNAPSHOT` | on | The dashboard hydrates every above-the-fold tile from the single `GET /api/dashboard/snapshot` cell so the whole strip shares one completion moment. Build with `NEXT_PUBLIC_DASHBOARD_SNAPSHOT=false` to fall back to the legacy four-cell path. |
|
|
|
|
To flip one, rebuild the image with the variable exported:
|
|
|
|
```bash
|
|
NEXT_PUBLIC_DASHBOARD_SNAPSHOT=false pnpm build
|
|
# or pass it as a Dockerfile build ARG / Docker build --build-arg
|
|
```
|
|
|
|
## 7. Where to go next
|
|
|
|
| Next step | File |
|
|
| ------------------------------------------------------------------- | ------------------------------------- |
|
|
| TLS + reverse-proxy configuration | `docs/self-hosting/reverse-proxy.md` |
|
|
| Tailnet-only HTTPS via `tailscale serve` (no reverse proxy) | `docs/self-hosting/tailscale.md` |
|
|
| Push notifications — Web Push, Telegram, ntfy, webhook, email, APNs | `docs/self-hosting/notifications.md` |
|
|
| Web/worker process split for horizontal scale | `docs/self-hosting/scaling.md` |
|
|
| Off-host encrypted backups to S3/R2/B2 | `docs/ops/backup-restore.md` |
|
|
| Encryption-key rotation procedure | `docs/ops/encryption-key-rotation.md` |
|
|
| Withings device sync | `docs/integrations/withings.md` |
|
|
| WHOOP device sync (per-user BYO-keys) | `docs/integrations/whoop.md` |
|
|
| Google Health sync — Fitbit & Pixel (per-user BYO-keys) | `docs/integrations/google-health.md` |
|
|
| Apple Health `export.zip` import | `docs/integrations/apple-health.md` |
|
|
| AI provider setup (OpenAI / Anthropic / local / ChatGPT OAuth) | `docs/integrations/ai-providers.md` |
|
|
|
|
## Troubleshooting
|
|
|
|
- **Where to look.** For a bug report, copy the support report (Admin,
|
|
System status) and the support info (Settings, About), and note the error
|
|
id the failure showed. Admin, App logs finds the event behind an error id.
|
|
What each contains, and what it never contains, is in
|
|
[`support.md`](./support.md).
|
|
- **`app` container exits with a Prisma migration error.** The
|
|
Postgres healthcheck races the migration on slow disks. Run
|
|
`docker compose restart app` once the database has stabilised —
|
|
migrations are idempotent.
|
|
- **First-user registration shows "registration disabled".** The
|
|
bundled image ships with registration enabled; the toggle lives in
|
|
`app_settings.singleton.registrationEnabled`. The admin panel can
|
|
flip it back if a previous owner closed it.
|
|
- **Service unreachable on `localhost:3000`.** Check `docker compose
|
|
ps` — the `app` healthcheck polls `/api/health` every 30 seconds
|
|
(it returns 503 while the database or worker is down) and will mark
|
|
the container unhealthy if Postgres is still
|
|
starting. Tail `docker compose logs db` to confirm Postgres came up
|
|
cleanly.
|
|
- **The login page says "Signing in cannot complete on this page".** The
|
|
server sets its session cookie with the `Secure` flag (the production
|
|
default) and the page was opened over plain `http://`, where the browser
|
|
would drop it. Set `SESSION_COOKIE_SECURE=false` for a server reached only
|
|
over HTTP on a private network, or open the `https://` address (behind a TLS
|
|
proxy, make sure it forwards `X-Forwarded-Proto: https`). The sign-in is
|
|
refused before any password, code or ticket is used.
|
|
- **OAuth callbacks loop back to localhost.** Confirm `APP_URL` and
|
|
`NEXT_PUBLIC_APP_URL` both point at the public hostname, not at
|
|
`localhost`, and restart `app` after the change.
|
|
- **An env var in `.env` seems ignored / a feature stays "off".** The
|
|
compose `environment:` block is a **whitelist** — a variable set in
|
|
`.env` only reaches the container if `docker-compose.yml` lists it
|
|
under `environment:`. Vars not listed never propagate, even with
|
|
`${VAR}` substitution at compose-up. If a setting looks configured but
|
|
is silently dead, check the var is in that block (add it if you run a
|
|
custom compose); the supported alternative for most secrets (VAPID,
|
|
GitHub token, GlitchTip DSN) is the **admin panel**, which stores them
|
|
in the database and sidesteps the whitelist entirely.
|
|
- **A new image doesn't pick up / `:latest` looks stale.** `docker-compose.yml`
|
|
sets `pull_policy: always`, which is load-bearing: without it Docker
|
|
re-uses the cached `:latest` digest and silently skips the registry
|
|
round-trip on `compose up`. If you pin a custom compose, keep
|
|
`pull_policy: always` on the `app` service, and verify the running
|
|
build with `GET /api/version` (it returns `version` + `buildSha`).
|
|
|
|
## Save the recovery kit
|
|
|
|
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 |
|
|
| --------- | -------------------------------------------------------------------------------------------------- |
|
|
| Compose | `.env` next to `docker-compose.yml` |
|
|
| TrueNAS | Apps, HealthLog, Edit: the Encryption Key field (`ENCRYPTION_KEY` in a YAML install's environment) |
|
|
| Coolify | the application's Environment Variables |
|
|
| Unraid | the container template (Docker tab, Edit) or the Compose `.env` |
|
|
| Portainer | the stack's Environment variables |
|
|
|
|
Set `HEALTHLOG_PLATFORM` (`compose`, `truenas`, `coolify`, `unraid`,
|
|
`portainer`) to open the kit on your platform's instructions.
|
|
|
|
To compute the fingerprint of your copy of a hex key, and of the token key:
|
|
|
|
```bash
|
|
echo -n "<your key>" | xxd -r -p | sha256sum | cut -c1-12
|
|
printf %s "<API_TOKEN_HMAC_KEY>" | sha256sum | cut -c1-12
|
|
```
|
|
|
|
**HealthLog refuses to serve: encryption key does not match this database.**
|
|
At start the app checks that its key opens the stored data. If it does not,
|
|
every API request answers `503` with `meta.errorCode`
|
|
`encryption.key_mismatch`, `/api/health` answers `503` with
|
|
`reason: "encryption_key_mismatch"`, and background jobs are not started.
|
|
Restore the original key, point `DATABASE_URL` at the matching database, or
|
|
start with an empty database; then restart.
|
|
|
|
The check remembers the key it first saw for each key id in the table
|
|
`encryption_key_canaries`. Before it records a key, it reads the oldest
|
|
encrypted values in the database and records the key only if they open, or
|
|
if the database holds no encrypted value under that key id at all. When the
|
|
stored data proves neither (a single unreadable value, the oldest values
|
|
failing while newer ones open, or a probe that ran out of time), the app
|
|
keeps serving, records nothing, logs a warning that starts with
|
|
`[boot] Encryption key check inconclusive`, and checks again at the next
|
|
start.
|
|
|
|
If you are certain the configured key is the one your data was written
|
|
with, and the check still refuses because it recorded a different key
|
|
earlier, reset the check for that key id and restart. The refusal in the log
|
|
prints the exact statement; for the default key id it is:
|
|
|
|
```bash
|
|
docker compose exec -T db psql -U healthlog healthlog \
|
|
-c "DELETE FROM encryption_key_canaries WHERE key_id = 'v1';"
|
|
docker compose restart app
|
|
```
|
|
|
|
The next start probes the stored data again and records the key only if
|
|
that data opens with it. Do this only when you are sure: if the key is in
|
|
fact wrong, the app serves errors on every encrypted value instead of the
|
|
one clear refusal. After a key rotation the rotation script removes the
|
|
record of a retired key id itself, once it reports that no values remain
|
|
under that id.
|
|
|
|
At a first start there is no record yet, so there is nothing to reset. If
|
|
the check refuses there and you are certain the key is right, the last
|
|
resort is `ENCRYPTION_KEY_CHECK=warn` (default `enforce`): the check still
|
|
runs and logs its full result, `/api/health` names it as
|
|
`warning: "encryption_key_mismatch"` without failing, requests are served,
|
|
and no key is recorded while the check does not pass. This disables a
|
|
safety check. With a wrong key every encrypted value fails and new rows are
|
|
written under that key, so remove the setting once the key is confirmed.
|
|
|
|
## Backup and restore
|
|
|
|
Your database is the only stateful piece — back it up, and back up the
|
|
key that decrypts it.
|
|
|
|
**Local snapshot (the common single-box case).** Dump the `db` service
|
|
with `pg_dump`:
|
|
|
|
```bash
|
|
# The bundled db service uses user `healthlog` and database `healthlog`.
|
|
docker compose exec -T db pg_dump -U healthlog healthlog \
|
|
| gzip > healthlog-$(date +%F).sql.gz
|
|
```
|
|
|
|
Restore into a fresh database the same way:
|
|
|
|
```bash
|
|
gunzip -c healthlog-2026-01-01.sql.gz \
|
|
| docker compose exec -T db psql -U healthlog healthlog
|
|
```
|
|
|
|
> **Back up your `ENCRYPTION_KEYS` / `ENCRYPTION_KEY` alongside the dump.**
|
|
> HealthLog encrypts sensitive columns at rest (AES-256-GCM). A database
|
|
> dump **without the encryption key is unrecoverable** — the encrypted
|
|
> data cannot be read back. Store the key (and any retired keys still in
|
|
> the rotation map) somewhere separate from the dump but equally durable.
|
|
> Losing the key means losing the encrypted data, full stop.
|
|
|
|
For off-host encrypted backups to S3/R2/B2 see
|
|
[`docs/ops/backup-restore.md`](../ops/backup-restore.md); for rotating the
|
|
encryption key safely (keep the old key until zero rows remain on it) see
|
|
[`docs/ops/encryption-key-rotation.md`](../ops/encryption-key-rotation.md).
|
|
|
|
## Updates
|
|
|
|
A new image can bring database migrations, and `docker-entrypoint.sh`
|
|
applies them on the first start of that image. Most are additive, but some
|
|
rewrite data, and going back to the previous image does not undo them. The
|
|
only way back from a migration that went wrong is the dump you took before
|
|
it. So take one before every pull:
|
|
|
|
```bash
|
|
# 1. Dump the database (same command as under "Backup and restore").
|
|
docker compose exec -T db pg_dump -U healthlog healthlog \
|
|
| gzip > healthlog-before-update-$(date +%F).sql.gz
|
|
|
|
# 2. Pull the new image and recreate the app container.
|
|
docker compose pull app
|
|
docker compose up -d app
|
|
|
|
# 3. Confirm the running build.
|
|
curl -s http://localhost:3000/api/version
|
|
```
|
|
|
|
Keep the dump until the new version has run for a few days, and keep your
|
|
encryption key with it: a dump without the key cannot be read.
|
|
|
|
The database image is a separate matter: a new Postgres minor is a change of
|
|
the `image:` line, a new major (16 to 18) is a dump and restore, described in
|
|
[`docs/ops/postgres-major-upgrade.md`](../ops/postgres-major-upgrade.md).
|
|
|
|
The start log says what is about to happen before the migrations run:
|
|
|
|
```text
|
|
HealthLog: 2 database migrations pending. Back up the database before updating (pg_dump, see the Updates section of docs/self-hosting/getting-started.md); a migration is not undone by going back to the previous image.
|
|
HealthLog: Running database migrations...
|
|
```
|
|
|
|
or `HealthLog: Database schema is up to date.` when the image brings none.
|
|
The line is a notice and does not pause the start: the migrations run right
|
|
after it. So the dump belongs before step 2, not after you see the line; by
|
|
then the database is already being migrated.
|
|
|
|
If an update to v1.43 stops at migration `0409_drop_plaintext_location`,
|
|
nothing was changed; the recovery is in
|
|
[`docs/ops/migration-0409-plaintext-location.md`](../ops/migration-0409-plaintext-location.md).
|
|
|
|
For the ordering on a host where you want the migration result before the
|
|
new container takes traffic, see [`docs/ops/deploy.md`](../ops/deploy.md).
|