Environment Variables and Configuration

Relevant source files

This document describes how Trigger.dev manages environment variables and configuration across the web application, workers, and deployment pipeline. It covers the centralized configuration system, validation approach, and the various categories of settings that control system behavior.

For information about local development setup, see Local Development. For deployment process details, see Deployment Process.

Configuration Architecture Overview

Trigger.dev uses a centralized, type-safe configuration system built on Zod schemas. All environment variables are validated at startup and exposed through a single env export rather than accessing process.env directly.

Architecture: Configuration System

Sources: apps/webapp/app/env.server.ts1-700 apps/webapp/app/utils/boolEnv.ts

Environment Variable Declaration and Validation

Zod Schema Definition

All environment variables are declared in a single Zod schema called EnvironmentSchema. This provides:

Type safety: TypeScript types are automatically inferred from the schema
Runtime validation: Invalid values cause startup failures with clear error messages
Default values: Sensible defaults reduce configuration burden
Transformations: Values can be parsed, coerced, and transformed

Sources: apps/webapp/app/env.server.ts28-700

Custom Validators

The system includes custom validation functions for complex requirements:

Validator	Purpose	Example Usage
`isValidDatabaseUrl`	Validates PostgreSQL connection strings	`DATABASE_URL`, `DIRECT_URL`
`isValidRegex`	Validates regex patterns for email filtering	`WHITELISTED_EMAILS`, `ADMIN_EMAILS`
`BoolEnv`	Parses boolean environment variables	`LOGIN_RATE_LIMITS_ENABLED`

Sources: apps/webapp/app/env.server.ts3-4 apps/webapp/app/utils/boolEnv.ts

Discriminated Unions

Complex features use discriminated unions to ensure related variables are set together:

This ensures all GitHub app credentials are provided when the feature is enabled, or none are required when disabled.

Sources: apps/webapp/app/env.server.ts6-26

Core Configuration Categories

Database Configuration

PostgreSQL connection settings with support for read replicas and connection pooling:

Variable	Type	Default	Description
`DATABASE_URL`	string	required	Primary database connection (pooled)
`DIRECT_URL`	string	required	Direct connection for migrations
`DATABASE_READ_REPLICA_URL`	string	optional	Read replica for query offloading
`DATABASE_CONNECTION_LIMIT`	number	10	Maximum connections per pool
`DATABASE_POOL_TIMEOUT`	number	60	Pool acquisition timeout (seconds)
`DATABASE_CONNECTION_TIMEOUT`	number	20	Connection timeout (seconds)

Database Configuration Pattern:

Sources: apps/webapp/app/env.server.ts31-46 apps/webapp/app/db.server.ts

Redis Configuration

The system uses multiple Redis instances for different purposes, each with independent configuration:

Redis Instance Architecture:

Each Redis instance supports:

Primary host/port configuration
Optional read replica (reader host/port)
Username/password authentication
TLS enable/disable
Cluster mode enable/disable

Configuration Pattern with Fallbacks:

This pattern allows specialized Redis instances to fall back to the base Redis configuration if not explicitly set.

Sources: apps/webapp/app/env.server.ts95-237 apps/webapp/app/env.server.ts575-643

Authentication and Security

Variable	Purpose
`SESSION_SECRET`	Signs session cookies
`MAGIC_LINK_SECRET`	Signs magic link tokens for passwordless auth
`ENCRYPTION_KEY`	Must be exactly 32 bytes, used for sensitive data encryption
`AUTH_GITHUB_CLIENT_ID`	GitHub OAuth app credentials
`AUTH_GITHUB_CLIENT_SECRET`	GitHub OAuth app credentials

Sources: apps/webapp/app/env.server.ts47-75

Email and Notifications

The system supports multiple email transports:

Transport	Required Variables
`resend`	`RESEND_API_KEY`
`smtp`	`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`
`aws-ses`	AWS credentials

Alerts use separate configuration (ALERT_EMAIL_TRANSPORT, ALERT_FROM_EMAIL, etc.) allowing different providers for system emails vs. user alerts.

Sources: apps/webapp/app/env.server.ts76-84 apps/webapp/app/env.server.ts398-442

Deployment Configuration

Deployment Registry Settings:

Variable	Description
`DEPLOY_REGISTRY_HOST`	Container registry hostname (required)
`DEPLOY_REGISTRY_USERNAME`	Registry authentication (optional)
`DEPLOY_REGISTRY_PASSWORD`	Registry authentication (optional)
`DEPLOY_REGISTRY_NAMESPACE`	Registry namespace (default: "trigger")
`DEPLOY_REGISTRY_ECR_TAGS`	CSV of key=value tags for ECR
`DEPLOY_REGISTRY_ECR_ASSUME_ROLE_ARN`	Cross-account ECR access

The system supports separate v3 and v4 registry configuration, with v4 falling back to v3 values:

Build Settings:

Variable	Default	Description
`DEPOT_TOKEN`	-	Depot.ai API token for remote builds
`DEPOT_ORG_ID`	-	Depot organization ID
`DEPOT_REGION`	"us-east-1"	Depot build region
`DEPLOY_IMAGE_PLATFORM`	"linux/amd64"	Target platform for images
`DEPLOY_TIMEOUT_MS`	480000	8 minutes - build timeout
`DEPLOY_QUEUE_TIMEOUT_MS`	900000	15 minutes - queue timeout

Sources: apps/webapp/app/env.server.ts264-319

Observability Configuration

OpenTelemetry Exporters:

Key OTEL Settings:

