# 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.