Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/config/src/catalog.ts
T

2733 lines
101 KiB
TypeScript

import type { EnvVariableDefinition, RuntimeTarget } from "./types.js";
const allTargets = ["shared", "web", "api", "mcp", "worker"] as const satisfies readonly RuntimeTarget[];
const webApiTargets = ["web", "api"] as const satisfies readonly RuntimeTarget[];
const apiWorkerTargets = ["api", "worker"] as const satisfies readonly RuntimeTarget[];
const webApiWorkerTargets = ["web", "api", "worker"] as const satisfies readonly RuntimeTarget[];
const webApiMcpWorkerTargets = ["web", "api", "mcp", "worker"] as const satisfies readonly RuntimeTarget[];
export const envVariableDefinitions = [
{
name: "I18N_ENABLED_LOCALES",
description: "Comma-separated product locales that may be selected at runtime.",
classification: "optional-provider",
targets: ["web", "api", "worker"],
kind: "string",
source: "code-and-example",
defaultValue: "de,en",
notes: "Must contain unique supported locale codes and always include de. Review-only locales are rejected in production until their release manifest is approved.",
},
{
name: "APP_NAME",
description: "Human-readable product name used in titles, metadata and seeded app configuration.",
classification: "required-core",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
requiredInProduction: true,
},
{
name: "DATABASE_URL",
description: "Prisma database connection URL.",
classification: "required-core",
targets: allTargets,
kind: "database-url",
source: "code-and-example",
requiredInProduction: true,
},
{
name: "DATABASE_READ_URL",
description: "Optional Postgres read-replica URL used by getReadDbClient() for hot-read paths.",
classification: "optional-provider",
targets: allTargets,
kind: "database-url",
source: "code-and-example",
notes:
"When unset (or empty), getReadDbClient() falls back to DATABASE_URL — single-DB dev / self-hosted setups remain functional without any code change. In staging/production point this at a streaming-replica or PgBouncer-fronted replica. See docs/architecture/rw-split.md.",
},
{
name: "DATABASE_POOL_MAX",
description: "Hard maximum node-postgres connections per process and database client pool.",
classification: "optional-provider",
targets: allTargets,
kind: "string",
source: "code-and-example",
defaultValue: "10",
notes: "Applies separately to the primary and optional read-replica pools. URL connection_limit parameters are ignored by PrismaPg/node-postgres.",
},
{
name: "DATABASE_POOL_IDLE_TIMEOUT_MS",
description: "Idle timeout for primary and read-replica node-postgres connections.",
classification: "optional-provider",
targets: allTargets,
kind: "string",
source: "code-and-example",
defaultValue: "10000",
},
{
name: "DATABASE_POOL_CONNECTION_TIMEOUT_MS",
description: "Maximum time allowed to establish a primary or read-replica database connection.",
classification: "optional-provider",
targets: allTargets,
kind: "string",
source: "code-and-example",
defaultValue: "5000",
},
{
name: "RLS_RUNTIME_MODE",
description: "Postgres RLS startup enforcement mode: off, audit, or required.",
classification: "production-only",
targets: allTargets,
kind: "string",
source: "code-and-example",
notes:
"Defaults to required when NODE_ENV=production and off otherwise. Production services fail startup unless the runtime role and all expected forced policies are active.",
},
{
name: "DATABASE_RUNTIME_ROLE",
description: "Expected restricted Postgres role for application traffic.",
classification: "production-only",
targets: allTargets,
kind: "string",
source: "code-and-example",
defaultValue: "hivegrid_app",
notes:
"Must be a direct login role with NOSUPERUSER and NOBYPASSRLS. App/API/MCP use hivegrid_app; workers require a separate hivegrid_worker DATABASE_URL and set this value to hivegrid_worker. Migration credentials remain isolated in DIRECT_URL.",
},
{
name: "HIVEGRID_CLI_OPERATOR_USER_ID",
description: "Authenticated AdminUser identity bound by database-backed HiveGrid CLI commands.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code",
notes: "Required only for database-backed operator CLI commands; never replaces the restricted runtime database role.",
},
{
name: "SESSION_SECRET",
description: "Cookie/session signing secret.",
classification: "required-core",
targets: ["web", "api"],
kind: "secret",
source: "code-and-example",
requiredInProduction: true,
},
{
name: "WEB_RUNTIME_SURFACE",
description: "Fail-closed web image runtime surface selector.",
classification: "production-only",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Must be core, admin, or portal. Production web runtimes require an explicit value.",
},
{
name: "PORTAL_SESSION_SECRET",
description: "Cookie/session signing secret used exclusively by the customer portal surface.",
classification: "production-only",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "AUDIT_CHAIN_SECRET",
description: "HMAC secret for AuditEvent v2 hashes and retention checkpoints.",
classification: "production-only",
targets: webApiMcpWorkerTargets,
kind: "secret",
source: "code-and-example",
requiredInProduction: true,
notes: "Must contain at least 32 bytes and remain stable for the lifetime of retained audit evidence.",
},
{
name: "APP_BASE_DOMAIN",
description: "Root domain used to derive canonical app, admin and API hosts.",
classification: "required-core",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "localhost",
notes: "Local default is localhost, producing app.localhost, admin.localhost and api.localhost.",
},
{
name: "WEB_APP_HOST",
description: "Canonical host for tenant app traffic.",
classification: "required-per-app",
targets: ["web", "api"],
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "app.localhost",
notes: "Local default is app.localhost.",
},
{
name: "APP_URL",
description: "Canonical public app origin used for generated links and worker-to-web callbacks.",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "url",
source: "code",
notes: "Workers use this for email unsubscribe links and the workflow trigger execution bridge when WORKFLOW_TRIGGER_EXECUTOR_URL is unset.",
},
{
name: "ADMIN_APP_HOST",
description: "Canonical host for admin app traffic.",
classification: "required-per-app",
targets: ["web", "api"],
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "admin.localhost",
notes: "Local default is admin.localhost.",
},
{
name: "API_HOST",
description: "Canonical host for versioned API traffic.",
classification: "required-per-app",
targets: ["api", "web"],
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "api.localhost",
notes: "Local default is api.localhost.",
},
{
name: "PORTAL_APP_HOST",
description: "Canonical host for the isolated customer portal runtime surface.",
classification: "production-only",
targets: ["web", "worker"],
kind: "string",
source: "code-and-example",
defaultValue: "portal.localhost",
notes: "Required by production portal and core web runtimes so host boundaries fail closed; worker-mail uses it for customer status links.",
},
{
name: "PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED",
description: "Explicit production runtime opt-in for customer-portal custom-domain administration and host routing.",
classification: "production-only",
targets: ["web"],
kind: "string",
source: "code",
defaultValue: "false",
notes:
"Must be exactly true on both staging web surfaces while the staging controller is active. Leave unset or false in production until its controller rollout is separately authorised.",
},
{
name: "APP_PROTOCOL",
description: "Canonical URL protocol for generated app, admin and API URLs.",
classification: "production-only",
targets: allTargets,
kind: "string",
source: "example",
defaultValue: "http",
notes: "Use https in production. Local development defaults to http.",
},
{
name: "CRYPTO_SECRET",
description: "Shared AES master secret for tenant-envelope encryption across web, API and the mail worker.",
classification: "required-per-app",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
requiredInProduction: true,
notes: "worker-mail must receive the exact same value as hivegrid-web so portal setup capabilities can be decrypted for delivery.",
},
{
name: "ADMIN_CONNECTION_MASTER_KEY",
description:
"Dedicated AES master secret for tenant-less platform-admin integration credentials.",
classification: "production-only",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
requiredInProduction: true,
notes:
"Use distinct staging and production values on web, API and worker; never reuse CRYPTO_SECRET or SESSION_SECRET.",
},
{
name: "API_ACCESS_TOKEN",
description: "Shared admin/API access token used by legacy API and workflow endpoints.",
classification: "required-per-app",
targets: webApiTargets,
kind: "token",
source: "code-and-example",
requiredInProduction: true,
},
{
name: "JWT_SECRET",
description: "JWT signing secret for legacy API auth endpoints.",
classification: "required-per-app",
targets: webApiTargets,
kind: "secret",
source: "code-and-example",
requiredInProduction: true,
},
{
name: "API_KEY_LEGACY_PLAINTEXT_FALLBACK",
description: "Temporary cutover switch for legacy plaintext API-key lookup after hash metadata backfill.",
classification: "production-only",
targets: ["web", "api", "mcp"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes:
"Secure default is false. Set true only for an explicitly approved, short migration window while validating pre-backfill API keys, then disable it again.",
},
{
name: "API_KEY_HASH_SECRET",
description: "Optional HMAC secret used to hash legacy API keys during lookup and migration.",
classification: "production-only",
targets: ["web", "api", "mcp"],
kind: "secret",
source: "code-and-example",
notes: "When unset, legacy lookup falls back to the built-in v1 key namespace; set this during the API-key hash backfill and keep it stable afterward.",
},
{
name: "LAGO_API_URL",
description: "Base URL for the self-hosted Lago API used by HiveGrid billing sync.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
notes: "Staging uses the Lago API service reachable from the deployment network or SSH tunnel. Do not include /api/v1; the Lago gateway appends it.",
},
{
name: "LAGO_API_KEY",
description: "Bearer token for the Lago API.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "LAGO_WEBHOOK_SECRET",
description: "Shared secret used to validate Lago webhook delivery once BILL-05 enables inbound sync.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "LAGO_TIMEOUT_MS",
description: "HTTP timeout for Lago API calls.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
defaultValue: "10000",
},
{
name: "MOLLIE_API_KEY",
description: "Mollie API key used for payment checkout and webhook verification.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
notes: "Use a Mollie testmode key in staging. Webhooks and admin manual sync are verified by refetching the payment through Mollie with this key.",
},
{
name: "MOLLIE_PROFILE_ID",
description: "Optional Mollie website profile id used when creating payments.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "MOLLIE_TIMEOUT_MS",
description: "HTTP timeout for Mollie API calls.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
defaultValue: "10000",
},
{
name: "BILLING_MOLLIE_WEBHOOK_URL",
description: "Canonical public Mollie webhook URL used by the general worker for recurring invoice payments.",
classification: "optional-provider",
targets: ["worker"],
kind: "url",
source: "code-and-example",
notes:
"Required when billing provider side effects are enabled. Must be HTTPS and end exactly in /v1/billing/mollie/webhooks; use the environment-specific API host.",
},
{
name: "NODE_ENV",
description: "Runtime mode supplied by Node, React Router or deployment platform.",
classification: "production-only",
targets: allTargets,
kind: "node-env",
source: "runtime",
},
{
name: "APP_REVISION",
description: "Immutable deploy revision injected by image build or runtime platform.",
classification: "production-only",
targets: allTargets,
kind: "string",
source: "runtime",
defaultValue: "unknown",
},
{
name: "WEB_BUILD_DIRECTORY",
description: "Optional server-runtime override for the React Router web build directory.",
classification: "production-only",
targets: ["web"],
kind: "string",
source: "code",
notes: "Used by server/server.ts for smoke tests and non-standard runtime layouts; normal Docker images use apps/web/build.",
},
{
name: "API_PORT",
description: "HTTP listen port for the API runtime.",
classification: "production-only",
targets: ["api"],
kind: "string",
source: "runtime",
defaultValue: "3001",
},
{
name: "MCP_HOST",
description: "HTTP listen host for the standalone MCP runtime.",
classification: "production-only",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
defaultValue: "0.0.0.0",
},
{
name: "MCP_PORT",
description: "HTTP listen port for the standalone MCP runtime.",
classification: "production-only",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
defaultValue: "8080",
},
{
name: "MCP_ALLOWED_HOSTS",
description: "Comma-separated host allowlist for Streamable HTTP DNS rebinding protection.",
classification: "required-per-app",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "mcp.hivegrid.de,staging-mcp.hivegrid.de,localhost,127.0.0.1,::1",
},
{
name: "MCP_ALLOWED_ORIGINS",
description: "Comma-separated Origin allowlist for Streamable HTTP DNS rebinding protection.",
classification: "required-per-app",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "https://mcp.hivegrid.de,https://staging-mcp.hivegrid.de,http://localhost,http://127.0.0.1",
},
{
name: "MCP_RESOURCE_URL",
description: "Public OAuth protected-resource origin for the standalone MCP runtime.",
classification: "required-per-app",
targets: ["web", "mcp"],
kind: "url",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "https://mcp.hivegrid.de",
notes: "Use https://staging-mcp.hivegrid.de in staging. MCP is host-root only; do not append /mcp.",
},
{
name: "MCP_AUTHORIZATION_SERVER_URL",
description: "Public OAuth authorization-server origin for MCP client onboarding.",
classification: "required-per-app",
targets: ["web", "mcp"],
kind: "url",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "https://app.hivegrid.de",
notes: "Use https://staging-app.hivegrid.de in staging.",
},
{
name: "MCP_OAUTH_TOKEN_HASH_SECRET",
description: "Optional HMAC secret for hash-only MCP OAuth authorization codes and bearer tokens.",
classification: "production-only",
targets: ["web", "mcp"],
kind: "secret",
source: "code-and-example",
notes: "When unset, MCP OAuth reuses API_KEY_HASH_SECRET so web and mcp can validate the same token hashes.",
},
{
name: "WEB_ORIGIN",
description: "Optional explicit web application origin allowed by API CORS and used as a worker workflow bridge fallback.",
classification: "optional-provider",
targets: ["api", "worker"],
kind: "url",
source: "code",
notes: "Workers use this only when WORKFLOW_TRIGGER_EXECUTOR_URL and APP_URL are unset.",
},
{
name: "ADMIN_ORIGIN",
description: "Optional explicit admin application origin allowed by API CORS.",
classification: "optional-provider",
targets: ["api"],
kind: "url",
source: "code",
},
{
name: "PORT",
description: "HTTP listen port for the web runtime.",
classification: "local-development-only",
targets: ["web"],
kind: "string",
source: "runtime",
defaultValue: "3000",
},
{
name: "HOST",
description: "HTTP listen host for the web runtime.",
classification: "local-development-only",
targets: ["web"],
kind: "string",
source: "runtime",
defaultValue: "0.0.0.0",
},
{
name: "DIRECT_URL",
description: "Unpooled Postgres URL used by Prisma Migrate when DATABASE_URL flows through PgBouncer.",
classification: "production-only",
targets: allTargets,
kind: "database-url",
source: "code-and-example",
notes:
"Read by prisma.config.ts datasource. Required whenever DATABASE_URL points at PgBouncer (transaction pool mode breaks Migrate's prepared statements). Falls back to DATABASE_URL when unset.",
},
{
name: "SERVER_URL",
description: "Potential canonical server URL.",
classification: "production-only",
targets: webApiTargets,
kind: "url",
source: "code",
notes: "Currently commented out in url.server.ts.",
},
{
name: "VERCEL_URL",
description: "Vercel-provided deployment host.",
classification: "production-only",
targets: ["web"],
kind: "string",
source: "code",
notes: "Currently commented out in i18n/url helpers.",
},
{
name: "WEBHOOKS_URL",
description: "Public base URL override used for webhook callbacks, commonly ngrok in development.",
classification: "optional-provider",
targets: webApiTargets,
kind: "url",
source: "code-and-example",
},
{
name: "AIRCALL_CLIENT_ID",
description: "Aircall Technology Partner OAuth client identifier.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "AIRCALL_CLIENT_SECRET",
description: "Aircall Technology Partner OAuth client secret.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "AIRCALL_REDIRECT_URI",
description: "Exact public Aircall OAuth callback URI registered for the current environment.",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
},
{
name: "AIRCALL_WEBHOOK_URL",
description: "Public Aircall webhook URL registered after a tenant authorizes the integration.",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes: "Must point to the API webhook route and use HTTPS outside local contract tests.",
},
{
name: "HALLOPETRA_WEBHOOK_URL",
description: "Public HiveGrid endpoint entered manually for HalloPetra post-call webhooks.",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes: "Must be the canonical API route and use HTTPS outside local contract tests.",
},
{
name: "KWP_OAUTH_CLIENT_ID",
description: "KWP Keycloak OAuth client identifier for the web connector.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "The callback URI is derived from routing.protocol and routing.webAppHost; no redirect env key is used.",
},
{
name: "KWP_OAUTH_CLIENT_SECRET",
description: "KWP Keycloak OAuth client secret for the web connector.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "KWP_OAUTH_SCOPES",
description: "Space-delimited OAuth scopes assigned to the KWP connector client.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "KWP_CUSTOMER_CODE",
description: "KWP customer code used for tenant relay discovery and authorization.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "KWP_OIDC_ISSUER",
description: "KWP Keycloak OIDC issuer URL used by the web connector.",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
},
{
name: "KWP_HIVEGRID_TENANT_ID",
description: "Exact tenant id allowed to use the environment-bound KWP pilot client.",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "string",
source: "code-and-example",
notes: "Required by the KWP runtime flow and checked in addition to the kwp_integration entitlement.",
},
{
name: "KWP_MANDANT",
description: "Deprecated process-wide bnWin mandant setting; ignored by new KWP connections.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Leave unset. The setup flow stores an explicit selected or none binding inside each encrypted connection.",
},
{
name: "STORAGE_PROVIDER",
description: "Primary storage provider for runtime uploads.",
classification: "optional-provider",
targets: webApiMcpWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Use s3 in production. Local is intended for explicit development or staging fallback only.",
},
{
name: "STORAGE_FALLBACK_PROVIDER",
description: "Optional fallback storage provider when the primary provider is unavailable.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "STORAGE_ENDPOINT",
description: "S3-compatible storage API endpoint for signed upload and download operations.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
},
{
name: "STORAGE_REGION",
description: "S3-compatible storage region used for request signing.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "STORAGE_BUCKET",
description: "Default S3-compatible bucket for generated upload and download URLs.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "STORAGE_ACCESS_KEY_ID",
description: "S3-compatible access key identifier for storage request signing.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "STORAGE_SECRET_ACCESS_KEY",
description: "S3-compatible secret access key for storage request signing.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "GDPR_EXPORT_SSE_C_KEY_BASE64",
description: "Base64-encoded 32-byte SSE-C key for portal and privacy GDPR export artifacts.",
classification: "production-only",
targets: ["web", "worker"],
kind: "secret",
source: "code-and-example",
requiredInProductionTargets: ["web"],
notes:
"Required on both web runtime surfaces and conditionally on the dedicated GDPR export worker. Keep it server-only; rotation must wait until all 72-hour export artifacts have expired.",
},
{
name: "STORAGE_SESSION_TOKEN",
description: "Optional temporary session token for S3-compatible storage credentials.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "WEB_STORAGE_ACCESS_KEY_ID",
description: "Host-side Compose access-key mapping for the core web storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the web container receives this value as STORAGE_ACCESS_KEY_ID.",
},
{
name: "WEB_STORAGE_SECRET_ACCESS_KEY",
description: "Host-side Compose secret-key mapping for the core web storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the web container receives this value as STORAGE_SECRET_ACCESS_KEY.",
},
{
name: "WEB_STORAGE_SESSION_TOKEN",
description: "Optional host-side Compose session-token mapping for the core web storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the web container receives this value as STORAGE_SESSION_TOKEN.",
},
{
name: "WORKER_GENERAL_STORAGE_ACCESS_KEY_ID",
description: "Host-side Compose access-key mapping for the general worker storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the general worker receives this value as STORAGE_ACCESS_KEY_ID.",
},
{
name: "WORKER_GENERAL_STORAGE_SECRET_ACCESS_KEY",
description: "Host-side Compose secret-key mapping for the general worker storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the general worker receives this value as STORAGE_SECRET_ACCESS_KEY.",
},
{
name: "WORKER_GENERAL_STORAGE_SESSION_TOKEN",
description: "Optional host-side Compose session-token mapping for the general worker storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the general worker receives this value as STORAGE_SESSION_TOKEN.",
},
{
name: "WORKER_IMPORT_STORAGE_ACCESS_KEY_ID",
description: "Host-side Compose access-key mapping for the import worker storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the import worker receives this value as STORAGE_ACCESS_KEY_ID.",
},
{
name: "WORKER_IMPORT_STORAGE_SECRET_ACCESS_KEY",
description: "Host-side Compose secret-key mapping for the import worker storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the import worker receives this value as STORAGE_SECRET_ACCESS_KEY.",
},
{
name: "WORKER_IMPORT_STORAGE_SESSION_TOKEN",
description: "Optional host-side Compose session-token mapping for the import worker storage principal.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "example",
notes: "Compose-only indirection; the import worker receives this value as STORAGE_SESSION_TOKEN.",
},
{
name: "STORAGE_PUBLIC_BASE_URL",
description: "Optional public CDN/base URL for storage object URLs.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
},
{
name: "STORAGE_FORCE_PATH_STYLE",
description: "Optional flag for S3-compatible providers that require path-style bucket addressing.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "STORAGE_LOCAL_ROOT",
description: "Filesystem root for explicit local storage fallback.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "STORAGE_LOCAL_PUBLIC_BASE_URL",
description: "Optional public base URL for local storage objects.",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
},
{
name: "CLAMD_HOST",
description: "Mesh-only ClamAV daemon host used for synchronous and queued INSTREAM malware scans.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Required for untrusted uploads in production. Scanner failures reject uploads fail-closed.",
},
{
name: "CLAMD_PORT",
description: "ClamAV daemon TCP port used by INSTREAM scanning.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
defaultValue: "3310",
},
{
name: "CLAMD_TIMEOUT_MS",
description: "Maximum time allowed for a ClamAV reachability check and malware scan.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
defaultValue: "30000",
},
{
name: "SCAN_QUEUE_ENABLED",
description: "Enables the worker-backed asynchronous scan queue for stored private files.",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Direct public asset uploads still require a synchronous clean ClamAV verdict.",
},
{
name: "MAILJET_WEBHOOK_SECRET",
description: "Shared secret for Basic-Auth authentication of inbound Mailjet event webhook attempts.",
classification: "optional-provider",
targets: ["api"],
kind: "secret",
source: "code-and-example",
notes:
"Inbound webhook secret only (used as the HTTP Basic-Auth password). Mailjet does not sign event webhooks, so the callback URL is configured as https://mailjet:SECRET@host/...; keep separate from the outbound MAILJET_API_KEY/MAILJET_SECRET_KEY pair.",
},
{
name: "MAILJET_API_KEY",
description: "Mailjet public API key for transactional email delivery (Basic-Auth username).",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "MAILJET_SECRET_KEY",
description: "Mailjet private/secret API key for transactional email delivery (Basic-Auth password).",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "MAILJET_FROM_EMAIL",
description: "Default sender email from a verified Mailjet sender domain.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "email",
source: "code-and-example",
},
{
name: "MAILJET_FROM_NAME",
description: "Optional default sender display name for Mailjet messages.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "example",
},
{
name: "SUPPORT_EMAIL",
description: "Support/contact email address.",
classification: "optional-provider",
targets: ["web"],
kind: "email",
source: "example",
},
{
name: "COMPANY_NAME",
description: "Company name for outbound email/footer metadata.",
classification: "optional-provider",
targets: ["web", "api"],
kind: "string",
source: "example",
},
{
name: "COMPANY_ADDRESS",
description: "Company address for outbound email/footer metadata.",
classification: "optional-provider",
targets: ["web", "api"],
kind: "string",
source: "example",
},
{
name: "INTEGRATIONS_CONTACT_FORMSPREE",
description: "Formspree endpoint for contact forms.",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
},
{
name: "CRISP_CHAT_WEBSITE_ID",
description: "Crisp website ID for chat widget integrations exposed through root app configuration.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Read by apps/web/app/utils/data/.server/rootData.ts and still listed in legacy Fly examples.",
},
{
name: "ANALYTICS_TOKEN",
description: "Token required by the public analytics ingestion endpoint.",
classification: "required-per-app",
targets: ["api"],
kind: "token",
source: "code",
notes: "The endpoint rejects missing or default token values.",
},
{
name: "AUTH_MAGIC_LINK_ENABLED",
description: "Feature flag for Magic-Link authentication capability metadata.",
classification: "optional-provider",
targets: ["web", "api"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
},
{
name: "AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES",
description: "Magic-Link token validity duration in minutes when the provider is enabled.",
classification: "optional-provider",
targets: ["web", "api"],
kind: "string",
source: "code-and-example",
},
{
name: "CAPTCHA_PROVIDER",
description: "Self-hosted captcha provider. Defaults to mcaptcha; set to cap to use Cap Standalone.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "mcaptcha",
},
{
name: "CAP_INSTANCE_URL",
description: "Base URL of the self-hosted Cap Standalone instance (e.g. https://captcha.hivegrid.de).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET",
description: "Fallback Cap site secret for server-side siteverify when per-surface secrets are not set.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET_LOGIN",
description: "Cap site secret for the login surface.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET_FORMS",
description: "Cap site secret for public form submissions.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET_BOOKING",
description: "Cap site secret for public booking pages.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITEKEY_LOGIN",
description: "Cap public sitekey for the login surface.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "CAP_SITEKEY_FORMS",
description: "Cap public sitekey for public form submissions.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "CAP_SITEKEY_BOOKING",
description: "Cap public sitekey for public booking pages.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "MCAPTCHA_INSTANCE_URL",
description: "Base URL of the self-hosted mCaptcha instance (e.g. https://captcha.tool-ctrl.de).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "MCAPTCHA_ACCOUNT_SECRET",
description: "mCaptcha dashboard account secret for server-side PoW siteverify.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "MCAPTCHA_SITEKEY_LOGIN",
description: "mCaptcha public sitekey for the login surface.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "MCAPTCHA_SITEKEY_FORMS",
description: "mCaptcha public sitekey for public form submissions.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "MCAPTCHA_SITEKEY_BOOKING",
description: "mCaptcha public sitekey for public booking pages.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "CAPTCHA_FAIL_OPEN",
description: "Local development/test escape hatch for captcha-provider outages. Deployed runtimes always fail closed.",
classification: "local-development-only",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Ignored unless NODE_ENV is development or test.",
},
{
name: "NOTIFICATIONS_NOVU_API_KEY",
description: "Novu API key for optional admin notification-provider diagnostics.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "WEB_PUSH_VAPID_SUBJECT",
description: "Public HTTPS or mailto contact identifier embedded in worker-generated VAPID assertions.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
notes: "Required together with both VAPID keys when the Web Push provider is wired; diagnostics may expose only the key name and validation state.",
},
{
name: "WEB_PUSH_VAPID_PUBLIC_KEY",
description: "URL-safe Base64 VAPID public key used by the worker provider and browser PushSubscription bootstrap.",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "string",
source: "code-and-example",
requiredInProductionTargets: ["web"],
notes: "Generate once as a pair with WEB_PUSH_VAPID_PRIVATE_KEY and keep the pair stable across deployments.",
},
{
name: "WEB_PUSH_VAPID_PRIVATE_KEY",
description: "URL-safe Base64 VAPID private key used to sign worker Web Push requests.",
classification: "optional-provider",
targets: ["worker"],
kind: "secret",
source: "code-and-example",
notes: "Never log or expose this value; rotate only with an explicit PushSubscription migration plan.",
},
{
name: "WORKER_ENABLED",
description: "Opt-in flag that allows the standalone worker runtime to start queue processors.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Worker runtime exits without starting queues unless this is exactly true.",
},
{
name: "WORKER_CONCURRENCY",
description: "Per-process BullMQ worker concurrency for queue processors.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "1",
notes: "Defaults to serial processing; must be a positive safe integer when provided.",
},
{
name: "WORKER_TENANT_SWEEP_CONCURRENCY",
description: "Bounded concurrency for active-tenant maintenance sweeps.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "4",
notes: "Clamped by the worker runtime to protect Postgres and provider rate limits.",
},
{
name: "WORKER_QUEUE_GROUP",
description: "Worker queue group: one of general | mail | import | webhook | plugin. Required when WORKER_ENABLED=true.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
notes: "Selects which BullMQ queues the process subscribes to. Each docker-compose / K8s replica sets exactly one group. See docs/ops/worker-queues.md.",
},
{
name: "WORKER_CONCURRENCY_GENERAL",
description: "Per-process concurrency for the general worker group (notifications, maintenance, file scan).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "10",
},
{
name: "WORKER_CONCURRENCY_MAIL",
description: "Per-process concurrency for the mail worker group (transactional email + webhook delivery).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "5",
},
{
name: "WORKER_CONCURRENCY_IMPORT",
description: "Per-process concurrency for the import worker group (imports + exports — CPU/memory bound).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "1",
},
{
name: "WORKER_CONCURRENCY_WEBHOOK",
description: "Per-process concurrency for the webhook worker group (AI chat, browser automation — I/O bound).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "20",
},
{
name: "WORKER_CONCURRENCY_PLUGIN",
description: "Per-process concurrency for the plugin worker group (WASM plugin invocations — sandboxed third-party code).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "5",
},
{
name: "WORKER_HEALTH_PORT",
description: "TCP port for the worker liveness/readiness HTTP server.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "9100",
notes: "Defaults to 9100 single-process; the five-service worker topology uses 9101-9105.",
},
{
name: "WORKER_HEALTH_HOST",
description: "Bind host for the worker health server. Defaults to 0.0.0.0 inside containers.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
},
{
name: "WORKER_REDIS_POOL_SIZE",
description: "Advisory ioredis connection pool size per worker process.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
notes: "Defaults differ per group: general/mail=4, import=2, webhook=8, plugin=4.",
},
{
name: "EMAIL_QUEUE_NAME",
description: "Optional BullMQ queue name override for transactional email jobs.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code",
defaultValue: "hivegrid.email",
notes: "Leave unset unless the worker and enqueue side are intentionally deployed with a non-default queue name.",
},
{
name: "WORKFLOW_QUEUE_NAME",
description: "Optional BullMQ queue name override for workflow jobs.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code",
defaultValue: "hivegrid.workflows",
notes: "Leave unset unless the worker and enqueue side are intentionally deployed with a non-default queue name.",
},
{
name: "WORKFLOW_TRIGGER_EXECUTOR_MODE",
description: "Selects the general worker's outbox.workflow execution adapter.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "http",
notes:
"Use http for the signed web-runtime bridge. hybrid canaries the worker-native safe-core MVP (event/manual/if/switch/doNothing/log/alertUser/variable/httpRequest/iterator, tenant-scoped rowGet/email, and single-boundary waitForInput continuation resumes) and falls back to the HTTP bridge for unsupported graph semantics. native is opt-in for safe-core-only deployments and fails loud for unsupported blocks or arbitrary conditional edges outside if/switch/iterator.",
},
{
name: "WORKFLOW_TRIGGER_EXECUTOR_URL",
description: "Optional web-runtime base URL override used by the general worker's outbox.workflow execution bridge.",
classification: "optional-provider",
targets: ["worker"],
kind: "url",
source: "code",
notes: "Falls back to APP_URL or WEB_ORIGIN. Set this when workers reach the web runtime through an internal service URL.",
},
{
name: "WORKFLOW_TRIGGER_EXECUTOR_TIMEOUT_MS",
description: "HTTP timeout for the general worker's outbox.workflow execution bridge.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "30000",
},
{
name: "WORKFLOW_TRIGGER_OUTBOX_ENABLED",
description: "Escape hatch for the general worker's outbox.workflow subscriber.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "true",
notes: "Set to false only for controlled maintenance. Events remain in outbox.workflow while disabled.",
},
{
name: "WORKFLOW_TRIGGER_OUTBOX_CONCURRENCY",
description: "BullMQ concurrency for the general worker's outbox.workflow subscriber.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "5",
},
{
name: "WORKFLOW_TRIGGER_OUTBOX_REQUIRED",
description: "Fail the general worker startup when the outbox.workflow subscriber cannot be bootstrapped.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to true in staging/production general workers once the workflow trigger bridge URL/token and Redis are provisioned.",
},
{
name: "EXPORT_RETENTION_QUEUE_ENABLED",
description: "Opt-in flag that allows API export-retention enqueueing and worker maintenance-queue processing.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to exactly true only when the maintenance worker is deployed with Redis and retention dependencies configured.",
},
{
name: "IMPORT_QUEUE_ENABLED",
description: "Opt-in flag for queued import submit processing.",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Keep false on worker-import placeholders until import, export, and scan services are wired and IMPORT_QUEUE_RUNTIME_READY=true.",
},
{
name: "IMPORT_QUEUE_RUNTIME_READY",
description: "Secondary opt-in proving import queue processors and scan/import services are wired before web submit enqueues import jobs.",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to exactly true only with IMPORT_QUEUE_ENABLED=true after the worker runtime can process hivegrid.imports/hivegrid.exports end to end.",
},
{
name: "PORTAL_GDPR_EXPORT_QUEUE_ENABLED",
description: "Internal opt-in for the import worker to consume only hivegrid.exports for portal and privacy GDPR artifacts.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes:
"Set to exactly true only on WORKER_QUEUE_GROUP=import while IMPORT_QUEUE_ENABLED and IMPORT_QUEUE_RUNTIME_READY are unset or false; requires complete STORAGE_* configuration.",
},
{
name: "OUTBOX_DISPATCHER_ENABLED",
description: "Master switch for the outbox dispatcher worker (transactional outbox pattern).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to exactly true on staging and production once Redis + Postgres are reachable. See docs/architecture/outbox-pattern.md.",
},
{
name: "OUTBOX_DISPATCHER_REQUIRED",
description: "Fail the general worker startup when the outbox dispatcher is disabled or cannot be bootstrapped.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to true on staging/production worker-general once Redis + Postgres are provisioned so outbox producers cannot silently pile up.",
},
{
name: "PLUGIN_HOOK_FANOUT_REQUIRED",
description: "Fail the general worker startup when plugin hook fanout cannot be bootstrapped.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes:
"Optional staging/canary fail-closed switch for outbox.plugin-hook. Production plugin runtime with PLUGIN_RUNTIME_PRODUCTION_ENABLED=true and Redis configured already treats hook fanout as required.",
},
{
name: "OUTBOX_DISPATCH_BATCH_SIZE",
description: "Maximum number of outbox events the dispatcher claims per polling tick.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "100",
notes: "Tune up when steady-state throughput exceeds 100 events/sec; clamped to the [1, 1000] range by the helper.",
},
{
name: "OUTBOX_DISPATCH_CONCURRENCY",
description: "Maximum number of claimed outbox events the dispatcher enqueues and updates concurrently per tick.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "10",
notes: "Keep at or below database and Redis connection capacity; runtime clamps the value to the [1, 100] range.",
},
{
name: "OUTBOX_DISPATCH_INTERVAL_MS",
description: "Outbox dispatcher polling interval in milliseconds.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "1000",
notes: "Lower values reduce delivery latency but increase Postgres query load. 1s is a good default.",
},
{
name: "OUTBOX_MAX_RETRIES",
description: "Maximum retries before an outbox event transitions to FAILED (dead-letter).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "6",
notes: "Each retry adds exponential backoff (1, 2, 4, 8, 16, 32 minutes). Raise only when receivers tolerate longer delays.",
},
{
name: "OUTBOX_DONE_RETENTION_HOURS",
description: "Retention window for successfully dispatched outbox rows before the maintenance worker purges them.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "720",
notes: "Applied by the daily worker-general outbox-done-retention scheduler. FAILED rows are not purged by this job.",
},
{
name: "OUTBOX_DONE_RETENTION_BATCH_SIZE",
description: "Maximum DONE outbox rows deleted per retention maintenance run.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "1000",
notes: "The DB helper clamps the batch to 1..10000 so large first runs drain gradually.",
},
{
name: "BULLMQ_REDIS_URL",
description: "Redis connection URL for BullMQ-backed web/API enqueue and worker processing.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
notes: "Required when queue-backed features are enabled. Queue package falls back to REDIS_URL when this is not set.",
},
{
name: "REDIS_URL",
description: "Redis connection URL for MCP rate limits/readiness and fallback for queue-backed web/API/worker processing.",
classification: "optional-provider",
targets: webApiMcpWorkerTargets,
kind: "url",
source: "code",
requiredInProductionTargets: ["web", "mcp"],
notes: "Required by web GDPR export download gates and MCP in production; used as a fallback when BULLMQ_REDIS_URL is absent for queue code.",
},
{
name: "CACHE_INVALIDATION_ENABLED",
description: "Global kill-switch for cross-replica cache pub/sub invalidation (boolean string: true|false).",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
defaultValue: "true",
notes:
"When false, two-tier caches stop publishing and subscribers are not started — replicas fall back to L1 TTL (CACHE_L1_TTL_SECONDS) as the only consistency mechanism. Use for emergency disable without redeploy. See docs/architecture/two-tier-cache.md.",
},
{
name: "CACHE_L1_TTL_SECONDS",
description: "Override the default 5-minute L1 (in-process) TTL for two-tier caches (subscription, tenant, entitlements).",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
defaultValue: "300",
notes:
"Acts as the safety-net when a pub/sub invalidation is missed (Redis disconnect, subscriber crash). Lower values mean fewer stale reads but more DB load.",
},
{
name: "IDEMPOTENCY_BACKEND",
description: "Storage backend for API idempotency-key reservations (string: prisma|shared-store).",
classification: "optional-provider",
targets: ["api"],
kind: "string",
source: "code-and-example",
defaultValue: "prisma",
notes:
"Default 'prisma' keeps idempotency state in Postgres (already multi-replica-safe). Set 'shared-store' to back it with the SharedStore (Redis) instead — keeps the primary DB cooler, relies on Redis TTL for eviction. See apps/api/src/idempotency/shared-store-client.ts.",
},
{
name: "BROWSER_RUNTIME_URL",
description: "Optional browser automation runtime endpoint for worker-backed browser sessions.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "url",
source: "code-and-example",
},
{
name: "BROWSER_RUNTIME_API_KEY",
description: "Optional browser automation runtime API key owned by the platform/worker runtime.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "BROWSER_SESSION_TIMEOUT_MS",
description: "Optional browser automation session timeout policy in milliseconds.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "HIVEGRID_API_MAINTENANCE_MODE",
description: "API maintenance-mode switch; set to 1 to return a maintenance response from non-health API routes.",
classification: "production-only",
targets: ["api"],
kind: "string",
source: "code",
defaultValue: "0",
},
{
name: "HIVEGRID_API_MAINTENANCE_RETRY_AFTER_SECONDS",
description: "Optional Retry-After value for API maintenance responses.",
classification: "production-only",
targets: ["api"],
kind: "string",
source: "code",
},
{
name: "IPSTACK_API_KEY",
description: "IPStack API key for IP enrichment.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "secret",
source: "code",
},
{
name: "IPAPIIS_API_KEY",
description: "ipapi.is API key for IP enrichment.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "secret",
source: "code",
},
{
name: "IP_HASH_PEPPER",
description: "Secret pepper for HMAC-SHA256 pseudonymisation of stored client IPs (AD-22). Server-side secret; keep out of the database.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code",
},
{
name: "GEOIP_DB_PATH",
description:
"Filesystem path to the local DB-IP Lite Country MMDB for country-only GeoIP lookups (AD-22). Defaults to ./data/geoip/dbip-country-lite.mmdb.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code",
},
{
name: "DEMO_USER",
description: "Local demo login hint in email:password format.",
classification: "local-development-only",
targets: ["web"],
kind: "string",
source: "code",
},
{
name: "SEED_ADMIN_EMAIL",
description: "Production bootstrap admin email used by the guarded database seed.",
classification: "production-only",
targets: ["web"],
kind: "email",
source: "code-and-example",
notes: "Production seeds refuse the local default admin email.",
},
{
name: "SEED_ADMIN_PASSWORD",
description: "Production bootstrap admin password used by the guarded database seed.",
classification: "production-only",
targets: ["web"],
kind: "secret",
source: "code-and-example",
notes: "Production seeds refuse the local default password.",
},
{
name: "SEED_DEMO_DATA",
description: "Explicit opt-in for demo tenants and demo users during local or guarded staging seed runs.",
classification: "local-development-only",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "May be enabled in staging only together with ALLOW_STAGING_DEMO_SEED=true; never enable on production resources.",
},
{
name: "ALLOW_STAGING_DEMO_SEED",
description: "Guard that permits CRM SaaS demo seeding on the disposable staging environment.",
classification: "production-only",
targets: ["web"],
kind: "string",
source: "code",
defaultValue: "false",
notes: "Seeding only. The demo LOGIN gate is STAGING_DEMO_LOGIN_ENABLED — a SEED_*-shaped key cannot live on a runtime resource.",
},
{
name: "STAGING_DEMO_LOGIN_ENABLED",
description: "Runtime gate that lets the seeded staging demo accounts sign in. Independent of any seeding flag.",
classification: "production-only",
targets: ["web"],
kind: "string",
source: "code",
defaultValue: "false",
notes:
"Only takes effect together with SENTRY_ENVIRONMENT=staging, so it cannot unlock a demo account in production. Deliberately not SEED_*-prefixed: the RLS deploy contract rejects those keys on runtime resources.",
},
{
name: "SEED_DEMO_PRO_MANAGED",
description: "Marks demo-pro-crm as owned by the comprehensive staging seed so the legacy boot demo seed leaves that tenant untouched.",
classification: "production-only",
targets: ["web"],
kind: "string",
source: "code",
defaultValue: "false",
notes: "Set only on the staging web resource; never enable on production resources. Starter and Business boot demo tenants remain unchanged.",
},
{
name: "SEED_DEMO_USER_PASSWORD",
description: "One-off password applied to the synthetic demo-pro-crm users by the comprehensive staging seed.",
classification: "production-only",
targets: ["shared"],
kind: "secret",
source: "code",
notes: "Operator-supplied staging-only secret. The deploy workflow must never create or overwrite it; never set it on production or expose it in logs.",
},
{
name: "SITE_KEY_*",
description: "Dynamic per-site API key, for example SITE_KEY_EXAMPLE_SITE.",
classification: "optional-provider",
targets: ["api"],
kind: "token",
source: "dynamic",
dynamicPrefix: "SITE_KEY_",
},
{
name: "BRAND_PRODUCT_NAME",
description: "Override for the product name used in mail templates, error pages and UI metadata.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "When unset the brand layer falls back to defaultBrandTokens.productName.",
},
{
name: "BRAND_SITE_URL",
description: "Override for the canonical public site URL used in mail templates and brand links.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
},
{
name: "BRAND_SUPPORT_EMAIL",
description: "Override for the support contact email surfaced in mail templates and footers.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "email",
source: "code-and-example",
},
{
name: "BRAND_SUPPORT_FROM_NAME",
description: "Override for the display name used in outbound support email and footers.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "BRAND_LEGAL_IMPRINT_URL",
description: "Override for the imprint/legal notice URL surfaced in mail templates.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
},
{
name: "BRAND_LEGAL_PRIVACY_URL",
description: "Override for the privacy policy URL surfaced in mail templates.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
},
{
name: "BRAND_LEGAL_TERMS_URL",
description: "Override for the terms-of-service URL surfaced in mail templates.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
},
{
name: "BRAND_LOGO_URL",
description: "Override for the logo asset URL used in mail templates and login screens.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "BRAND_FAVICON_URL",
description: "Override for the favicon asset URL.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "BRAND_MAIL_PRIMARY",
description: "Override for the primary brand color used in transactional mail buttons.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "BRAND_MAIL_PRIMARY_TEXT",
description: "Override for the text color rendered on primary brand surfaces in mail.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "BRAND_MAIL_BACKGROUND",
description: "Override for the mail body background color.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "BRAND_MAIL_LINK",
description: "Override for the mail link color.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "SENTRY_DSN",
description: "Optional Sentry DSN that opts the runtime into the Sentry error-reporter adapter.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
notes: "When unset the runtime keeps the safe no-op error reporter. @sentry/node is loaded via dynamic import.",
},
{
name: "SENTRY_ENVIRONMENT",
description: "Optional Sentry environment tag forwarded to the Sentry adapter when SENTRY_DSN is set.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Falls back to NODE_ENV when omitted.",
},
{
name: "SENTRY_DSN_API",
description: "Optional Sentry DSN dedicated to the API process (hivegrid-api project).",
classification: "optional-provider",
targets: ["api"],
kind: "secret",
source: "code-and-example",
notes: "When unset the API keeps the safe no-op reporter. Independent from SENTRY_DSN_WORKER and SENTRY_DSN_WEB.",
},
{
name: "SENTRY_DSN_WORKER",
description: "Optional Sentry DSN dedicated to the BullMQ worker process (hivegrid-worker project).",
classification: "optional-provider",
targets: ["worker"],
kind: "secret",
source: "code-and-example",
notes: "When unset the worker keeps the safe no-op reporter. Independent from SENTRY_DSN_API and SENTRY_DSN_WEB.",
},
{
name: "SENTRY_RELEASE",
description: "Optional Sentry release tag (typically $GIT_SHA in CI) used to correlate errors to deploys.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Defaults to undefined; production deployments should inject the build SHA.",
},
{
name: "SENTRY_TRACES_SAMPLE_RATE",
description: "Optional Sentry tracing sample rate (0.0 - 1.0). API/Worker default to 0.1 in production, 1.0 in dev.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Clamped to [0, 1]; non-numeric input falls back to the runtime default.",
},
{
name: "SENTRY_PROFILES_SAMPLE_RATE",
description: "Optional Sentry profiling sample rate (0.0 - 1.0). Defaults to 0.0 (off) until @sentry/profiling-node is wired.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Clamped to [0, 1]; non-numeric input falls back to 0.",
},
{
name: "SENTRY_URL",
description: "Optional self-hosted Sentry base URL used by @sentry/cli and the @sentry/vite-plugin for source-map uploads.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
notes: "Required only on CI for the release / source-map upload step. Defaults to sentry.io when omitted.",
},
{
name: "AUTH_PASSWORD_MIN_LENGTH",
description: "Minimum password length enforced by the auth password-policy validator. Defaults to 12 (OWASP 2024).",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
},
{
name: "AUTH_PASSWORD_REQUIRE_UPPER",
description: "Whether the password validator requires at least one uppercase character. Defaults to true.",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
},
{
name: "AUTH_PASSWORD_REQUIRE_LOWER",
description: "Whether the password validator requires at least one lowercase character. Defaults to true.",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
},
{
name: "AUTH_PASSWORD_REQUIRE_DIGIT",
description: "Whether the password validator requires at least one numeric character. Defaults to true.",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
},
{
name: "AUTH_PASSWORD_REQUIRE_SPECIAL",
description: "Whether the password validator requires at least one special character. Defaults to false.",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
},
{
name: "AUTH_PASSWORD_HIBP_CHECK",
description: "Toggle HaveIBeenPwned breach checks during password validation. Defaults to true.",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
},
{
name: "AUTH_PASSWORD_HIBP_MAX_OCCURRENCES",
description: "Maximum allowed HIBP occurrence count before password is rejected. Defaults to 0.",
classification: "optional-provider",
targets: webApiTargets,
kind: "string",
source: "code-and-example",
},
{
name: "OTEL_EXPORTER_OTLP_ENDPOINT",
description: "Optional OpenTelemetry OTLP HTTP endpoint that opts the runtime into the tracing skeleton.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
notes: "When unset the tracing skeleton stays disabled. @opentelemetry/sdk-node is loaded via dynamic import.",
},
{
name: "OTEL_SERVICE_NAME",
description: "Optional OpenTelemetry service.name override used when initializing the tracing NodeSDK.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Defaults to the runtime-specific component name (api, worker, web) when omitted.",
},
{
name: "OTEL_EXPORTER_OTLP_HEADERS",
description: "Optional comma-separated key=value pairs forwarded as HTTP headers on every OTLP export request.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "string",
source: "code-and-example",
notes:
"Used to attach OTLP auth tokens (e.g. `x-sentry-auth=Sentry sentry_key=<key>`). Values are sent in cleartext; supply only via deploy-secret stores.",
},
{
name: "OTEL_TRACES_SAMPLER",
description: "Optional OpenTelemetry sampler name override (e.g. `parentbased_traceidratio`, `always_on`).",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "string",
source: "code-and-example",
notes:
"The runtime always wraps the configured sampler in ParentBasedSampler(TraceIdRatioBasedSampler(arg)); this var is exposed only for diagnostic override.",
},
{
name: "OTEL_TRACES_SAMPLER_ARG",
description: "OpenTelemetry trace sampler ratio (0.0 - 1.0). API defaults to 0.1, worker to 0.2.",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Clamped to [0, 1]; non-numeric input falls back to the runtime default. Set to 1.0 on staging when debugging cross-service traces.",
},
{
name: "OTEL_LOG_LEVEL",
description: "OpenTelemetry diag-logger verbosity (e.g. `debug`, `info`, `warn`, `error`).",
classification: "optional-provider",
targets: apiWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Used only by the bootstrap to toggle DiagConsoleLogger at DEBUG level when OTLP exports are silently dropped; leave unset for normal operation.",
},
{
name: "VITE_OTEL_EXPORTER_OTLP_ENDPOINT",
description: "Browser-side OpenTelemetry OTLP HTTP endpoint baked into the Vite bundle at build time.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes:
"When unset, apps/web/app/otel.client.ts is a no-op. Companion to OTEL_EXPORTER_OTLP_ENDPOINT (server-side). The endpoint must be CORS-reachable from the browser and rate-limited at the gateway.",
},
{
name: "VITE_OTEL_SERVICE_NAME",
description: "Optional browser-side OpenTelemetry service.name override baked into the Vite bundle at build time.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Defaults to hivegrid-web when omitted.",
},
{
name: "SENTRY_DSN_WEB",
description: "Optional Sentry DSN for the SSR side of apps/web. Separate project from SENTRY_DSN (api/worker).",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
notes: "When unset, apps/web/app/sentry.server.ts is a no-op. Companion to VITE_SENTRY_DSN_WEB (client-side).",
},
{
name: "SENTRY_AUTH_TOKEN",
description: "Sentry CLI auth token used by the Vite plugin to upload source maps. CI-only.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
notes: "When unset, the Vite plugin is skipped and source maps are not uploaded.",
},
{
name: "SENTRY_ORG",
description: "Sentry organisation slug used by the source-map upload plugin.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Required only when SENTRY_AUTH_TOKEN is set.",
},
{
name: "SENTRY_PROJECT",
description: "Sentry project slug for the web app (default: hivegrid-web).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Used by the Vite source-map upload plugin. Companion to SENTRY_AUTH_TOKEN / SENTRY_ORG.",
},
{
name: "SENTRY_RELEASE",
description: "Release identifier (typically the git SHA) associated with uploaded source maps and SDK events.",
classification: "optional-provider",
targets: ["web", "api", "worker"],
kind: "string",
source: "code-and-example",
notes: "When unset the SDK auto-detects via CI heuristics. Set explicitly in Coolify for reproducible releases.",
},
{
name: "VITE_SENTRY_DSN_WEB",
description: "Client-side Sentry DSN baked into the browser bundle at Vite build time.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Public by design (browser bundle). Secure the project via Sentry domain-allowlist in the project settings.",
},
{
name: "VITE_SENTRY_RELEASE",
description: "Build-time release identifier exposed to the browser bundle for correlating events to uploaded source maps.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Mirror SENTRY_RELEASE at build time so client + server events share the same release ID.",
},
{
name: "VITE_SENTRY_TRACES_SAMPLE_RATE",
description: "Browser-side performance traces sample rate (0.0-1.0). Defaults to 0.1.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Stored as a string because Vite injects env vars literally; parsed back to a number at runtime.",
},
{
name: "VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE",
description: "Sample rate (0.0-1.0) for proactively recording Replay sessions. Defaults to 0.1 (10% of sessions).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Replay is the most expensive Sentry feature. Keep low in production; set to 1.0 on staging for QA.",
},
{
name: "VITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE",
description: "Sample rate (0.0-1.0) for Replay sessions that are retroactively kept when an error fires. Defaults to 1.0.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Standard Sentry recommendation is 1.0 — every error gets a replay.",
},
{
name: "METRICS_ENABLED",
description: "Master switch for the Prometheus /metrics and /status endpoints across api, worker and web. Default false in dev.",
classification: "optional-provider",
targets: ["web", "api", "worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to 'true' (literal) on staging and production. When false the endpoints return 404 and the in-process registry stays passive.",
},
{
name: "METRICS_TOKEN",
description:
"Bearer token for /metrics endpoints. Must be the same string across api, worker and web in a single deployment so one Prometheus job can scrape all three.",
classification: "optional-provider",
targets: ["web", "api", "worker"],
kind: "secret",
source: "code-and-example",
notes: "Generate with `openssl rand -hex 32`. Rotate every 6 months. Required whenever METRICS_ENABLED=true.",
},
{
name: "WORKER_ADMIN_PORT",
description: "TCP port for the worker admin HTTP server hosting /status and /metrics. Default 9100.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "9100",
notes: "Only opened when METRICS_ENABLED=true. Expose internally to Prometheus only — never via the public proxy.",
},
{
name: "WORKER_ADMIN_HOST",
description: "Bind host for the worker admin server. Default 0.0.0.0 inside containers.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
notes: "Override only when running outside Docker on a multi-NIC host.",
},
{
name: "APP_REGION",
description: "Deployment-region tag surfaced in /status responses. Falls back to FLY_REGION when unset.",
classification: "optional-provider",
targets: ["web", "api", "worker"],
kind: "string",
source: "code-and-example",
notes: "Used by Grafana cluster filters. Free-form short slug (eu-central-1, hetzner-fsn1, …).",
},
{
name: "BACKUP_S3_ENDPOINT",
description: "S3-compatible endpoint for the backup bucket (MinIO/R2/Wasabi). Empty falls back to AWS default.",
classification: "optional-provider",
targets: ["shared"],
kind: "url",
source: "code-and-example",
notes: "Consumed by @hivegrid/cli only.",
},
{
name: "BACKUP_S3_REGION",
description: "S3 region for the backup bucket.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
},
{
name: "BACKUP_S3_BUCKET",
description: "Destination bucket for @hivegrid/cli backup archives.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
notes: "Keep this bucket isolated from STORAGE_BUCKET so a single IAM credential leak does not pivot to backups.",
},
{
name: "BACKUP_S3_ACCESS_KEY_ID",
description: "S3 access key id used by @hivegrid/cli (separate from the app STORAGE_* credentials).",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "code-and-example",
},
{
name: "BACKUP_S3_SECRET_ACCESS_KEY",
description: "S3 secret access key used by @hivegrid/cli.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "code-and-example",
},
{
name: "BACKUP_S3_SESSION_TOKEN",
description: "Optional temporary session token for backup S3 credentials.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "code-and-example",
},
{
name: "BACKUP_S3_FORCE_PATH_STYLE",
description: "Set to 'true' when the backup endpoint requires path-style addressing (MinIO, some R2 setups).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
},
{
name: "BACKUP_ENCRYPTION",
description: "Encryption method for backup archives: age (default), gpg, or none. age REQUIRES BACKUP_AGE_PUBLIC_KEY.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
notes: "Operator-only — backups carry tenant data, never disable encryption in production.",
},
{
name: "BACKUP_AGE_PUBLIC_KEY",
description: "age public key (recipient) used to encrypt backup archives.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
notes: "Generate via `age-keygen`; the matching identity (private key) must be stored offline, not in env.",
},
{
name: "BACKUP_AGE_IDENTITY_FILE",
description: "Path to the age identity file used by backup:restore / backup:verify.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
notes: "Only mount this in restore environments; the file is the master decryption secret.",
},
{
name: "BACKUP_GPG_RECIPIENT",
description: "GPG key id used when BACKUP_ENCRYPTION=gpg.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
},
{
name: "BACKUP_RETENTION_DAILY",
description: "Number of daily backups @hivegrid/cli backup:rotate keeps (default 7).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
},
{
name: "BACKUP_RETENTION_WEEKLY",
description: "Number of weekly backups (Sunday UTC) kept by backup:rotate (default 4).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
},
{
name: "BACKUP_RETENTION_MONTHLY",
description: "Number of monthly backups (1st UTC) kept by backup:rotate (default 12).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
},
{
name: "BACKUP_INCLUDE_CLICKHOUSE",
description: "Set to 'true' to include a ClickHouse BACKUP statement in backup:create.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
},
{
name: "ASSET_CDN_URL",
description: "CDN origin that fronts /assets, /fonts, /images. Empty = serve directly from origin (default).",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes:
"Must be present at Vite build time — the asset base is baked into the bundle. See docs/ops/asset-cdn.md and docs/improvement-plan/03-scaling-infrastructure/asset-cdn.md.",
},
{
name: "BUNNY_PULL_ZONE_ID",
description: "Numeric Bunny.net pull-zone id consumed by scripts/cdn/bunny-purge.ts after deploys.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
notes: "CI-only. Paired with BUNNY_API_KEY; the post-deploy purge step skips when either is unset.",
},
{
name: "BUNNY_API_KEY",
description: "Bunny.net account-level API key used to purge the CDN pull zone after each deploy.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
source: "code-and-example",
notes: "CI-only. Rotate quarterly. When unset, scripts/cdn/bunny-purge.ts exits 0 silently.",
},
{
name: "MEILI_URL",
description: "Meilisearch endpoint used by search hot paths and the search-indexer worker.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
notes:
"When unset the app keeps SQL fallback search semantics. Production should use an internal-only Meilisearch URL. Required on worker-general when tenant hard-delete runs in production, required-RLS, or staging/production Sentry mode.",
},
{
name: "MEILI_API_KEY",
description: "SaaS-scoped Meilisearch API key the app authenticates with against the central Meilisearch (not the server master key).",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
notes:
"Never expose to browsers. Scoped to the SaaS index prefix (e.g. hivegrid-*), minted from the master key per infra STANDARDS §4. Local docker-compose may use the documented dev key. Required on worker-general when tenant hard-delete runs in production, required-RLS, or staging/production Sentry mode.",
},
{
name: "MEILI_ENV",
description: "Environment mode for the standalone Meilisearch service.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "example",
defaultValue: "development",
notes: "Set to production on the Meilisearch container. App runtimes do not read this directly.",
},
{
name: "SEARCH_BACKEND",
description: "Search hot-path override.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "meilisearch",
notes: "Set to sql as an emergency fallback to bypass Meilisearch reads while keeping writes harmless.",
},
{
name: "PLUGIN_OUTPUT_SANITIZATION_STRICTNESS",
description: "Controls plugin output redaction before worker persistence/logging.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "moderate",
notes: "Supported values are strict, moderate and off. Keep moderate or strict in production.",
},
{
name: "PLUGIN_RUNTIME_PRODUCTION_ENABLED",
description: "Production rollout gate for tenant plugin runtime operations.",
classification: "production-only",
targets: ["web", "worker"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes:
"Set to true only after the external plugin runtime security sign-off is complete; production plugin lifecycle and worker paths fail closed otherwise.",
},
{
name: "PLUGIN_TRUSTED_PUBLIC_KEYS",
description: "CSV of trusted Ed25519 public keys used to verify plugin WASM signatures.",
classification: "optional-provider",
targets: ["worker"],
kind: "secret",
source: "code-and-example",
notes: "Empty fails plugin signature verification closed. Rotate by updating worker env and restarting plugin workers.",
},
{
name: "PLUGIN_MAX_FUEL",
description: "Sandbox fuel budget for one plugin invocation.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "1000000",
},
{
name: "PLUGIN_MAX_MEMORY_MB",
description: "Sandbox memory cap in MiB for one plugin invocation.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "64",
},
{
name: "PLUGIN_MAX_WALL_CLOCK_MS",
description: "Wall-clock timeout for one plugin invocation; the worker-thread sandbox is terminated after this budget.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "5000",
},
{
name: "PLUGIN_RATE_LIMIT_PER_MINUTE",
description: "Per-tenant/plugin invocation rate limit.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "100",
},
{
name: "PLUGIN_RATE_LIMIT_WINDOW_SECONDS",
description: "Sliding-window size for plugin invocation rate limits.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "60",
},
{
name: "PLUGIN_AUDIT_RETENTION_DAYS",
description: "Days to retain PluginCapabilityUse audit rows.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "90",
},
{
name: "PLUGIN_AUDIT_RETENTION_BATCH_SIZE",
description: "Rows deleted per PluginCapabilityUse audit-retention batch.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "1000",
},
{
name: "PLUGIN_AUDIT_RETENTION_MAX_BATCHES",
description: "Maximum PluginCapabilityUse audit-retention delete batches per run.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "100",
},
{
name: "PLUGIN_AUDIT_RETENTION_CRON",
description: "Cron pattern for the plugin capability audit-retention scheduler.",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "0 3 * * *",
},
{
name: "PLUGIN_HOST_VERSION_OVERRIDE",
description: "Optional host-version override for plugin compatibility checks.",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "string",
source: "example",
notes: "Intended for staging/tests only; default host version comes from package metadata.",
},
{
name: "PLUGIN_INSTALL_SKIP_BINARY_VERIFY",
description: "Development escape hatch for plugin binary signature verification.",
classification: "local-development-only",
targets: ["web"],
kind: "string",
source: "example",
defaultValue: "false",
notes: "Must not be true in production.",
},
{
name: "PLUGIN_REQUIRE_CAPABILITY_CONSENT",
description: "Requires tenant capability grants before a plugin can be enabled.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "example",
defaultValue: "true",
notes: "Kept for backwards-compatible dev/test environments while consent UI is rolled out.",
},
{
name: "PLUGIN_INSTALL_RATE_LIMIT_PER_MIN",
description: "Per-tenant plugin install rate limit over a 60-second sliding window.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "5",
},
{
name: "PLUGIN_SETTINGS_WRITE_RATE_LIMIT_PER_MIN",
description: "Per-user plugin settings write rate limit over a 60-second sliding window.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "60",
},
{
name: "PLUGIN_SETTINGS_FRAME_VIOLATION_RATE_LIMIT_PER_MIN",
description: "Per-user plugin settings iframe violation report rate limit over a 60-second sliding window.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "120",
},
{
name: "PLATFORM_LEADS_INGRESS_ENABLED",
description: "Fail-closed runtime switch for POST /v1/platform/leads.",
classification: "production-only",
targets: ["api"],
kind: "string",
source: "code-and-example",
defaultValue: "true",
notes:
"Set to false, 0, or off to return a neutral 404 before source authentication or writes. This is an ingress safety switch for external lead capture; the authenticated admin Sales workspace remains available by permission.",
},
{
name: "MARKETING_ALLOWED_ORIGINS",
description: "Deprecated CORS allowlist for the retired /api/leads/capture 410 response.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes:
"R-LEADS retired browser capture and removed marketing.js. This value no longer authorizes a write; it only lets known old origins read the structured 410 drain response. Remove it after the documented drain window.",
},
{
name: "MARKETING_RATE_LIMIT_PER_MIN",
description: "Deprecated, ignored rate-limit key from the retired browser lead-capture endpoint.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes:
"No active runtime reads this key. Keep only while cleaning existing environment inventories; native /v1/platform/leads uses source and pre-auth ingress limits.",
},
{
name: "LEAD_CONVERSION_SECRET",
description: "HMAC-SHA256 key signing signed-lead-tokens for the self-service conversion flow (Phase 05 #79).",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
notes:
"Min 32 bytes of entropy (`openssl rand -hex 32`). Tokens carry leadId + planId + 7-day TTL and are validated by the /register loader to pre-fill the form. Rotating the secret invalidates outstanding tokens after at most 7 days. When unset, signing throws and verifying returns null — the conversion deep-link flow is fail-closed.",
},
{
name: "LEAD_CONVERSION_ENABLED",
description: "Toggle for the Phase 05 #79 lead-conversion flow (default 'true').",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes:
"Set to 'false' to disable both the signed-token /register pre-fill flow and the admin 'Convert to Tenant' button without rolling the DB migration back. Used as the rollback knob in incident response.",
},
{
name: "MARKETING_WEBHOOKS_ENABLED",
description: "Toggle for the apps/worker `outbox.marketing` handler (Phase 05 #79).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
notes:
"Set to 'false' to halt outbound webhook dispatch (Slack, Discord, Mailchimp, HubSpot, Brevo, custom). Outbox rows accumulate while disabled and resume on re-enable — raise the outbox retention TTL if you plan a multi-day pause.",
},
{
name: "ADMIN_EMAIL_EVENT_WEBHOOK_SECRET",
description:
"HMAC secret for normalized Admin Sales delivery and bounce events.",
classification: "optional-provider",
targets: ["api"],
kind: "secret",
source: "code-and-example",
notes:
"Min 32 bytes. Provider adapters sign timestamp plus exact body; rotation invalidates in-flight deliveries.",
},
{
name: "ADMIN_EMAIL_BCC_CAPABILITY_SECRET",
description:
"HMAC secret for signed, rotatable Admin Sales BCC recipient capabilities.",
classification: "optional-provider",
targets: ["api", "web"],
kind: "secret",
source: "code-and-example",
notes:
"Min 32 bytes. This is independent from Mailjet webhook authentication; rotating it invalidates generated BCC addresses after their database rows are archived.",
},
{
name: "ADMIN_EMAIL_BCC_INBOUND_DOMAIN",
description:
"Dedicated inbound domain receiving signed Admin Sales BCC copies.",
classification: "optional-provider",
targets: ["api", "web"],
kind: "string",
source: "code-and-example",
notes:
"Defaults to bcc.<APP_BASE_DOMAIN>. Configure the provider catch-all and MX only for this dedicated host.",
},
{
name: "MARKETING_TOKEN_SECRET",
description: "HMAC secret signing unsubscribe tokens for sequence emails (Phase 05 #80).",
classification: "optional-provider",
targets: ["web", "worker"],
kind: "secret",
source: "code-and-example",
notes:
"Min 32 bytes (`openssl rand -hex 32`). Falls back to LEAD_CONVERSION_SECRET when unset for operator convenience. Rotating invalidates every active unsubscribe link at once — use that as the kill-switch.",
},
{
name: "MARKETING_SEQUENCES_ENABLED",
description: "Killswitch for the email-sequence trigger + scheduler workers (Phase 05 #80).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
notes:
"Set to 'false' to halt both the outbox-triggered run-starter and the scheduled step-sender. Outbox events accumulate while disabled and replay on re-enable.",
},
{
name: "HOCUSPOCUS_AUTH_SECRET",
description: "Shared HS256 secret signing the 15-min JWTs issued by /api/collab/token (Phase 05 #59 — realtime-collab).",
classification: "optional-provider",
targets: ["web", "api"],
kind: "secret",
source: "code-and-example",
notes:
"Must match between the web app and the hocuspocus container. Min 32 bytes of entropy. When unset, the hocuspocus container refuses to boot and the web token endpoint returns 503 — single-user editor mode stays functional. See docs/features/realtime-collab.md.",
},
{
name: "CHAT_GATEWAY_AUTH_SECRET",
description: "Dedicated HS256 secret for short-lived Team Chat WebSocket identity tokens.",
classification: "optional-provider",
targets: ["web", "api"],
kind: "secret",
source: "code-and-example",
notes:
"Must match between web and API, contain at least 32 bytes of entropy, and must not be reused for Hocuspocus or another audience. Missing or weak configuration disables only the Team Chat realtime connection.",
},
{
name: "VITE_HOCUSPOCUS_URL",
description: "Browser-visible WebSocket URL for the Hocuspocus server (Phase 05 #59).",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes:
"Typically `wss://collab.<base-domain>`. When unset the Novel-Editor mounts without Y.js / Hocuspocus extensions and falls back to the existing REST save path — graceful single-user degradation. Exposing as VITE_-prefixed so the browser bundle can read it.",
},
{
name: "HOCUSPOCUS_URL",
description: "Server-internal Hocuspocus WebSocket endpoint, for any server-side health-probe / management code (Phase 05 #59).",
classification: "optional-provider",
targets: ["web", "api"],
kind: "url",
source: "code-and-example",
notes:
"Defaults to ws://hocuspocus:1234 when running in docker-compose. Distinct from VITE_HOCUSPOCUS_URL which is the browser-public endpoint behind TLS.",
},
{
name: "HOCUSPOCUS_PORT",
description: "TCP port the apps/hocuspocus service listens on (Phase 05 #59).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
defaultValue: "1234",
notes: "Container-internal port. Production reverse-proxy terminates TLS in front of this.",
},
{
name: "HOCUSPOCUS_HOST",
description: "Bind address for the apps/hocuspocus service (Phase 05 #59).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
defaultValue: "0.0.0.0",
notes: "Container-internal bind. Keep 0.0.0.0 inside docker, 127.0.0.1 for local-only experiments.",
},
{
name: "HOCUSPOCUS_MAX_PAYLOAD_BYTES",
description: "Maximum encoded Y.Doc state we will persist per CollabDoc row (Phase 05 #59).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
source: "code-and-example",
defaultValue: "10485760",
notes:
"Defaults to 10 MiB. Acts as a guard against runaway Y.js state-bloat — the snapshot/compaction strategy (deferred follow-up) reduces real-world state size below this limit.",
},
// ------------------------------------------------------------------
// Admin-Panel SSO via Authentik (Phase 09 #82 — admin-oidc-login.md).
// Optional-provider: when unset the admin login page hides the SSO
// CTA and falls back to email/password (gated by ADMIN_FALLBACK_LOGIN_*).
// ------------------------------------------------------------------
{
name: "AUTHENTIK_ISSUER_URL",
description: "OIDC issuer URL published by the Authentik `hivegrid-admin-panel` provider (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes:
"Typically https://auth.<base-domain>/application/o/hivegrid-admin-panel/. Must match the `iss` claim in Authentik ID-tokens; openid-client uses it for Issuer.discover().",
},
{
name: "AUTHENTIK_ADMIN_CLIENT_ID",
description: "OIDC client_id registered with the Authentik admin-panel provider (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Matches the blueprint client_id (defaults to `hivegrid-admin-panel`).",
},
{
name: "AUTHENTIK_ADMIN_CLIENT_SECRET",
description: "OIDC client_secret for the Authentik admin-panel provider (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
notes: "Fetched from the Authentik admin UI after the blueprint applies. Rotate via Authentik then redeploy the web service.",
},
{
name: "AUTHENTIK_ADMIN_JIT_DATABASE_URL",
description: "PostgreSQL URL for the execute-only Authentik Admin JIT callback capability.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
notes:
"Must authenticate as hivegrid_authentik_jit. Configure it together with Admin SSO only after the role provisioner has installed the dedicated login.",
},
{
name: "AUTHENTIK_ADMIN_REDIRECT_URI",
description: "Exact OAuth callback URI registered with the Authentik admin-panel provider (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes: "Must be the public URL of /auth/admin/callback on the admin host, byte-for-byte equal to the Authentik provider configuration.",
},
{
name: "AUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI",
description: "URI Authentik redirects to after RP-initiated end_session (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes: "Typically https://admin.<base-domain>/login?logged_out=1 — must be allowlisted in Authentik's post_logout_redirect_uris.",
},
{
name: "ADMIN_FALLBACK_LOGIN_ENABLED",
description: "Toggles the email/password emergency login on the admin host (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes:
"When false (default) the admin login page hides the password form entirely. Flip to true only when Authentik is unreachable; pair with a tight ADMIN_FALLBACK_LOGIN_EMAILS allowlist.",
},
{
name: "ADMIN_FALLBACK_LOGIN_EMAILS",
description: "Comma-separated allowlist of admin emails that may use the fallback path when enabled (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Keep this short (1-2 bootstrap accounts max). Every fallback success/failure emits an admin.login.fallback.* audit event tagged severity=warn.",
},
] as const satisfies readonly EnvVariableDefinition[];
export type KnownEnvVariableName = (typeof envVariableDefinitions)[number]["name"];