Installer n8n sur un VPS KVM avec Docker

n8n est un outil d'automatisation : dans un éditeur visuel, vous enchaînez des étapes (webhooks, appels d'API, e-mails, bases de données, tâches planifiées) pour former des workflows. Ce guide installe n8n 2.47.5 avec Docker Compose, publié en HTTPS sur https://nom.vps.heberghub.app.

n8n est diffusé sous sa propre licence, la Sustainable Use License : c'est vous qui l'installez et l'exploitez sur votre VPS, dans le cadre de cette licence.

Ce qu'il vous faut

Un VPS KVM : Docker ne s'installe correctement que sur une machine virtuelle, pas sur un VPS LXC.
Docker et Docker Compose installés : voir Installer Docker sur un VPS KVM.
Un accès SSH par clé (Première connexion SSH) et un VPS sécurisé (Sécuriser un VPS Debian).
Le port 80 libre et environ 2 Go d'espace disque pour l'image.

Dans notre essai, n8n occupait environ 400 Mo de mémoire au repos.

1. Le fichier .env

bash

mkdir -p /opt/n8n && cd /opt/n8n
openssl rand -hex 32

La seconde commande affiche une clé aléatoire, qui chiffrera les identifiants confiés à n8n (mots de passe, jetons d'API). Créez /opt/n8n/.env :

ini

# Adresse publique
N8N_HOST=nom.vps.heberghub.app
N8N_PROTOCOL=https
N8N_WEBHOOK_URL=https://nom.vps.heberghub.app/
# Un proxy devant n8n : le frontal HTTPS
N8N_PROXY_HOPS=1
# Fuseau des déclencheurs planifiés
GENERIC_TIMEZONE=Europe/Paris
TZ=Europe/Paris
# Clé affichée par openssl
N8N_ENCRYPTION_KEY=collez-ici-la-cle
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true

bash

chmod 600 .env

N8N_WEBHOOK_URL fixe l'adresse affichée dans les nœuds Webhook ; sans elle, notre essai affichait une adresse en :5678, injoignable. L'ancien nom WEBHOOK_URL est déprécié depuis n8n 2.35.0.
N8N_PROTOCOL=https décrit l'adresse publique : n8n écoute toujours en HTTP dans le conteneur.
GENERIC_TIMEZONE : sans elle, n8n prend America/New_York.
La clé : sans N8N_ENCRYPTION_KEY, n8n en génère une dans le volume. La fixer ici vous permet de la sauvegarder à part.

2. Le fichier compose.yaml

yaml

services:
  n8n:
    image: docker.io/n8nio/n8n:2.47.5
    restart: unless-stopped
    env_file: .env
    ports:
      - "80:5678"                # le frontal HTTPS arrive sur le port 80, n8n écoute sur 5678
    volumes:
      - data:/home/node/.n8n     # base SQLite, fichier config (la clé), journaux

volumes:
  data:

Seul le port 80 est publié. Docker contourne ufw : ne publiez pas d'autre port, en particulier pas le 5678.
Le HTTPS est géré en amont. Le certificat de nom.vps.heberghub.app est géré par le frontal ; votre VPS reçoit le trafic en HTTP sur son port 80, avec l'en-tête X-Forwarded-Proto: https. N'installez pas de certificat dans le VPS pour ce nom.
SQLite par défaut. Workflows, identifiants et exécutions sont dans database.sqlite, dans le volume. PostgreSQL est possible (DB_TYPE=postgresdb, voir la documentation de n8n).

3. Premier lancement et compte propriétaire

bash

docker compose up -d
docker compose logs -f n8n

Le premier lancement crée la base : ne l'interrompez pas. Quand le journal affiche Editor is now accessible via: suivi de votre adresse, quittez avec Ctrl+C et ouvrez https://nom.vps.heberghub.app.

Le premier écran crée le compte propriétaire : e-mail, prénom, nom et mot de passe de 8 à 64 caractères, avec au moins un chiffre et une majuscule. Faites-le tout de suite : tant que ce compte n'existe pas, la première personne qui ouvre l'adresse peut le créer.

Ouvrez toujours l'éditeur en https:// : son cookie de session est réservé au HTTPS.

4. Les webhooks derrière le frontal

Adresses. Un nœud Webhook a deux adresses : https://nom.vps.heberghub.app/webhook-test/<chemin>, active pendant que l'éditeur attend un événement de test, et https://nom.vps.heberghub.app/webhook/<chemin>, active une fois le workflow publié.

Traitements longs : 300 secondes au plus. Le frontal coupe une requête qui dure plus de 300 s. Si le Webhook répond When Last Node Finishes, ou par un nœud Respond to Webhook placé après un long traitement, l'appelant reçoit une erreur. Dans notre essai, l'exécution s'est terminée après la coupure, mais sa réponse était perdue. Réglez alors Respond sur Immediately : n8n répond aussitôt (Workflow was started), poursuit, puis transmet le résultat autrement (e-mail, autre API).

Taille des envois. n8n accepte 16 Mio par requête (N8N_PAYLOAD_SIZE_MAX) et 200 Mio par fichier de formulaire (N8N_FORMDATA_FILE_SIZE_MAX). Au-delà, notre essai a reçu une erreur 500 (request entity too large dans le journal). Vous pouvez relever ces valeurs, mais le frontal refuse tout envoi de plus de 512 Mo.

WebSocket. Le suivi en direct des exécutions passe par WebSocket, que le frontal accepte.

Votre propre domaine. Ajoutez-le dans l'espace client (TXT _heberghub-verify et CNAME vers nom.vps.heberghub.app, voir Relier un nom de domaine). Mettez-le dans N8N_HOST et N8N_WEBHOOK_URL, relancez docker compose up -d, puis mettez à jour les services qui appellent vos webhooks.

5. Envoyer des e-mails

n8n envoie des e-mails pour inviter des utilisateurs et réinitialiser un mot de passe. Sur votre VPS, le port 25 est fermé en sortie (anti-spam) ; les ports 465 et 587 sont ouverts, avec un nombre de connexions par minute limité. Ajoutez à .env le serveur SMTP authentifié de votre messagerie ou d'un service d'envoi :

ini

N8N_EMAIL_MODE=smtp
N8N_SMTP_HOST=smtp.votre-messagerie.fr
N8N_SMTP_PORT=465
N8N_SMTP_SSL=true
N8N_SMTP_USER[email protected]
N8N_SMTP_PASS=mot-de-passe-smtp
N8N_SMTP_SENDER[email protected]

Sur le port 587, mettez N8N_SMTP_PORT=587 et N8N_SMTP_SSL=false : STARTTLS (N8N_SMTP_STARTTLS) est actif par défaut. Relancez avec docker compose up -d.

Le nœud Send Email de vos workflows suit la même règle. Pour des envois nombreux, préférez l'API HTTPS d'un service d'envoi.

Mot de passe oublié sans SMTP. Cette commande supprime tous les comptes et rouvre la création du propriétaire ; dans notre essai, workflows et identifiants ont été conservés :

bash

docker compose exec n8n n8n user-management:reset

6. Mettre à jour

Lisez les notes de version de n8n, sauvegardez (section suivante), remplacez 2.47.5 par la nouvelle version dans compose.yaml, puis :

bash

docker compose pull && docker compose up -d

n8n migre sa base au démarrage, et revenir à l'image précédente n'annule pas cette migration : en cas de problème, restaurez la sauvegarde. n8n conseille une mise à jour au moins mensuelle.

7. Sauvegarder

Votre VPS est sauvegardé chaque nuit en entier, n8n compris ; pour restaurer n8n seul, ou avant une mise à jour, faites votre propre archive. Le volume contient la base database.sqlite et le fichier config (la clé). Arrêtez n8n le temps de l'archive, comme le demande sa documentation :

bash

cd /opt/n8n
docker compose stop
tar -czf n8n-$(date +%F).tar.gz -C /var/lib/docker/volumes/n8n_data/_data .
docker compose start

Le chemin vaut pour le dossier /opt/n8n (docker volume ls donne le nom du volume). Pour restaurer : arrêtez n8n, videz le volume, décompressez-y l'archive, gardez le même .env, puis relancez.

En complément, exportez workflows et identifiants pour les réimporter ailleurs :

bash

docker compose exec n8n n8n export:workflow --backup --output=/home/node/.n8n/backups/workflows/
docker compose exec n8n n8n export:credentials --backup --output=/home/node/.n8n/backups/credentials/
docker compose cp n8n:/home/node/.n8n/backups ./backups-$(date +%F)

Les identifiants exportés restent chiffrés par la clé. Pour les réimporter (n8n import:workflow --separate --input=…, puis n8n import:credentials --separate --input=…), créez d'abord le compte propriétaire ; les workflows arrivent désactivés.

Copiez l'archive, les exports et .env hors du VPS, dans un endroit protégé. Sans la clé, personne ne peut relire vos identifiants, vous compris.

Plusieurs applications sur le VPS

Si une autre application doit répondre sur le port 80, placez un relais (Caddy, nginx ou Traefik) sur ce port : il répartit par nom de domaine, et n8n ne publie plus de port. Le relais doit transmettre Upgrade et Connection (WebSocket), ainsi que les en-têtes X-Forwarded-* demandés par la documentation de n8n. Voir Installer Docker sur un VPS KVM.

Problèmes fréquents

Symptôme	Cause probable
Le conteneur redémarre en boucle, `Mismatching encryption keys` dans le journal	`N8N_ENCRYPTION_KEY` différente de la clé déjà enregistrée dans le volume : remettez la clé d'origine.
L'appelant reçoit une erreur au bout de 5 minutes	Réponse attendue en fin de traitement : réglez Respond sur Immediately.
Erreur 500, `request entity too large` dans le journal	Envoi de plus de 16 Mio : relevez `N8N_PAYLOAD_SIZE_MAX`, dans la limite de 512 Mo du frontal.
Adresse de production en 404	Workflow non publié.
`Python 3 is missing` dans le journal	Normal avec l'image seule : le runner JavaScript démarre, pas le runner Python (voir les task runners dans la documentation de n8n).
E-mail en échec	Port 25 utilisé : passez par 465 ou 587 avec authentification.

Besoin d'aide ?

Ouvrez un ticket depuis votre espace client avec le nom du VPS, la sortie de docker compose ps et les dernières lignes de docker compose logs n8n. Ne transmettez jamais .env ni votre clé de chiffrement.