mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-07 04:12:04 +00:00
Marc-André Bombeck
69bae8bdb4
At a first start there is no recorded key yet, so an operator facing a refusal they are certain is false has no row to delete. With ENCRYPTION_KEY_CHECK=warn (default enforce) the check still runs and logs its full outcome, /api/health names a mismatch as a warning field without failing, requests are served, and no key is recorded unless every key id passes. The variable is on the compose whitelist, in both example files, the env manifest, the Unraid and Portainer templates and the published-env guard. The log block, the mismatch page and the self-hosting pages offer it as the last resort after the three real fixes, and say that it disables a safety check.
354 lines
17 KiB
JSON
354 lines
17 KiB
JSON
{
|
|
"$schema": "./env-manifest.schema.json",
|
|
"description": "Manifest of env vars required by a HealthLog production deployment. Used by `pnpm check-env` to catch missing/empty vars BEFORE a deploy ships. v1.4.42 W6 \u2014 born out of the v1.4.40 AP-2 .p8 install gap that shipped silently for 3 days.",
|
|
"groups": [
|
|
{
|
|
"name": "Core",
|
|
"description": "Database, app URL, encryption keys. The app refuses to boot without these.",
|
|
"required": true,
|
|
"variables": [
|
|
{
|
|
"name": "DATABASE_URL",
|
|
"purpose": "Postgres connection string. App boot fails if missing.",
|
|
"example": "postgresql://healthlog:<pw>@db:5432/healthlog?schema=public"
|
|
},
|
|
{
|
|
"name": "POSTGRES_PASSWORD",
|
|
"purpose": "Database password for the bundled `db` service in docker-compose.yml.",
|
|
"example": "<openssl rand -hex 32>"
|
|
},
|
|
{
|
|
"name": "NEXT_PUBLIC_APP_URL",
|
|
"purpose": "Public URL embedded in OAuth redirects, webhook callbacks, APNs deep-links."
|
|
},
|
|
{
|
|
"name": "APP_URL",
|
|
"purpose": "Server-side mirror of NEXT_PUBLIC_APP_URL; used by background workers."
|
|
},
|
|
{
|
|
"name": "ENCRYPTION_KEY",
|
|
"purpose": "AES-256-GCM key for at-rest encryption of provider tokens. 64 hex chars (32 bytes). Required unless ENCRYPTION_KEYS is set."
|
|
},
|
|
{
|
|
"name": "API_TOKEN_HMAC_KEY",
|
|
"purpose": "HMAC-SHA256 key for hashing external Bearer tokens AND web session cookies. 64 hex chars. Rotating it signs every browser session out on top of invalidating every issued token."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Withings OAuth",
|
|
"description": "Withings API credentials are entered per user in Settings \u2192 Integrations (no env-var path). Only the webhook shared secret is operator-level.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "WITHINGS_WEBHOOK_SECRET",
|
|
"purpose": "Random secret carried as a path segment in the Withings webhook callback URL. Generate with `openssl rand -hex 32`."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Polar OAuth",
|
|
"description": "Required to enable the Polar AccessLink integration. App boots without these but the Polar connect button stays disabled. Register an app at https://admin.polaraccesslink.com and set the redirect URI to ${NEXT_PUBLIC_APP_URL}/api/polar/callback.",
|
|
"required": false,
|
|
"allOrNone": true,
|
|
"variables": [
|
|
{
|
|
"name": "POLAR_CLIENT_ID",
|
|
"purpose": "Polar AccessLink OAuth client id."
|
|
},
|
|
{
|
|
"name": "POLAR_CLIENT_SECRET",
|
|
"purpose": "Polar AccessLink OAuth client secret."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Oura OAuth",
|
|
"description": "Required to enable the Oura Cloud v2 integration. App boots without these but the Oura connect button stays disabled. Register an app at https://cloud.ouraring.com/oauth/applications and set the redirect URI to ${NEXT_PUBLIC_APP_URL}/api/oura/callback.",
|
|
"required": false,
|
|
"allOrNone": true,
|
|
"variables": [
|
|
{
|
|
"name": "OURA_CLIENT_ID",
|
|
"purpose": "Oura Cloud OAuth client id."
|
|
},
|
|
{
|
|
"name": "OURA_CLIENT_SECRET",
|
|
"purpose": "Oura Cloud OAuth client secret."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "OIDC SSO login",
|
|
"description": "Required to enable SSO login against a self-hosted identity provider (Authentik, Keycloak, Authelia, Google Workspace, etc.). App boots without these but the login page's SSO button stays hidden. Register a confidential client with redirect URI ${NEXT_PUBLIC_APP_URL}/api/auth/oidc/callback.",
|
|
"required": false,
|
|
"allOrNone": true,
|
|
"variables": [
|
|
{
|
|
"name": "OIDC_ISSUER_URL",
|
|
"purpose": "OIDC provider issuer URL (discovery doc served at <issuer>/.well-known/openid-configuration)."
|
|
},
|
|
{
|
|
"name": "OIDC_CLIENT_ID",
|
|
"purpose": "OIDC confidential client id."
|
|
},
|
|
{
|
|
"name": "OIDC_CLIENT_SECRET",
|
|
"purpose": "OIDC confidential client secret."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "OIDC SSO options",
|
|
"description": "Optional tuning for an enabled OIDC provider. Each stands alone (deliberately NOT allOrNone \u2014 any subset is valid) and each has a safe default when unset.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "OIDC_SCOPES",
|
|
"purpose": "Space-separated scopes requested at authorization. Default: \"openid email profile\"."
|
|
},
|
|
{
|
|
"name": "OIDC_BUTTON_LABEL",
|
|
"purpose": "Label on the login page's SSO button. Default: \"Single Sign-On\"."
|
|
},
|
|
{
|
|
"name": "OIDC_ONLY",
|
|
"purpose": "\"true\" disables password/passkey login server-side (only effective when the OIDC provider group is fully configured). Default: additive login. Locks the native iOS app out of sign-in."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "AI Provider",
|
|
"description": "Optional runtime policy and output tuning for user-configured AI providers. Each variable stands alone and has a safe default when unset.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "AI_PRIVATE_ORIGINS",
|
|
"purpose": "AI endpoints on the operator's own network (Ollama, LM Studio, LiteLLM). Comma-separated exact origins (scheme://host[:port]), e.g. \"http://ollama.lan:11434\". Unset, a private AI base URL is refused (apart from what the deprecated ALLOW_LOCAL_AI_PRIVATE_HOSTS=true still covers). Link-local, metadata and unspecified addresses stay refused even when listed; a malformed entry is logged once and grants nothing."
|
|
},
|
|
{
|
|
"name": "ALLOW_LOCAL_AI_PRIVATE_HOSTS",
|
|
"purpose": "Older form of AI_PRIVATE_ORIGINS, kept for existing installs: an exact comma-separated host list still grants those hosts. \"true\" is deprecated since v1.39.3: it covers only the admin AI key and AI settings saved on an admin account (pinned; metadata and link-local refused), is reported at boot and on the admin AI settings page, and will be removed in a later release."
|
|
},
|
|
{
|
|
"name": "INSIGHTS_MAX_TOKENS",
|
|
"purpose": "Daily-briefing output-token ceiling. Default 2500, clamped to 500-8000."
|
|
},
|
|
{
|
|
"name": "INSIGHTS_RATE_LIMIT_PER_HOUR",
|
|
"purpose": "Per-user hourly ceiling for POST /api/insights/generate. Default 10; values below 1 fall back to the default."
|
|
},
|
|
{
|
|
"name": "DOCUMENT_AI_LIMIT_PER_HOUR",
|
|
"purpose": "Per-user hourly ceiling for the document-AI actions (read/index, extract, suggest, summarise share one bucket). Default 6, clamped to 1-1000."
|
|
},
|
|
{
|
|
"name": "DOCUMENT_UPLOAD_LIMIT_PER_HOUR",
|
|
"purpose": "Hourly upload ceiling per document-upload token (Paperless workflow, import script). Default 120, clamped to 1-1000. Web and phone uploads keep their own bucket."
|
|
},
|
|
{
|
|
"name": "LABS_OCR_LIMIT_PER_HOUR",
|
|
"purpose": "Per-user hourly ceiling for lab-report scans (photo/PDF and browser-OCR text share one bucket). Default 6, clamped to 1-1000."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Offline geolocation",
|
|
"description": "Optional offline GeoLite2 tier for the admin login overview. Unset, the runtime reads /opt/geolite2 (the path the image bakes its own copy into) and falls back to the online provider when the databases are absent.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "GEOLITE2_DIR",
|
|
"purpose": "Directory holding GeoLite2-City.mmdb + GeoLite2-ASN.mmdb. Point it at a read-only mount to bring your own databases. Default /opt/geolite2."
|
|
},
|
|
{
|
|
"name": "MAXMIND_LICENSE_KEY",
|
|
"purpose": "MaxMind licence key for the runtime GeoLite2 fetch (issue #659). Set it and the worker downloads both databases into GEOLITE2_DIR on boot and monthly, no rebuild or manual mount. Free at maxmind.com/en/geolite2/signup."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Outbound requests",
|
|
"description": "Switches for the requests HealthLog makes to third parties on its own. All default to on; set any of them to 1, true or yes to turn that request off.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "IP_GEO_LOOKUP_DISABLED",
|
|
"purpose": "Stops the online IP-to-location lookup for login events and the monthly MaxMind download. Only the local GeoLite2 databases are used."
|
|
},
|
|
{
|
|
"name": "PASSWORD_BREACH_CHECK_DISABLED",
|
|
"purpose": "Stops the HaveIBeenPwned range query made when a password is set. The query carries the first five hex characters of the password's SHA-1, never the password or the full hash."
|
|
},
|
|
{
|
|
"name": "UPDATE_CHECK_DISABLED",
|
|
"purpose": "Stops the daily request to the GitHub releases API behind the About page and the admin version tile."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "APNs (iOS push)",
|
|
"description": "All four core APNS_* vars together. Missing any disables APNs silently \u2014 the v1.4.40 AP-2 gap that motivated this manifest. allOrNone trips the synthetic <all-or-none> required row whenever 1-3 of the 4 are set.",
|
|
"required": false,
|
|
"allOrNone": true,
|
|
"variables": [
|
|
{
|
|
"name": "APNS_KEY_ID",
|
|
"purpose": "10-char Key ID from Apple Developer."
|
|
},
|
|
{
|
|
"name": "APNS_TEAM_ID",
|
|
"purpose": "10-char Team ID from Apple Developer."
|
|
},
|
|
{
|
|
"name": "APNS_BUNDLE_ID",
|
|
"purpose": "iOS app bundle id, e.g. dev.healthlog.ios."
|
|
},
|
|
{
|
|
"name": "APNS_KEY",
|
|
"purpose": "APNs auth key (.p8 contents). Use APNS_KEY for 12-factor env-block deploys; APNS_KEY_FILE is the filesystem alternative \u2014 at least one of the two must be set.",
|
|
"anyOf": ["APNS_KEY", "APNS_KEY_FILE"]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Deploy webhook",
|
|
"description": "Coolify -> HealthLog deploy-result webhook. Without this, the auto-deploy success/failure feedback loop is broken.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "DEPLOY_WEBHOOK_SECRET",
|
|
"purpose": "Shared secret for the X-Deploy-Webhook-Secret header on POST /api/internal/deploy-webhook. 64 hex chars."
|
|
},
|
|
{
|
|
"name": "DEPLOY_LOGS_URL",
|
|
"purpose": "URL of the deployment dashboard (e.g. the Coolify UI) linked in deploy-failure notifications. Optional; when unset the notification omits the link."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "TLS leaf pin monitor",
|
|
"description": "Baseline for the TLS leaf SPKI-change alarm. The native client pins the served leaf certificate; without this the monitor logs the served pin but cannot alarm on a rotation. See docs/ops/tls-cert-pin.md.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "TLS_LEAF_SPKI_PINS",
|
|
"purpose": "Comma-separated known-good leaf SPKI pins, base64(sha256(DER subjectPublicKeyInfo)) \u2014 the same value the native client pins. Hold both the current and the next pin during a dual-pin renewal window."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "SMTP (email channel)",
|
|
"description": "Operator SMTP transport for the email notification channel (v1.17.1). All of SMTP_HOST, SMTP_PORT, SMTP_FROM together enable the channel; SMTP_USER/SMTP_PASS are optional (unauthenticated relay). Missing any of the three core vars disables email silently \u2014 the channel is never offered and the Settings card hides itself.",
|
|
"required": false,
|
|
"allOrNone": true,
|
|
"variables": [
|
|
{
|
|
"name": "SMTP_HOST",
|
|
"purpose": "SMTP server hostname, e.g. smtp.example.com."
|
|
},
|
|
{
|
|
"name": "SMTP_PORT",
|
|
"purpose": "SMTP port. 587 for STARTTLS (SMTP_SECURE unset/false), 465 for implicit TLS (SMTP_SECURE=true)."
|
|
},
|
|
{
|
|
"name": "SMTP_FROM",
|
|
"purpose": "From address for outbound mail, e.g. \"HealthLog <noreply@example.com>\"."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Notification targets on a private network",
|
|
"description": "Operator grant for webhook (Gotify, Home Assistant, n8n) and ntfy targets on the operator's own network. Unset, a target that resolves to a private address is refused at send time and the test button reports private_origin_not_approved. Optional; public targets never need it.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "NOTIFICATION_PRIVATE_ORIGINS",
|
|
"purpose": "Comma-separated exact origins (scheme://host[:port], no path, no wildcard, no CIDR), e.g. \"https://gotify.example.com,http://ntfy.lan:8080\". Link-local, metadata and unspecified addresses stay refused even when listed; a malformed entry is logged once and grants nothing."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Document picker",
|
|
"description": "Operator grant for the document picker, which lets a person search their own Paperless-ngx or Papra instance and import picked documents. Unset, the picker is off. Optional.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "DOCUMENT_SOURCE_ORIGINS",
|
|
"purpose": "Comma-separated exact origins (scheme://host[:port], no path, no wildcard, no CIDR), e.g. \"https://paperless.example.com,http://papra.lan:1221\". Only listed origins are contacted, public or private; redirects are not followed; link-local, metadata and unspecified addresses stay refused even when listed; a malformed entry is logged once and grants nothing."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Off-host backups",
|
|
"description": "Required ALL-OR-NONE: any of these without the rest disables backups silently.",
|
|
"required": false,
|
|
"allOrNone": true,
|
|
"variables": [
|
|
{
|
|
"name": "BACKUP_S3_ENDPOINT",
|
|
"purpose": "S3-compatible endpoint URL."
|
|
},
|
|
{
|
|
"name": "BACKUP_S3_BUCKET",
|
|
"purpose": "Bucket name."
|
|
},
|
|
{
|
|
"name": "BACKUP_S3_ACCESS_KEY",
|
|
"purpose": "S3 access key."
|
|
},
|
|
{
|
|
"name": "BACKUP_S3_SECRET_KEY",
|
|
"purpose": "S3 secret key."
|
|
},
|
|
{
|
|
"name": "BACKUP_ENCRYPTION_KEY",
|
|
"purpose": "Separate AES key for the backup body \u2014 MUST NOT match ENCRYPTION_KEY."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Operational windows and cookie flags",
|
|
"description": "Values the product states back to a user or that decide whether a session cookie is accepted. Optional: each has a documented default. They are listed so `pnpm check-env` reports them, and so the compose whitelist and the example files can be held in step with this manifest.",
|
|
"required": false,
|
|
"variables": [
|
|
{
|
|
"name": "AUDIT_LOG_RETENTION_DAYS",
|
|
"purpose": "How long audit rows survive, in days (365 by default). Published, not merely enforced: the shared-access activity feed and the dialog that ends somebody's access both state the number back to the user.",
|
|
"example": "365"
|
|
},
|
|
{
|
|
"name": "SESSION_COOKIE_SECURE",
|
|
"purpose": "Forces the Secure flag on every cookie the app issues. Unset, it tracks NODE_ENV. Set false for a LAN / VPN-only self-host served over plain HTTP, where the default makes login look broken.",
|
|
"example": "false"
|
|
},
|
|
{
|
|
"name": "HEALTHLOG_PLATFORM",
|
|
"purpose": "Where this server's environment is configured (compose, truenas, coolify, unraid, portainer). Shown back to the admin: the \"Back up your encryption key\" step opens on that platform's instructions. Unset means compose.",
|
|
"example": "compose"
|
|
},
|
|
{
|
|
"name": "ENCRYPTION_KEY_CHECK",
|
|
"purpose": "The start-up encryption key check. enforce (default) refuses to serve when the configured key does not open the stored data; warn only logs the finding, names it as a warning on /api/health, serves anyway and records no key until the check passes. A last resort for a refusal the operator is certain is false; it disables a safety check.",
|
|
"example": "enforce"
|
|
},
|
|
{
|
|
"name": "TRUST_PROXY_HOPS",
|
|
"purpose": "Trusted reverse-proxy hop count; the client IP is read that many entries from the right of X-Forwarded-For.",
|
|
"example": "1"
|
|
},
|
|
{
|
|
"name": "BACKUP_ENCRYPTION_PREVIOUS_KEYS",
|
|
"purpose": "Comma-separated off-host backup keys that are no longer written with but may still be needed to read older objects. Set during a rotation of BACKUP_ENCRYPTION_KEY until the bucket's lifecycle rule has retired every object written under the old key.",
|
|
"example": ""
|
|
},
|
|
{
|
|
"name": "BACKUP_MAX_STORED_MB",
|
|
"purpose": "Largest stored backup of one account the app keeps, in megabytes of encrypted copy (2048 by default). A storage limit, independent of the app's memory: a backup past it fails with a message naming this variable, and the previous copy stays.",
|
|
"example": "2048"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|