Docker Compose (Self-Hosting)

The quickest way to get started with a self-hosted Trigger.dev deployment.

Production Warning

This guide alone is unlikely to result in a fully production-ready deployment. For production, harden your configuration and consider the Kubernetes guide.

Requirements

Component	Minimum
Webapp machine	3+ vCPU, 6+ GB RAM
Worker machine	4+ vCPU, 8+ GB RAM
Docker	20.10.0+
Docker Compose	2.20.0+

What's New in v4

• Combined supervisor (simplified setup)
• Automatic container cleanup
• Horizontal worker scaling
• Built-in resource limits
• Docker Socket Proxy integration
• Network isolation

Setup Steps

1. Clone the Repository

git clone https://github.com/triggerdotdev/trigger.dev
cd trigger.dev

2. Create Environment File

cp .env.example .env
# Edit .env with your configuration

3. Start Services

docker compose up -d

4. Configure Worker Token

Worker tokens connect supervisor instances to the webapp. Two options:

Automatic bootstrap — configured in your .env file with a pre-generated token.

Manual creation — create from the dashboard → Settings → Workers.

Key Configuration Areas

Container Registry

A built-in container registry runs at localhost:5000. Alternatively, configure an external registry (Docker Hub, ECR, GCR).

Object Storage

MinIO handles payloads by default. Configure external S3-compatible storage by setting the appropriate env vars.

Authentication Methods

Method	Env vars required
Magic links (default)	Email transport
GitHub OAuth	GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
SMTP	SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS
Resend	RESEND_API_KEY
AWS SES	AWS credentials

CLI Profile Setup

When self-hosting, configure a CLI profile pointing to your instance:

npx trigger.dev login --profile self-hosted --api-url https://your-trigger-instance.example.com

Then deploy using the profile:

npx trigger.dev deploy --profile self-hosted

CI / GitHub Actions

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

- name: Login to Registry
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

- name: Deploy
  env:
    TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
    TRIGGER_API_URL: ${{ secrets.TRIGGER_API_URL }}
  run: npx trigger.dev@latest deploy

Version Pinning

Pin Docker image tags for reproducible deployments:

# docker-compose.yml
services:
  webapp:
    image: ghcr.io/triggerdotdev/trigger.dev:4.x.x  # pin specific version
  worker:
    image: ghcr.io/triggerdotdev/trigger.dev:4.x.x

Keep CLI in sync

The CLI version must match the self-hosted version. Pin trigger.dev in your package.json devDependencies.

Troubleshooting

Issue	Solution
Deployment failures	Check build logs in dashboard
Email not delivered	Verify email transport config in .env
PostgreSQL migration errors	Run migrations manually; check DB connection
Worker not connecting	Verify worker token is correct

Telemetry

OpenTelemetry integration is available for monitoring. Configure exporters in the webapp environment to send to Axiom, Honeycomb, Datadog, etc.

Community Support

Join the #self-hosting channel on Discord for help.