HealthLog/docs/ops/env-check.md

Pre-deploy env-var sanity check

pnpm check-env reads scripts/env-manifest.json and verifies every variable declared required: true is present + non-empty in the runtime environment. Optional groups are surfaced too, so an operator can spot the "3 out of 4 vars set" pattern that silently disables a feature.

This is the answer to the v1.4.40 AP-2 silent-disable: the .p8 file went missing during a Coolify migration, three of four APNS_* vars remained set, the app booted cleanly, and APNs notifications stopped working — undetected for three days because the dispatcher's fallback chain hid the gap behind the Telegram → ntfy → Web Push path.

Usage

Against the live shell

pnpm check-env

Runs against process.env (after the local .env / .env.local load, if any). Exit code 0 on green, 1 on at least one required variable missing, 2 on a malformed manifest.

Against a Coolify export / .env.production

pnpm check-env --file /path/to/.env.production

The file is parsed locally (no shell execution, no variable expansion) and checked against the manifest. Useful for spot-checking a Coolify export without polluting the local shell.

Output format

Output is one row per declared variable, grouped by section. Three states:

Marker	Meaning
[OK]	Variable is set and non-empty.
[MISSING-REQUIRED]	Variable is required for boot. The script exits 1.
[missing-optional]	Variable is optional. The script reports it but does not fail.

The grep-friendly format lets a CI pipeline do grep -q '\[MISSING-REQUIRED\]' to gate a deploy. CI already does: the env-check.yml workflow runs pnpm check-env --file .env.production.example on every PR and fails on missing required vars.

All-or-none groups

Some groups (e.g. off-host backups) are marked allOrNone: true in the manifest. When such a group is partially populated — some vars set, some missing — the script emits a synthetic <all-or-none> row with severity REQUIRED, even if the surrounding group is required: false. This is the v1.4.40 AP-2 detection pattern.

Example output for a partial APNs config:

# APNs (iOS push)
  [OK] APNS_KEY_ID
  [OK] APNS_TEAM_ID
  [OK] APNS_BUNDLE_ID
  [missing-optional] APNS_KEY — Satisfied by any of: APNS_KEY, APNS_KEY_FILE
  [MISSING-REQUIRED] <all-or-none> — Group is all-or-none but only 3/4 variables are set. Either set all or unset all.

The APNs group is allOrNone: true, so the partial config also emits the synthetic <all-or-none> row at REQUIRED severity and the run exits 1. A reviewer immediately sees that APNS_KEY (or its APNS_KEY_FILE alternative) is missing while the other three APNs vars are set — the exact configuration that silently disables iOS push.

Editing the manifest

The manifest lives at scripts/env-manifest.json and is git-tracked so changes go through a PR. To add a new variable:

1. Pick the right group (or add a new one if the variable doesn't belong to any existing category).
2. Decide whether the variable is required for boot, optional, or part of an all-or-none feature group.
3. Document the variable's purpose in one sentence — the operator reads this text when the var shows up as missing.
4. Run pnpm check-env locally against your live shell to confirm the manifest still passes (or fails for the right reason).
5. Add a regression test under scripts/__tests__/check-env.test.ts if the manifest change introduces a new classification branch (anyOf, allOrNone, …).

CI gate

The GitHub Actions workflow .github/workflows/env-check.yml runs pnpm check-env --file .env.production.example on every PR, blocking changes that introduce new required vars without updating the example file.

Still an idea only: a Coolify pre-deploy hook that runs pnpm check-env inside the target container and aborts the deploy on exit code 1.