Environment Variables

Core Runtime

Variable	Required	Purpose
NODE_ENV	No	Runtime mode (development, test, production)
PORT	No	API server port
APP_BASE_URL	Required when DURABULL_AUTHLESS=false or MCP on public ingress	Canonical app URL for auth, email, and MCP OAuth resource {APP_BASE_URL}/mcp
VITE_PUBLIC_APP_URL	Recommended	Public URL exposed to browser clients

Auth and Identity

Variable	Required	Purpose
DURABULL_AUTHLESS	No	Enable/disable authless mode
BETTER_AUTH_SECRET	Required for OAuth and shipped self-host Compose	Session/OAuth signing secret (set even for authless lab Compose)
GOOGLE_OAUTH_CLIENT_ID	Optional	Google OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRET	Optional	Google OAuth secret
GITHUB_OAUTH_CLIENT_ID	Optional	GitHub OAuth client ID
GITHUB_OAUTH_CLIENT_SECRET	Optional	GitHub OAuth secret

Persistence and Data

Variable	Required	Purpose
DURABULL_POSTGRES_PORT	Optional	Host port mapped to Docker Postgres (55432 default)
DATABASE_URL	Optional	Enables PostgreSQL mode when set
REDIS_URL	Optional	Generic Redis URL used by scripts/defaults
DURABULL_REDIS_URL_ENCRYPTION_KEY	Required when persisting connections	32-byte key (hex/base64) used to encrypt Redis connection URLs at rest
DURABULL_SECRET_ENCRYPTION_KEY	Required for Linear alert integrations	32-byte key (hex/base64) used to encrypt third-party OAuth tokens at rest
DURABULL_PGLITE_DIR	Optional	Override PGlite data directory

Connection Mode

Variable	Required	Purpose
DURABULL_ENV_CONNECTIONS	No	Use env-driven connection set
DURABULL_REDIS_URL_DEFAULT	Recommended	Default env connection key
DURABULL_REDIS_URL_<NAME>	When env mode enabled	Redis URL for named connection
DURABULL_REDIS_URL_<NAME>_ENVIRONMENT	Optional	development, staging, or production
DURABULL_REDIS_URL_<NAME>_ALLOW_SELF_SIGNED_CERTS	Optional	Set to true for providers with self-signed TLS certs (for example Heroku Key-Value Store)

Optional Integrations

Variable	Required	Purpose
RESEND_API_KEY	Optional	Email delivery via Resend (invitations and alerts)
EMAIL_FROM	No	Sender address for Resend emails (default: Durabull <no-reply@durabull.io>)
LINEAR_OAUTH_CLIENT_ID	Required for Linear alert integrations	Linear OAuth application client ID
LINEAR_OAUTH_CLIENT_SECRET	Required for Linear alert integrations	Linear OAuth application client secret
LINEAR_OAUTH_REDIRECT_URI	Optional	Explicit Linear OAuth callback URL; defaults to ${APP_BASE_URL}/api/alerts/integrations/linear/callback
LINEAR_OAUTH_ACTOR	Optional	Linear OAuth actor mode: user by default, or app for service-account style app actor authorization
POSTHOG_KEY	Optional	PostHog project API key
POSTHOG_HOST	Optional	PostHog upstream host for the reverse proxy (defaults to https://us.i.posthog.com)

Note: The web app receives PostHog configuration from the API at /api/app/config. You only need to set the server-side POSTHOG_KEY and POSTHOG_HOST variables — no VITE_ prefix is required. Set POSTHOG_HOST to PostHog's ingestion domain (for example https://us.i.posthog.com), not your own app /ingest URL. The API reverse-proxies analytics traffic through /ingest to bypass ad blockers.

Linear OAuth callback

For Linear alert integrations, register this callback URL in your Linear OAuth application:

https://your-domain.example/api/alerts/integrations/linear/callback

Durabull derives that URL from APP_BASE_URL by default. Set LINEAR_OAUTH_REDIRECT_URI explicitly when your self-hosted API is served from a different public origin than the web app. The redirect URI configured in Linear must exactly match the value Durabull sends during OAuth. By default, Durabull uses Linear's user actor OAuth flow and omits the actor authorize parameter. Set LINEAR_OAUTH_ACTOR=app only when the Linear application is configured for app actor authorization and you want alert-created issues attributed to the app.

For the full connection, alert delivery, retry, and idempotency model, see Linear Integration.

Anonymous Usage Telemetry

Durabull collects anonymous/pseudonymous usage telemetry in production and self-hosted usage to understand feature adoption and improve the product. Configuring POSTHOG_KEY for your own PostHog project does not disable Durabull telemetry, and Durabull does not provide a product-level telemetry opt-out. When POSTHOG_KEY is set, the configured PostHog project receives the full PostHog browser analytics stream.

Telemetry includes feature and route usage, safe runtime context, success/failure booleans, enum values such as job status or theme, and aggregate count/duration buckets. Durabull does not collect Redis URLs, queue names, Redis key names, job data, logs, emails, names, organizations, hostnames, raw URLs, search patterns, stack traces, or raw error messages.

Self-hosted deployments do not need a separate collector service or telemetry hostname. The app forwards sanitized telemetry to Durabull's existing cloud API.

Optional Runtime Toggles

Variable	Required	Purpose
ASSET_PRELOAD_MAX_SIZE	No	Asset preload tuning
ASSET_PRELOAD_VERBOSE_LOGGING	No	Extra preload diagnostics

MCP

MCP is always enabled on the unified API deployment at {APP_BASE_URL}/mcp. No separate MCP port, service, or enable flag is required.

Variable	Required	Purpose
APP_BASE_URL	See Core Runtime	MCP host allowlist and OAuth resource URI ({APP_BASE_URL}/mcp)
DURABULL_AUTHLESS	No	Must remain false on internet-facing deployments
DISABLE_RATE_LIMIT	No	When true, disables all in-memory API + MCP rate limiting
MCP_TELEMETRY_LOG	No	Set false to disable stdout mcp_telemetry JSON logs (runtime-only; default: enabled)
MCP_AUTHLESS_BEARER_TOKEN	Authless + production	Strong bearer for isolated lab authless only — not for internet-facing production

See MCP Server for scopes, tools, and client setup. Operators: MCP operations runbook.

Recommended Production Baseline

NODE_ENV=production
APP_BASE_URL=https://your-domain.example
VITE_PUBLIC_APP_URL=https://your-domain.example
DURABULL_AUTHLESS=false
BETTER_AUTH_SECRET=<long-random-secret>
DURABULL_REDIS_URL_ENCRYPTION_KEY=<openssl-rand-hex-32>
DURABULL_SECRET_ENCRYPTION_KEY=<openssl-rand-hex-32>
DURABULL_ENV_CONNECTIONS=true
DURABULL_REDIS_URL_MAIN=redis://...
DURABULL_REDIS_URL_MAIN_ENVIRONMENT=production
DURABULL_REDIS_URL_DEFAULT=MAIN

Screenshot placeholder: .env sample file in docs-friendly format.