compose-anything/src/trigger-dev/README.md

Trigger.dev

English | 中文

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

1. Create a .env file with required secrets:

   cp .env.example .env
   

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

3. Start all services:

   docker compose up -d
   

4. Wait for services to be healthy:

   docker compose ps
   

5. Access the webapp at http://localhost:8030

6. 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:

1. Check webapp logs for the token:

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

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

1. Create a GitHub OAuth App at https://github.com/settings/developers

2. Set callback URL: http://localhost:8030/auth/github/callback

3. 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:

1. Set up additional supervisor instances on different machines
2. Configure each with the same TRIGGER_WORKER_TOKEN
3. 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

References

• Trigger.dev Documentation
• Self-hosting Guide
• GitHub Repository