Installing Trigger.dev on a VPS: complete self-hosted guide

Trigger.dev replaces homemade queues (BullMQ, fragile crons, Lambdas that time out) with a unified platform: durable tasks, automatic retries, concurrency management and a real-time dashboard. The cloud version bills by the number of executions and limits job duration, which quickly becomes constraining for ETL processing, mass email sending or slow API calls.

Self-hosted on a VPS, you keep your workers on your side: your third-party API keys (OpenAI, Stripe, Resend) never pass through a third party, and your jobs can run for 10 minutes or several hours without being cut off. The stack relies on PostgreSQL, Redis and Docker, making it reproducible and easy to back up. The installation is completely free: no licence, no subscription — only the VPS cost applies.

Trigger.dev is a relatively resource-hungry stack because it combines the web application, workers, PostgreSQL and Redis. Plan for a VPS with at least 4 GB of RAM and 2 vCPU for light production use; aim for 8 GB of RAM and 4 vCPU if you run many concurrent jobs or heavy processing. Allow 40 GB of SSD disk for the database, logs and Docker images.

On the software side: Docker Engine 24+ and the Docker Compose v2 plugin (check with docker compose version), a domain name pointing to the VPS IP (for example trigger.mydomain.com), and port 443 open for HTTPS. Two secrets are essential: MAGIC_LINK_SECRET (passwordless authentication) and ENCRYPTION_KEY (32 hexadecimal characters, encrypts project environment variables). Generate them before you begin — they cannot be regenerated without breaking existing data.

Here are the five most common errors encountered when installing Trigger.dev self-hosted.

Error: ENCRYPTION_KEY must be 32 characters — You used openssl rand -base64 16 instead of openssl rand -hex 16. The base64 form produces characters outside the hexadecimal character set. Regenerate with -hex 16 (exactly 32 chars).

webapp exited with code 1 on startup — Check the full logs with docker compose logs webapp. Most common cause: incorrect DATABASE_URL or PostgreSQL not yet ready. Wait 10 seconds and restart with docker compose restart webapp.

The account creation magic link does not appear — The application may have started before migrations finished. Restart docker compose restart webapp and watch the logs from the beginning. If the link is still absent, check that LOGIN_ORIGIN exactly matches your domain (no trailing slash).

Failed to connect in the CLI during login — The reverse proxy is not yet active or DNS has not yet propagated to your VPS. Test locally with curl http://127.0.0.1:3030/healthcheck from the VPS: if it responds, the issue is on the proxy or DNS side.

The job deploys but does not run — Check that the workers are running: docker compose ps should show the worker service in running state. If the worker is stopped, docker compose up -d worker restarts it. Also check that TRIGGER_SECRET_KEY in your project matches the key of the correct project in the dashboard.

A Trigger.dev instance exposes the dashboard and the API on the same domain. A few precautions reduce the attack surface without complicating operations.

Firewall: block all ports except 22 (SSH), 80 and 443 (with ufw allow for each). Port 3030 must never be directly accessible from outside — it is reserved for the local reverse proxy.

Secret rotation: MAGIC_LINK_SECRET can be rotated without breaking data. ENCRYPTION_KEY, however, encrypts project environment variables — rotation requires a data migration. Store them in a secrets manager (Bitwarden, 1Password or HashiCorp Vault).

Updates: Trigger.dev publishes releases on GitHub. To update, pull the new version (git pull in /opt/trigger/src), rebuild the images (docker compose pull) and restart (docker compose up -d). Database migrations are applied automatically at webapp startup.

Backups: schedule a daily PostgreSQL dump to external storage. A minimal cron: 0 3 * * * docker exec trigger-postgres-1 pg_dump -U postgres trigger | gzip > /opt/backups/trigger-$(date +%F).sql.gz.

A Trigger.dev job is a TypeScript function exported from a trigger/ file in your project. Here is a minimal example of a deferred email send:

import { task } from "@trigger.dev/sdk/v3";

export const sendWelcomeEmail = task({
  id: "send-welcome-email",
  run: async (payload: { userId: string; email: string }) => {
    // your sending logic here
    await sendEmail(payload.email, "Welcome!");
    return { sent: true };
  },
});

Deploy with npx trigger.dev@latest deploy. The dashboard then shows your job under the Tasks tab. Trigger a test run from the dashboard or from your code: await sendWelcomeEmail.trigger({ userId: "u1", email: "[email protected]" }). Automatic retries apply on error — configurable with the retry option on task().

For long jobs (CSV import, image processing), use wait.for() to suspend execution and avoid blocking a worker during network pauses: Trigger.dev resumes the job where it left off, even after a container restart.