HiveGrid-Wireframes/hivegrid-cloud/docs/configuration.md

Configuration

This project keeps runtime configuration explicit and treats secret diagnostics as a public surface. Application code should receive configuration through typed loaders, provider options, or handler dependencies instead of reading process.env inside package internals.

Explicit environment access

Only runtime entrypoints should read from process.env. Worker-owned environment reads are limited to the worker runtime and health entrypoints. Those entrypoints immediately validate values and convert them into explicit dependencies for queues, Mailjet, browser runtime integrations, and handlers.

Package adapters must accept an environment object or concrete provider options from their caller. This keeps hidden environment coupling out of packages such as packages/mail and packages/queue, makes tests deterministic, and lets diagnostics report configuration status without exposing raw secret values.

Worker enablement

The worker is opt-in. Set WORKER_ENABLED=true only on deployments that should start queue processors. In multi-resource platforms such as Coolify, do not put WORKER_ENABLED=false into a shared production environment group that is also injected into the worker resource; leave it unset for web/API resources and set it explicitly to true on each worker resource.

When the worker is enabled, provide queue configuration explicitly:

• WORKER_QUEUE_GROUP must be one of general, mail, import, webhook, or plugin for grouped worker resources.
• WORKER_HEALTH_PORT and WORKER_ADMIN_PORT should be unique per Coolify worker app when those endpoints are exposed.
• BULLMQ_REDIS_URL is the worker Redis URL.
• REDIS_URL is accepted only as a fallback when BULLMQ_REDIS_URL is absent.

If the worker is disabled, queue processors should not start. Health and runtime diagnostics may still report enablement and readiness status, but they must not include the Redis URL value.

Mailjet configuration

Mailjet is the transactional mail provider boundary for API and worker runtimes. Mail delivery requires the provider key and verified sender domain address to be configured together:

• MAILJET_API_KEY is the Mailjet API token.
• MAILJET_FROM_EMAIL is the default sender email from a verified Mailjet domain.
• MAILJET_FROM_NAME is an optional sender display name.

Treat MAILJET_API_KEY and MAILJET_FROM_EMAIL as a required pair whenever Mailjet delivery is enabled. Supplying only one of the pair is invalid configuration because the provider cannot safely send mail without both authentication and an approved sender address.

Browser runtime configuration

Worker browser runtime settings are explicit worker configuration, not package-global state:

• BROWSER_RUNTIME_URL identifies the browser runtime service endpoint when that integration is enabled.
• BROWSER_RUNTIME_API_KEY authenticates requests to the browser runtime service.
• BROWSER_SESSION_TIMEOUT_MS configures the session timeout and must parse as a valid millisecond duration.

Browser runtime diagnostics should report key names, parse status, and diagnostic codes only. They must never include endpoint secrets, API keys, tokens, or raw values.

Safe diagnostics and redaction

Configuration validation must use the central redacted secret validator for required and optional secret-like values. Errors, health JSON, and logs may include:

• environment key names;
• diagnostic codes;
• parse status;
• high-level messages;
• queue readiness or worker enablement status.

They must not include raw secret values. This applies to Redis URLs, database URLs, API keys, tokens, Mailjet sender secrets, browser runtime credentials, and any future provider secret.

When reporting invalid or missing configuration, prefer messages such as missing required env key MAILJET_API_KEY or invalid duration for BROWSER_SESSION_TIMEOUT_MS. Do not interpolate the rejected value into thrown errors, logs, or health responses.

Seed Credentials

Local demo users and demo tenants are opt-in through SEED_DEMO_DATA=true and are refused in production. Production bootstrap seeding requires SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD, creates only the configured admin plus roles, permissions, and entitlements, and refuses local default seed emails or the default password.

Adding new configuration

When adding a new runtime setting:

1. Decide which runtime entrypoint owns the environment read.
2. Validate and normalize the value before passing it to packages or handlers.
3. Use the redacted secret validator for secret-like required or optional values.
4. Pass normalized values through explicit options or dependencies.
5. Add tests that assert diagnostics expose keys and codes, not raw values.
6. Update this document and the environment inventory when the setting is user-facing.