Instalar Trigger.dev en un VPS: guía completa self-hosted

Trigger.dev sustituye las colas caseras (BullMQ, cron frágiles, Lambda que expiran) por una plataforma unificada: tareas duraderas, reintentos automáticos, gestión de la concurrencia y panel en tiempo real. La versión cloud factura por número de ejecuciones y limita la duración de los jobs, algo que enseguida resulta restrictivo para procesos ETL, envíos masivos de correo o llamadas lentas a API.

En self-hosted sobre un VPS, mantiene sus workers en casa: sus claves API de terceros (OpenAI, Stripe, Resend) nunca pasan por un intermediario, y sus jobs pueden durar 10 minutos o varias horas sin ser interrumpidos. El stack se apoya en PostgreSQL, Redis y Docker, lo que lo hace reproducible y fácil de respaldar. La instalación es totalmente gratuita: sin licencia, sin suscripción — solo el coste del VPS.

Trigger.dev es un stack relativamente exigente porque combina la aplicación web, workers, PostgreSQL y Redis. Prevea un VPS con al menos 4 GB de RAM y 2 vCPU para un uso de producción ligero; apunte a 8 GB de RAM y 4 vCPU si ejecuta muchos jobs concurrentes o procesos pesados. Cuente con 40 GB de disco SSD para la base de datos, los logs y las imágenes Docker.

En el plano del software: Docker Engine 24+ y el plugin Docker Compose v2 (compruébelo con docker compose version), un nombre de dominio que apunte a la IP del VPS (por ejemplo trigger.mondomaine.com), y el puerto 443 abierto para HTTPS. Dos secretos son imprescindibles: MAGIC_LINK_SECRET (autenticación sin contraseña) y ENCRYPTION_KEY (32 caracteres hexadecimales, cifra las variables de entorno de los proyectos). Genérelos antes de comenzar — no pueden regenerarse sin romper los datos existentes.

Estos son los cinco errores más comunes al instalar Trigger.dev en self-hosted.

Error: ENCRYPTION_KEY must be 32 characters — Ha usado openssl rand -base64 16 en lugar de openssl rand -hex 16. La forma base64 produce caracteres fuera del juego hexadecimal. Regénere con -hex 16 (exactamente 32 chars).

webapp exited with code 1 al arrancar — Compruebe los logs completos con docker compose logs webapp. La causa más frecuente: DATABASE_URL incorrecta o PostgreSQL no listo todavía. Espere 10 segundos y reinicie con docker compose restart webapp.

El magic link de creación de cuenta no aparece — La aplicación puede haber arrancado antes de que terminaran las migraciones. Ejecute docker compose restart webapp y observe los logs desde el principio. Si el enlace sigue ausente, compruebe que LOGIN_ORIGIN coincide exactamente con su dominio (sin barra final).

Failed to connect en el CLI durante login — El proxy inverso no está aún activo o el DNS no ha propagado todavía hacia su VPS. Pruebe localmente con curl http://127.0.0.1:3030/healthcheck desde el VPS: si responde, el problema está en el proxy o el DNS.

El job se despliega pero no se ejecuta — Compruebe que los workers están en marcha: docker compose ps debe mostrar el servicio worker en estado running. Si el worker está detenido, docker compose up -d worker lo reinicia. Verifique también que TRIGGER_SECRET_KEY en su proyecto coincide con la clave del proyecto correcto en el panel.

Una instancia de Trigger.dev expone el panel y la API en el mismo dominio. Algunas precauciones reducen la superficie de ataque sin complicar la operación.

Firewall: bloquee todos los puertos salvo el 22 (SSH), 80 y 443. El puerto 3030 no debe ser accesible directamente desde el exterior — está reservado para el proxy inverso local.

Rotación de secretos: MAGIC_LINK_SECRET puede rotarse sin romper datos. ENCRYPTION_KEY, en cambio, cifra las variables de entorno de los proyectos — su rotación exige una migración de datos. Guárdelos en un gestor de secretos (Bitwarden, 1Password o HashiCorp Vault).

Actualizaciones: Trigger.dev publica sus releases en GitHub. Para actualizar, tire de la nueva versión (git pull en /opt/trigger/src), reconstruya las imágenes (docker compose pull) y reinicie (docker compose up -d). Las migraciones de base de datos se aplican automáticamente al arrancar webapp.

Copias de seguridad: programe un volcado diario de PostgreSQL hacia almacenamiento externo. Un cron mínimo: 0 3 * * * docker exec trigger-postgres-1 pg_dump -U postgres trigger | gzip > /opt/backups/trigger-$(date +%F).sql.gz.

Un job de Trigger.dev es una función TypeScript exportada desde un fichero trigger/ de su proyecto. Un ejemplo mínimo de envío de correo diferido:

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

export const sendWelcomeEmail = task({
  id: "send-welcome-email",
  run: async (payload: { userId: string; email: string }) => {
    // su lógica de envío aquí
    await sendEmail(payload.email, "¡Bienvenido!");
    return { sent: true };
  },
});

Despliegue con npx trigger.dev@latest deploy. El panel muestra entonces su job bajo la pestaña Tasks. Ejecute un test desde el panel o desde su código: await sendWelcomeEmail.trigger({ userId: "u1", email: "[email protected]" }). Los reintentos automáticos se aplican en caso de error — configurables con la opción retry en task().

Para jobs largos (importación de CSV, procesamiento de imágenes), use wait.for() para suspender la ejecución y no bloquear un worker durante pausas de red: Trigger.dev reanuda el job donde lo dejó, incluso tras un reinicio del contenedor.