Deploy and Host Trigger.dev v4.8 on Railway (Webapp) + DigitalOcean (Supervisor)

Trigger.dev is an open-source platform that lets developers reliably run long-duration background jobs—like AI workflows and data processing—directly in their codebase, without timeouts, manual scaling, or complex setup.

About Hosting Trigger.dev

This template deploys Trigger.dev across two platforms: Railway hosts the webapp (orchestration, API, dashboard) while DigitalOcean runs the supervisor (task execution in Docker containers). This architecture is required because Railway doesn't provide Docker socket access needed for task execution, while DigitalOcean droplets have full Docker capabilities.

The included ops-controller automates the entire deployment process—requiring only a DigitalOcean API token and a Railway API token. After one-click deployment, the system automatically provisions a DigitalOcean droplet, configures task execution, and maintains the supervisor without manual intervention.

Common Use Cases

AI workflow orchestration - LLM pipelines, model inference, and AI agent automation without timeouts
Video and audio processing - Long-running media processing tasks that exceed typical serverless limits
Data import and ETL - Batch processing, data transformation, and migration jobs with progress tracking
Document generation - Automated PDF creation, report generation, and file processing workflows
Webhook automation - Event-driven workflows and third-party service integrations with retry logic
Scheduled task execution - Cron-like scheduling with robust error handling and real-time monitoring
API workflow orchestration - Chain multiple API calls with proper error handling and state management

Architecture: Railway + DigitalOcean

Why Two Platforms? Trigger.dev v4 requires a supervisor service to execute tasks in Docker containers. Railway's platform restrictions prevent Docker socket access (/var/run/docker.sock), making task execution impossible. DigitalOcean droplets provide the full Docker capabilities needed for the supervisor.

How It Works:

Railway Services: Webapp, PostgreSQL, Redis, ClickHouse, Railway Bucket (object storage), Docker registry
DigitalOcean Service: Supervisor droplet for task execution
ops-controller: Automates cross-platform deployment and monitoring
One-Click Setup: Deploy button requires only a DigitalOcean API token and a Railway account or workspace token

Dependencies for Trigger.dev Hosting

PostgreSQL database - Job storage, state management, and task persistence (provided by Railway)
Redis instance - Queue management, real-time features, and caching (provided by Railway)
ClickHouse database - Analytics database for advanced metrics and observability (provided by Railway)
Railway Bucket - S3-compatible object storage for large payloads (provided by Railway)
Docker registry - Password-protected registry for task images, on a persistent volume (provided by Railway)
Node.js/TypeScript runtime - Core execution environment for webapp and task processing
Environment variables - Auto-configured via Railway template with secure secret generation

Deployment Dependencies

