mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
c86f23c2c0
Making `=true` grant nothing would stop a single-user self-host's local model on a patch update. It is deprecated for one release cycle instead, in a narrowed and safe form: it still grants a private host, but only to the operator's own configurations (the instance-wide admin provider and AI settings saved on an admin account), and only through the pinned operator-approved dispatcher, so redirects stay forbidden and metadata, link-local and unspecified addresses stay refused. A non-admin account's own base URL needs an exact origin in AI_PRIVATE_ORIGINS. Provider resolution passes the owning account's role to the client (`operatorTrusted`); the save route and the connection test apply the same rule to the account being configured. The boot summary now says the setting is deprecated and names the replacement, and the admin AI settings page shows the exact AI_PRIVATE_ORIGINS line for the private origins saved on the instance (every account's Local and gateway URL and the admin base URL, scheme, host and port only), so the operator can copy it and drop the old setting.
309 lines
14 KiB
JSON
309 lines
14 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": "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": "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": "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_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"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|