Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -15,6 +15,7 @@ Use placeholder-only examples when explaining required shape:
```sh
DATABASE_URL=<DATABASE_URL>
SESSION_SECRET=<SESSION_SECRET>
AUDIT_CHAIN_SECRET=<AUDIT_CHAIN_SECRET>
MAILJET_API_KEY=<MAILJET_API_KEY>
```
@@ -34,17 +35,23 @@ These keys are required for normal production application runtime unless the dep
| --- | --- | --- | --- |
| `APP_NAME` | Shared web/API/worker runtime | Human-readable product name for titles, metadata, and seeded app configuration. | Key name and configured/unconfigured status. |
| `DATABASE_URL` | Web/API runtime and Prisma operations | Primary application database connection. | Key name, missing/present status, migration status code. |
| `SESSION_SECRET` | Web/API runtime | Session signing and verification boundary. | Key name and redacted validator code only. |
| `SESSION_SECRET` | Core web/API runtime | Core session signing and verification boundary; forbidden on the customer-portal resource. | Key name and redacted validator code only. |
| `WEB_RUNTIME_SURFACE` | Web runtime boundary | Selects exactly one surface, `core` or `portal`; production web resources fail closed without it. | Key name and enum-validation status only. |
| `PORTAL_SESSION_SECRET` | Customer-portal web runtime | Dedicated portal-cookie signing boundary; required only on `hivegrid-portal` and forbidden on core web. | Key name and redacted validator code only. |
| `AUDIT_CHAIN_SECRET` | Web/API/MCP/worker audit boundary | HMAC authentication for AuditEvent v2 hashes and retention checkpoints; minimum 32 bytes and stable across the retention lifetime. | Key name and redacted validator code only. |
| `APP_BASE_DOMAIN` | Split-host routing boundary | Root domain used to derive canonical app, admin, and API hosts. | Key name and host-normalization status only. |
| `WEB_APP_HOST` | Tenant web runtime | Canonical host for tenant app traffic, such as `app.<domain>`. | Key name and host-normalization status only. |
| `ADMIN_APP_HOST` | Admin web runtime | Canonical host for admin traffic, such as `admin.<domain>`. | Key name and host-normalization status only. |
| `API_HOST` | API runtime | Canonical host for versioned API traffic, such as `api.<domain>`. | Key name and host-normalization status only. |
| `CRYPTO_SECRET` | Web/API runtime | Application encryption/signing boundary for protected data. | Key name and redacted validator code only. |
| `PORTAL_APP_HOST` | Core/customer-portal web and mail-worker runtimes | Canonical host for the isolated customer portal and the origin for status-mail links; must differ from app, admin, API, and base-domain hosts. | Key name and host-normalization status only. |
| `CRYPTO_SECRET` | Web/API and mail-worker runtime | Shared tenant-envelope master key. `worker-mail` must receive the exact `hivegrid-web` value so portal setup capabilities can be decrypted only at delivery time. | Key name and redacted validator code only; never print or compare the value in logs. |
| `ADMIN_CONNECTION_MASTER_KEY` | Core web, API and admin-sales mail worker | Dedicated envelope-wrapping key for tenant-less AdminDataConnection credentials. Staging and production use distinct values; never reuse `CRYPTO_SECRET` or a session secret. | Key name and redacted validator code only; never print, compare or copy the value into logs or tickets. |
| `API_ACCESS_TOKEN` | Web/API runtime | Service-token boundary for internal and API operator calls. | Key name and redacted validator code only. |
| `JWT_SECRET` | API runtime | API session JWT signing and verification boundary. | Key name and redacted validator code only. |
| `ANALYTICS_TOKEN` | API runtime | Analytics ingestion and public analytics API token boundary. | Key name and redacted validator code only. |
| `ANALYTICS_TOKEN` | API runtime | Browser-facing anonymous analytics ingestion capability only; it never authorizes analytics reads or identity attribution. | Key name and redacted validator code only. |
| `MCP_RESOURCE_URL` | MCP connector runtime | Public origin of the MCP resource server; used for RFC 9728 protected-resource metadata and OAuth audience binding. | Key name and host-normalization status only. |
| `MCP_AUTHORIZATION_SERVER_URL` | Web/MCP runtime | Public origin of the OAuth authorization server (the web app) that issues MCP access tokens. | Key name and host-normalization status only. |
| `WEB_PUSH_VAPID_PUBLIC_KEY` | Web and webhook-worker push boundary | Shared browser subscription key for incoming-call Web Push. Production web and webhook-worker deployments must receive the same generated key pair source. | Key name, configured/unconfigured status, and validation code only. |
`DIRECT_URL` is database-owned and may be required by Prisma or deployment-specific migration workflows. Treat it as secret material whenever present, and document only whether the key is configured for the workflow being run.
@@ -56,7 +63,8 @@ Optional integration keys are feature-gated. Missing optional keys should produc
| --- | --- | --- | --- |
| `WORKER_ENABLED` | Worker runtime | Queue processors should start for the deployment. | Boolean enablement status and diagnostic code. |
| `BULLMQ_REDIS_URL` | Web/API enqueue and worker runtime | Queue-backed features are enabled and need BullMQ connectivity. | Key name, missing/present status, queue readiness code. |
| `REDIS_URL` | Web/API enqueue and worker fallback | `BULLMQ_REDIS_URL` is absent and the deployment intentionally uses the generic Redis key. | Fallback key name and readiness code only. |
| `REDIS_URL` | MCP shared store; web/API/worker fallback | Always required by MCP in production; elsewhere used only when `BULLMQ_REDIS_URL` is absent and the deployment intentionally uses the generic Redis key. | Key name and readiness code only. |
| `AUTHENTIK_ADMIN_JIT_DATABASE_URL` | Authentik admin callback on the web runtime | Admin SSO is enabled and the verified callback may JIT-link or create an operator identity. The URL must authenticate as the execute-only `hivegrid_authentik_jit` role. | Key name, configured/unconfigured status, and exact-role diagnostic only; never log the URL. |
| `MAILJET_API_KEY` | Mail provider boundary | Outbound Mailjet delivery is enabled. | Key name and redacted validator code only. |
| `API_KEY_LEGACY_PLAINTEXT_FALLBACK` | API-key cutover boundary | Temporary plaintext API-key lookup fallback is disabled by default; enable only during a bounded hash-backfill migration window. | Boolean status only; never record API-key material. |
| `MAILJET_FROM_EMAIL` | Mail provider boundary | Outbound Mailjet delivery is enabled. | Key name and sender-domain validation status only. |
@@ -70,10 +78,10 @@ Optional integration keys are feature-gated. Missing optional keys should produc
| `MOLLIE_API_KEY` | Payment provider boundary | Mollie payment checkout or webhook refetch is enabled. | Key name, mode label, and redacted validator code only. |
| `MOLLIE_PROFILE_ID` | Payment provider boundary | Mollie payment creation requires an explicit website profile. | Key name and configured/unconfigured status. |
| `MOLLIE_TIMEOUT_MS` | Payment provider boundary | Mollie payment gateway uses a non-default timeout. | Timeout parse status only. |
| `PORTAL_SERVER_URL` | Portal/site-builder boundary | Portal server integration is enabled. | Key name, present/missing status, and redacted URL validation code only. |
| `PORTAL_SERVER_FLY_TOKEN` | Portal automation boundary | Portal server automation is enabled. | Key name and redacted validator code only. |
| `BILLING_MOLLIE_WEBHOOK_URL` | General-worker recurring billing boundary | Recurring Lago invoices may create Mollie payments. | Key name and validation status only; the value must be the environment-specific HTTPS API webhook route. |
| `IMPORT_QUEUE_ENABLED` | Web enqueue and worker runtime | Import jobs should be sent through BullMQ. | Boolean enablement status and diagnostic code. |
| `IMPORT_QUEUE_RUNTIME_READY` | Web enqueue and worker runtime | Import queue processors and scan/import services are wired end to end. | Boolean readiness status and diagnostic code. |
| `PORTAL_GDPR_EXPORT_QUEUE_ENABLED` | Internal worker runtime | The import worker may consume only portal/privacy GDPR jobs from `hivegrid.exports`. | Boolean enablement status and diagnostic code only. |
| `MISTRAL_API_KEY` | AI provider boundary | Mistral generation is enabled. | Key name and redacted provider-readiness code only. |
| `MISTRAL_MODEL` | AI provider boundary | Mistral generation uses a non-default model. | Model label only when approved for release records. |
| `AI_PROCESSING_REGION` | AI provider boundary | AI generation is enabled under a deployment-region policy. | Expected region label and confirmation status only. |
@@ -91,6 +99,7 @@ Optional integration keys are feature-gated. Missing optional keys should produc
| `STORAGE_BUCKET` | Storage provider boundary | S3-compatible upload/download operations need a default bucket. | Bucket alias or configured/unconfigured status only; avoid customer-specific bucket names in incidents. |
| `STORAGE_ACCESS_KEY_ID` | Storage provider boundary | S3-compatible storage is enabled. | Key name and redacted validator code only. |
| `STORAGE_SECRET_ACCESS_KEY` | Storage provider boundary | S3-compatible storage is enabled. | Key name and redacted validator code only. |
| `GDPR_EXPORT_SSE_C_KEY_BASE64` | GDPR export storage boundary | Portal/privacy export objects are encrypted with SSE-C. Production core/portal web and the dedicated export worker must receive the same canonical Base64 value for 32 random bytes. | Key name and missing/invalid status only; never log, diff, or print the value. |
| `STORAGE_SESSION_TOKEN` | Storage provider boundary | Temporary S3-compatible credentials are used. | Key name and redacted validator code only. |
| `STORAGE_PUBLIC_BASE_URL` | Storage provider boundary | A CDN or public base URL is configured for storage object URLs. | Provider endpoint label or redacted URL validation code only. |
| `STORAGE_FORCE_PATH_STYLE` | Storage provider boundary | The S3-compatible provider requires path-style bucket addressing. | Boolean status only. |
@@ -99,9 +108,24 @@ Optional integration keys are feature-gated. Missing optional keys should produc
## Worker key group
`WORKER_ENABLED` controls whether queue processors start. Set it to `true` only in deployments that should run background jobs. When queue-backed web/API features enqueue jobs or workers process jobs, prefer `BULLMQ_REDIS_URL` for BullMQ Redis connectivity; `REDIS_URL` is a fallback only when `BULLMQ_REDIS_URL` is absent and the deployment intentionally uses the shared Redis key.
`WORKER_ENABLED` controls whether queue processors start. Set it to `true` only in deployments that should run background jobs. MCP requires `REDIS_URL` in production for distributed abuse limits and readiness. When queue-backed web/API features enqueue jobs or workers process jobs, prefer `BULLMQ_REDIS_URL` for BullMQ Redis connectivity; those runtimes use `REDIS_URL` only as a fallback when `BULLMQ_REDIS_URL` is absent.
`IMPORT_QUEUE_ENABLED` and `IMPORT_QUEUE_RUNTIME_READY` must both be `true` before tenant import submissions enqueue jobs. Keep them disabled unless the worker runtime can process the import queue end to end.
`IMPORT_QUEUE_ENABLED` and `IMPORT_QUEUE_RUNTIME_READY` must both be `true` before tenant import submissions enqueue jobs. Full mode owns `hivegrid.exports` too, so it also requires complete HTTPS `STORAGE_*`, a canonical `GDPR_EXPORT_SSE_C_KEY_BASE64`, and generic plus portal/privacy GDPR export services. Keep the gates disabled unless the worker runtime can process both queues end to end.
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` is a worker-only, internal alternative
for `WORKER_QUEUE_GROUP=import`. Keep both `IMPORT_QUEUE_*` gates unset or
`false`; the worker then owns only `hivegrid.exports` and requires complete
`STORAGE_*`, `GDPR_EXPORT_SSE_C_KEY_BASE64` and portal/privacy GDPR export
service wiring. The same key is mandatory on both production web surfaces so
downloads remain server-proxied; it must never be placed in a URL or browser
header. The modes are
mutually exclusive and fail closed on mixed gates or another worker group.
`worker-general` requires `MEILI_URL` and the HiveGrid-scoped `MEILI_API_KEY`
whenever tenant hard-delete runs under production, required RLS, or a
staging/production Sentry marker. Missing values or a missing search client
abort startup before queue ownership so a deletion request cannot complete
while tenant documents remain indexed.
Staging and production `worker-general` services must also fail loud for
outbox and workflow fanout. Set `OUTBOX_DISPATCHER_ENABLED=true`,
@@ -137,11 +161,11 @@ Diagnostics may say that a required Mailjet key is missing, a sender domain is n
`AI_PROCESSING_REGION` must match the approved deployment-region policy when AI generation is enabled. The cataloged AI provider keys currently include Mistral, Scaleway, and Aleph Alpha entries; deployment records must define the allowed provider order and region labels before production traffic is routed. `SCALEWAY_REGION` and `SCALEWAY_BASE_URL` are provider-specific markers and must match the deployment record.
`LAGO_API_URL`, `LAGO_API_KEY`, and `LAGO_WEBHOOK_SECRET` are the AD-27 billing-engine keys. `MOLLIE_API_KEY` and `MOLLIE_PROFILE_ID` are the payment-processor keys. Keep Lago and Mollie production values separate from staging/testmode values, and never paste provider keys, webhook secrets, payment references, invoice payloads, tenant identifiers, or customer identifiers into docs or verification records.
`LAGO_API_URL`, `LAGO_API_KEY`, and `LAGO_WEBHOOK_SECRET` are the AD-27 billing-engine keys. `MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID`, and the environment-specific `BILLING_MOLLIE_WEBHOOK_URL` are the payment-processor boundary keys. Keep Lago and Mollie production values separate from staging/testmode values, and never paste provider keys, webhook secrets, payment references, invoice payloads, tenant identifiers, or customer identifiers into docs or verification records.
## Portal provider key group
## Customer-portal runtime key group
`PORTAL_SERVER_URL` and `PORTAL_SERVER_FLY_TOKEN` belong to optional portal/site-builder automation. A missing portal key should make that feature unavailable with a redacted diagnostic rather than blocking unrelated core auth, tenant, admin, API, or worker boot.
The core and portal containers use the same immutable web image but separate resources and secrets. Set `WEB_RUNTIME_SURFACE=core`, `SESSION_SECRET`, `DATABASE_RUNTIME_ROLE=hivegrid_app`, and `PORTAL_APP_HOST` on core web. Set `WEB_RUNTIME_SURFACE=portal`, `PORTAL_SESSION_SECRET`, `DATABASE_RUNTIME_ROLE=hivegrid_portal`, `PORTAL_APP_HOST`, `REDIS_URL`, and the selected CAPTCHA provider keys on `hivegrid-portal`. Both web resources receive the same `GDPR_EXPORT_SSE_C_KEY_BASE64` as the dedicated GDPR export worker; this export-decryption secret stays server-only. Core, portal, import worker, and general worker require complete `STORAGE_*` credentials but may use the same existing `STORAGE_ACCESS_KEY_ID`/`STORAGE_SECRET_ACCESS_KEY` pair; credential separation is optional and shared credentials are not a rollout blocker. The general worker must not receive the SSE-C key. For the tenant-export barrier only, import and general resolve SharedStore from non-empty `REDIS_URL` before `BULLMQ_REDIS_URL` and must target the same normalized Redis endpoint and database. The staging Compose reference maps storage credentials from `WEB_STORAGE_*`, `WORKER_IMPORT_STORAGE_*`, and `WORKER_GENERAL_STORAGE_*`; those sources may resolve to the same pair, while portal remains a separate Coolify resource. Never copy core session, OAuth, billing, ingress, migration, seed, or retired `PORTAL_SERVER_*` credentials into the portal resource. The exact operator matrix and rollout order live in [`docs/deploy/customer-portal.md`](./deploy/customer-portal.md).
## Database key group