Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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
|
||||
|
||||
|
||||
Reference in new issue
Block a user