Category	Variables	Purpose
Dev OTEL	`DEV_OTEL_EXPORTER_OTLP_ENDPOINT`	Development worker telemetry endpoint
Batch Processing	`DEV_OTEL_BATCH_PROCESSING_ENABLED`	Enable batch span/log export
Span Limits	`TRIGGER_OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` (default: 1024)	Maximum attributes per span
Log Limits	`TRIGGER_OTEL_LOG_ATTRIBUTE_COUNT_LIMIT` (default: 1024)	Maximum attributes per log
Internal Tracing	`INTERNAL_OTEL_TRACE_SAMPLING_RATE` (default: "20")	1 in 20 traces sampled

Sources: apps/webapp/app/env.server.ts343-393

Run Engine 2.0 Configuration

The Run Engine has extensive tuning parameters:

Core Run Engine Settings:

Variable	Default	Description
`RUN_ENGINE_WORKER_COUNT`	4	Number of worker threads
`RUN_ENGINE_TASKS_PER_WORKER`	10	Concurrent tasks per worker
`RUN_ENGINE_WORKER_CONCURRENCY_LIMIT`	10	Max concurrent operations
`RUN_ENGINE_WORKER_POLL_INTERVAL`	100	Polling interval (ms)
`RUN_ENGINE_TIMEOUT_EXECUTING`	300000	5 minutes - execution timeout
`RUN_ENGINE_PARENT_QUEUE_LIMIT`	1000	Parent queue max size

Run Locking Configuration:

Variable	Default	Description
`RUN_ENGINE_RUN_LOCK_DURATION`	5000	Lock duration (ms)
`RUN_ENGINE_RUN_LOCK_MAX_RETRIES`	10	Maximum lock acquisition attempts
`RUN_ENGINE_RUN_LOCK_BASE_DELAY`	100	Initial retry delay (ms)
`RUN_ENGINE_RUN_LOCK_MAX_DELAY`	3000	Maximum retry delay (ms)
`RUN_ENGINE_RUN_LOCK_BACKOFF_MULTIPLIER`	1.8	Exponential backoff factor

Sources: apps/webapp/app/env.server.ts520-643

Build-time vs Runtime Configuration

Configuration Stages:

Build-time Variables

These are embedded in the Docker image during build:

Sources: docker/Dockerfile96-103

Turbo Global Environment

Turbo tracks specific environment variables to invalidate build caches when they change:

Sources: turbo.json124-146

Runtime Validation

At server startup, env.server.ts validates all environment variables:

Invalid configurations cause the application to fail with descriptive error messages before accepting any requests.

Sources: apps/webapp/app/env.server.ts28-700

Configuration Patterns

Fallback Pattern

Many configuration options fall back to base values:

This reduces duplication when using a single Redis instance for multiple purposes.

Sources: apps/webapp/app/env.server.ts136-166

Coercion and Transformation

Numeric and boolean values are coerced from strings:

Sources: apps/webapp/app/env.server.ts37 apps/webapp/app/env.server.ts62

Conditional Defaults

Some defaults depend on other environment variables:

Sources: apps/webapp/app/env.server.ts133

Custom validation logic ensures correctness:

Sources: apps/webapp/app/env.server.ts49-54

Best Practices

Never Access `process.env` Directly

All application code imports env from env.server.ts:

Sources: .cursor/rules/webapp.mdc14-22

Service/Configuration Separation

Testable services receive configuration as constructor parameters rather than importing env directly:

This pattern allows tests to instantiate services with mock configuration without importing env.server.ts.

Sources: .cursor/rules/webapp.mdc18-22

Secrets Management

Sensitive values should never be committed to version control:

Use .env files for local development (ignored by git)
Use Docker secrets for container deployments
Use environment variables in CI/CD pipelines

Sources: docker/Dockerfile72-73

Docker and Production Setup

Entrypoint Script

The Docker entrypoint validates the environment and runs migrations before starting the application:

Sources: docker/scripts/entrypoint.sh1-36

Multi-stage Build

The Dockerfile uses separate stages for dependencies, building, and running:

pruner: Extracts only necessary package files
dev-deps: Installs development dependencies
production-deps: Installs only production dependencies
builder: Builds the application
runner: Final runtime image with minimal footprint

Sources: docker/Dockerfile1-116

Memory Configuration

The entrypoint allows configuring Node.js heap size:

Sources: docker/scripts/entrypoint.sh44-50

Configuration Reference Table

Critical Security Variables

Variable	Required	Validation	Purpose
`SESSION_SECRET`	Yes	String	Session cookie signing
`MAGIC_LINK_SECRET`	Yes	String	Magic link token signing
`ENCRYPTION_KEY`	Yes	Exactly 32 bytes	Encrypt sensitive data
`PROVIDER_SECRET`	Yes	String (default: "provider-secret")	Provider authentication
`COORDINATOR_SECRET`	Yes	String (default: "coordinator-secret")	Coordinator authentication
`MANAGED_WORKER_SECRET`	Yes	String (default: "managed-secret")	Worker authentication

Feature Flags

Variable	Default	Description
`V2_MARQS_ENABLED`	"0"	Enable legacy MARQS queue system
`MARQS_WORKER_ENABLED`	"0"	Enable MARQS worker processing
`EVENT_LOOP_MONITOR_ENABLED`	"1"	Monitor event loop lag
`RESOURCE_MONITOR_ENABLED`	"0"	Monitor memory/CPU usage
`DISABLE_COMPRESSION`	-	Disable HTTP compression
`DISABLE_SSE`	-	Disable server-sent events

Sources: apps/webapp/app/env.server.ts264-665 apps/webapp/app/entry.server.tsx245-257