115 lines
4.8 KiB
Markdown
115 lines
4.8 KiB
Markdown
# 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.
|