Trigger.dev v4.8.3 - Release notes, official upstream images, every image pinned
Railway account - Sign up at railway.app and create an account or workspace token (project tokens don't work)
DigitalOcean account - Sign up at digitalocean.com and generate API token
ops-controller - Automated deployment service (included in template)
Documentation - Official Trigger.dev docs

Optional Services

Electric Sync Engine - Deploy separately for real-time PostgreSQL synchronization
External ClickHouse - Replace built-in ClickHouse with cloud provider, manage with CH-UI
External Object Storage - Replace the Railway Bucket with AWS S3, Cloudflare R2, or another S3-compatible provider

Implementation Details

What's Included:

✅ Railway Services: Trigger.dev webapp, PostgreSQL, Redis, ClickHouse, Railway Bucket, Docker registry
✅ DigitalOcean Supervisor: Automated droplet deployment for task execution
✅ ops-controller: Cross-platform automation with health monitoring and auto-scaling
✅ One-Click Setup: Deploy with just a DigitalOcean and a Railway API token, everything else auto-configured
✅ Official Trigger.dev images, no patched fork
✅ Version-aware ops-controller: change TRIGGER_VERSION and it replaces the supervisor
✅ Auto-generated secure secrets (SESSION_SECRET, ENCRYPTION_KEY, etc.)
✅ Vertical auto-scaling and health monitoring
✅ SSL certificates and secure environment setup

Key v4 Features:

Machine presets - Scale tasks with micro, small-1x, large-2x resource configurations
Real-time streaming - Send live progress updates to your frontend
Enhanced retry logic - Configurable backoff strategies and error handling
TypeScript-first - Full type safety throughout task definitions
Polyglot support - Write tasks in both Node.js/TypeScript and Python

Deploying Tasks

docker login <registry-domain> -u trigger
npx trigger.dev@4.8.3 login -a https://<webapp-domain>
npx trigger.dev@4.8.3 deploy

The first runs wait until the supervisor droplet boots and connects, usually about 5 minutes after the deploy (up to 20).

Upgrading

Set the webapp image tag and the ops-controller's TRIGGER_VERSION to the same new version. The webapp migrates on boot, and the ops-controller replaces the supervisor droplet. ClickHouse can only be upgraded, never downgraded.

Email Configuration (Optional)

Default Behavior: Without email configuration, Trigger.dev logs magic links and invitations to the console instead of sending emails. Check Railway deployment logs to find invitation URLs.

Why Configure Email: Enable automatic magic link authentication and user invitation emails for a seamless user experience.

Option 1: Resend (Recommended)

Best for: Quick setup, excellent deliverability, modern API Free tier: 3,000 emails/month Setup time: ~2 minutes

Add these environment variables to Railway:

EMAIL_TRANSPORT=resend
FROM_EMAIL=onboarding@resend.dev    # Use their test domain instantly
REPLY_TO_EMAIL=support@yourdomain.com
RESEND_API_KEY=re_xxxxxxxxxx        # Get from resend.com dashboard

Setup steps:

Sign up at resend.com (free)
Copy API key from dashboard
Add environment variables to Railway service
Magic links and invitations now send via email! ✅

Option 2: SMTP (Standard Email Server)

Best for: Using existing email infrastructure, Gmail/Outlook integration Setup time: ~10 minutes

EMAIL_TRANSPORT=smtp
FROM_EMAIL=noreply@yourdomain.com
REPLY_TO_EMAIL=support@yourdomain.com
SMTP_HOST=smtp.gmail.com          # Your SMTP server
SMTP_PORT=587                     # Usually 587 for TLS, 465 for SSL
SMTP_SECURE=false                 # true for SSL, false for TLS
SMTP_USER=your-email@gmail.com    # SMTP username
SMTP_PASSWORD=your-app-password   # SMTP password or app password

Popular SMTP servers:

Gmail: smtp.gmail.com:587 (requires App Password)
Outlook: smtp-mail.outlook.com:587
SendGrid: smtp.sendgrid.net:587

Option 3: AWS SES (Enterprise)

Best for: High volume, cost-effective enterprise deployment Setup time: ~30 minutes

EMAIL_TRANSPORT=aws-ses
FROM_EMAIL=noreply@yourdomain.com
REPLY_TO_EMAIL=support@yourdomain.com
AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1              # Your AWS SES region

Requires a verified domain and SES production access.

Finding Invitation Links (No Email Configured)

When email is not configured, find invitation links in Railway logs:

Go to Railway dashboard → trigger.dev service → View Logs
Look for entries: ##### sendEmail to [email], subject: [subject]
Copy magic link URLs: https://your-app.up.railway.app/magic?token=<token>
Share links with users for registration

Why Deploy Trigger.dev on Railway?

This template combines Railway's managed infrastructure with DigitalOcean's Docker capabilities to provide the complete Trigger.dev v4 experience without compromise.

Railway handles your infrastructure complexity - PostgreSQL, Redis, ClickHouse, object storage (Railway Bucket) and the Docker registry run on Railway with automatic backups, while DigitalOcean provides the Docker socket access essential for task execution that Railway cannot offer.

Key Benefits:

True one-click deployment - ops-controller automates the entire cross-platform setup
Zero infrastructure administration - Railway manages databases, DigitalOcean supervisor auto-configures
Cost-effective - Railway services scale to zero when idle, DigitalOcean droplet optimizes for task load
Production-ready - SSL certificates, health monitoring, and observability across both platforms
Complete feature set - Full Trigger.dev v4 capabilities without platform limitations
Automated maintenance - ops-controller handles supervisor updates and health monitoring
Developer-friendly - GitHub integration, automatic deployments, and unified logging