Trigger.dev is an open-source platform for building AI workflows and background jobs in TypeScript. It provides long-running tasks with retries, queues, observability, and elastic scaling.

Services

Core Services (Webapp Stack)

Service	Description
`webapp`	Main Trigger.dev application with dashboard and API
`trigger-postgres`	PostgreSQL database with logical replication
`trigger-redis`	Redis for cache and job queue
`trigger-clickhouse`	ClickHouse for analytics database
`trigger-minio`	S3-compatible object storage
`trigger-minio-init`	MinIO bucket initialization
`electric`	ElectricSQL for real-time sync
`trigger-registry`	Private Docker registry for deployed code
`trigger-registry-init`	Registry htpasswd initialization

Worker Services (Supervisor Stack)

Service	Description
`supervisor`	Worker orchestrator that executes tasks
`docker-socket-proxy`	Secure Docker socket proxy for supervisor

Prerequisites

Docker 20.10.0+
Docker Compose 2.20.0+
Minimum 6 vCPU and 12 GB RAM for the complete stack

Quick Start

Create a .env file with required secrets:
```
cp .env.example .env
```

Generate required secrets:

# Generate secrets
echo "SESSION_SECRET=$(openssl rand -hex 16)" >> .env
echo "MAGIC_LINK_SECRET=$(openssl rand -hex 16)" >> .env
echo "ENCRYPTION_KEY=$(openssl rand -hex 16)" >> .env
echo "POSTGRES_PASSWORD=$(openssl rand -hex 16)" >> .env

Start all services:
```
docker compose up -d
```
Wait for services to be healthy:
```
docker compose ps
```
Access the webapp at http://localhost:8030
Get the magic link from webapp logs for first login:
```
docker compose logs -f webapp
```

Environment Variables

Required Secrets

Variable	Description
`SESSION_SECRET`	Session encryption secret (run: `openssl rand -hex 16`)
`MAGIC_LINK_SECRET`	Magic link encryption secret (run: `openssl rand -hex 16`)
`ENCRYPTION_KEY`	Secret store encryption key (run: `openssl rand -hex 16`)
`POSTGRES_PASSWORD`	PostgreSQL password

Domain Configuration

Variable	Default	Description
`APP_ORIGIN`	`http://localhost:8030`	Public webapp URL
`LOGIN_ORIGIN`	`http://localhost:8030`	Login URL (usually same as APP_ORIGIN)
`API_ORIGIN`	`http://localhost:8030`	API URL

Image Versions

Variable	Default	Description
`TRIGGER_IMAGE_TAG`	`v4.2.0`	Trigger.dev webapp and supervisor version
`POSTGRES_VERSION`	`17.2-alpine3.21`	PostgreSQL version
`REDIS_VERSION`	`7.4.3-alpine3.21`	Redis version
`CLICKHOUSE_VERSION`	`25.3`	ClickHouse version
`MINIO_VERSION`	`RELEASE.2025-04-22T22-12-26Z`	MinIO version

Port Configuration

Variable	Default	Description
`TRIGGER_PORT`	`8030`	Webapp port
`MINIO_API_PORT`	`9000`	MinIO API port
`MINIO_CONSOLE_PORT`	`9001`	MinIO console port
`REGISTRY_PORT`	`5000`	Docker registry port

Authentication

Variable	Description
`WHITELISTED_EMAILS`	Regex pattern to restrict login (e.g., `^user@example\.com$`)
`AUTH_GITHUB_CLIENT_ID`	GitHub OAuth client ID
`AUTH_GITHUB_CLIENT_SECRET`	GitHub OAuth client secret

Email Configuration

Variable	Default	Description
`EMAIL_TRANSPORT`	—	Transport type: `resend`, `smtp`, or `aws-ses`
`FROM_EMAIL`	—	From email address
`RESEND_API_KEY`	—	Resend API key (if using Resend)
`SMTP_HOST`	—	SMTP server host
`SMTP_PORT`	`587`	SMTP server port

Volumes

Volume	Description
`trigger_shared`	Shared volume for worker token
`trigger_postgres_data`	PostgreSQL data
`trigger_redis_data`	Redis data
`trigger_clickhouse_data`	ClickHouse data
`trigger_clickhouse_logs`	ClickHouse logs
`trigger_minio_data`	MinIO object storage
`trigger_registry_data`	Docker registry data
`trigger_registry_auth`	Registry htpasswd authentication

Worker Token

On first startup, the webapp generates a worker token and saves it to the shared volume. If you need to run workers on separate machines:

Check webapp logs for the token:

docker compose logs webapp | grep -A15 "Worker Token"

Set the token in the remote worker's .env:
```
TRIGGER_WORKER_TOKEN=tr_wgt_xxxxx
```

Registry Setup

The built-in registry uses htpasswd authentication. The htpasswd file is automatically generated on first startup using the credentials from environment variables.

Default credentials:

Username: registry-user (set via REGISTRY_USER)
Password: very-secure-indeed (set via REGISTRY_PASSWORD)

To use custom credentials, set them in your .env file before first run:

REGISTRY_USER=my-user
REGISTRY_PASSWORD=my-secure-password

Before deploying tasks, login to the registry:

docker login -u registry-user localhost:5000

CLI Usage

To initialize a project with self-hosted Trigger.dev:

npx trigger.dev@latest login -a http://localhost:8030
npx trigger.dev@latest init -p <project-ref> -a http://localhost:8030

To deploy tasks:

npx trigger.dev@latest deploy --self-hosted

GitHub OAuth Setup

Create a GitHub OAuth App at https://github.com/settings/developers
Set callback URL: http://localhost:8030/auth/github/callback

Configure environment variables:

AUTH_GITHUB_CLIENT_ID=your_client_id
AUTH_GITHUB_CLIENT_SECRET=your_client_secret

Production Considerations

Use strong, unique passwords for all secrets
Set up proper TLS/SSL with a reverse proxy
Configure email transport for magic links
Use external managed databases for high availability
Set appropriate resource limits based on your workload
Enable WHITELISTED_EMAILS to restrict access
Consider disabling telemetry: TRIGGER_TELEMETRY_DISABLED=1

Scaling Workers

To add more worker capacity:

Set up additional supervisor instances on different machines
Configure each with the same TRIGGER_WORKER_TOKEN
Use unique TRIGGER_WORKER_INSTANCE_NAME for each

Troubleshooting

Magic links not arriving

Check webapp logs: docker compose logs -f webapp
Magic links are logged if no email transport is configured
Set up email transport for production use

Deployment fails at push step

Ensure you're logged into the registry: docker login localhost:5000
Check registry is healthy: docker compose ps trigger-registry

Services not starting

Ensure all required secrets are set in .env
Check logs: docker compose logs -f

README.md

Trigger.dev