Installer Trigger.dev sur un VPS : guide complet self-hosted

Trigger.dev remplace les files d'attente maison (BullMQ, cron fragiles, Lambda qui timeout) par une plateforme unifiée : tâches durables, retries automatiques, gestion de la concurrence et tableau de bord en temps réel. La version cloud facture au nombre d'exécutions et limite la durée des jobs, ce qui devient vite contraignant pour des traitements ETL, des envois d'emails en masse ou des appels d'API lents.

En self-hosted sur un VPS, vous gardez vos workers chez vous : vos clés API tierces (OpenAI, Stripe, Resend) ne transitent jamais par un tiers, et vos jobs peuvent tourner 10 minutes ou plusieurs heures sans être coupés. La stack repose sur PostgreSQL, Redis et Docker, ce qui la rend reproductible et facile à sauvegarder. L'installation est totalement gratuite : aucune licence, aucun abonnement — seul le coût du VPS s'applique.

Trigger.dev est une stack relativement gourmande car elle combine l'application web, des workers, PostgreSQL et Redis. Prévoyez un VPS avec au minimum 4 Go de RAM et 2 vCPU pour un usage de production léger ; visez 8 Go de RAM et 4 vCPU si vous exécutez beaucoup de jobs concurrents ou des traitements lourds. Comptez 40 Go de disque SSD pour la base de données, les logs et les images Docker.

Côté logiciel : Docker Engine 24+ et le plugin Docker Compose v2 (vérifiez avec docker compose version), un nom de domaine pointant vers l'IP du VPS (par exemple trigger.mondomaine.com), et le port 443 ouvert pour le HTTPS. Deux secrets sont indispensables : MAGIC_LINK_SECRET (authentification sans mot de passe) et ENCRYPTION_KEY (32 caractères hexadécimaux, chiffrement des variables d'environnement de vos projets). Générez-les avant de commencer — ils ne se régénèrent pas sans casser les données existantes.

Voici les cinq erreurs les plus courantes rencontrées lors de l'installation de Trigger.dev en self-hosted.

Error: ENCRYPTION_KEY must be 32 characters — Vous avez utilisé openssl rand -base64 16 au lieu de openssl rand -hex 16. La forme base64 produit des caractères hors du jeu hexadécimal. Régénérez avec -hex 16 (exactement 32 chars).

webapp exited with code 1 au démarrage — Vérifiez les logs complets avec docker compose logs webapp. Cause la plus fréquente : DATABASE_URL incorrecte ou PostgreSQL pas encore prêt. Attendez 10 secondes et relancez avec docker compose restart webapp.

Le magic link de création de compte ne s'affiche pas — L'application a peut-être démarré avant la fin des migrations. Relancez docker compose restart webapp et regardez les logs dès le démarrage. Si le lien reste absent, vérifiez que LOGIN_ORIGIN correspond exactement à votre domaine (sans slash final).

Failed to connect dans le CLI lors du login — Le reverse proxy n'est pas encore actif ou le DNS ne pointe pas encore vers votre VPS. Testez localement avec curl http://127.0.0.1:3030/healthcheck depuis le VPS : si ça répond, le problème est côté proxy ou DNS.

Le job se déploie mais ne s'exécute pas — Vérifiez que les workers sont bien démarrés : docker compose ps doit montrer le service worker en état running. Si le worker est arrêté, docker compose up -d worker le redémarre. Vérifiez aussi que TRIGGER_SECRET_KEY dans votre projet correspond à la clé du bon projet dans le dashboard.

Une instance Trigger.dev expose le dashboard et l'API sur le même domaine. Quelques précautions réduisent la surface d'attaque sans compliquer l'exploitation.

Firewall : bloquez tous les ports sauf 22 (SSH), 80 et 443 (avec ufw allow pour chacun). Le port 3030 ne doit jamais être accessible directement depuis l'extérieur — il est réservé au reverse proxy local.

Rotation des secrets : MAGIC_LINK_SECRET peut être rotaté sans casser les données. ENCRYPTION_KEY, en revanche, chiffre les variables d'environnement des projets — une rotation exige une migration de données. Notez-les dans un gestionnaire de secrets (Bitwarden, 1Password ou HashiCorp Vault).

Mises à jour : Trigger.dev publie ses releases sur GitHub. Pour mettre à jour, tirez la nouvelle version (git pull dans /opt/trigger/src), reconstruisez les images (docker compose pull) et redémarrez (docker compose up -d). Les migrations de base de données s'appliquent automatiquement au démarrage de webapp.

Sauvegardes : planifiez un dump PostgreSQL quotidien vers un stockage externe. Un cron minimal : 0 3 * * * docker exec trigger-postgres-1 pg_dump -U postgres trigger | gzip > /opt/backups/trigger-$(date +%F).sql.gz.

Un job Trigger.dev est une fonction TypeScript exportée depuis un fichier trigger/ de votre projet. Voici un exemple minimal d'envoi d'email différé :

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

export const sendWelcomeEmail = task({
  id: "send-welcome-email",
  run: async (payload: { userId: string; email: string }) => {
    // votre logique d'envoi ici
    await sendEmail(payload.email, "Bienvenue !");
    return { sent: true };
  },
});

Déployez avec npx trigger.dev@latest deploy. Le dashboard affiche alors votre job sous l'onglet Tasks. Déclenchez une exécution test depuis le dashboard ou depuis votre code : await sendWelcomeEmail.trigger({ userId: "u1", email: "[email protected]" }). Les retries automatiques s'appliquent en cas d'erreur — configurables avec l'option retry sur le task().

Pour les jobs longs (import CSV, traitement d'images), utilisez wait.for() pour suspendre l'exécution et ne pas bloquer un worker pendant les pauses réseau : Trigger.dev reprend le job là où il s'était arrêté, même après un redémarrage du container.