mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
1e09f30eff
A stored backup was one value in data_backups.data. v1.39.1 wrote it a piece at a time but still joined the pieces into that one value, and one value has to pass through the app whole, so a copy was capped at a fifth of the heap: 105 MB in the default 1 GB container. An account with 1.75 million readings is past that and could not be backed up at all (#1031). A copy is now kept as ordered pieces of about a megabyte in the new data_backup_chunks table (migration 0352). Each piece is sealed on its own with AES-256-GCM, and its sealed header names the copy (a random stream id kept on the row), its position and whether it is the last. A reader checks every piece before it releases a byte, so a piece that is missing, moved, altered, taken from another copy, or a copy cut short is refused with backup.payload.undecryptable before a restore deletes anything, and the second read during the restore checks each piece again. The write is one transaction, so the previous copy stays whole and readable until the new one commits. Pieces are written through the model API: a raw query with a large parameter is kept alive by Prisma's query plan cache, which left 160 MB of heap behind per hundred one-megabyte inserts. Restore, preview, download, the restore job and the admin list read both forms; copies written before this change keep their single value and still restore. The heap-derived limit is gone. The one limit left is on storage, BACKUP_MAX_STORED_MB (default 2048), and its message names the setting. Key rotation covers the pieces, the wipe and account deletion take them with their backup, and the backup plan lists the table as not carried. Measured on an account of 2.6 million readings in a 1 GB container with web and worker in one process: backup 87 s, 97 MiB in 96 pieces, preview 20 s, download 25 s, restore 264 s with every reading back exactly, peak 567 MiB, no restart.
301 lines
13 KiB
JSON
301 lines
13 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": "ALLOW_LOCAL_AI_PRIVATE_HOSTS",
|
|
"purpose": "Local-AI SSRF opt-in. Unset rejects private/internal hosts; set an exact comma-separated host allowlist or \"true\" to allow any private host."
|
|
},
|
|
{
|
|
"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": "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"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|