n8n avec Docker : le fichier compose expliqué ligne par ligne

Tous les tutoriels d’installation de n8n vous font copier le même fichier d’une vingtaine de lignes. Il
fonctionne, et c’est bien le problème : il fonctionne sans que vous sachiez ce qu’il
fait. Le jour où quelque chose coince — un port occupé, un fuseau horaire décalé, des
identifiants qui disparaissent après une mise à jour — vous n’avez aucune prise.

Cet article prend ce fichier et l’explique bloc par bloc. Vous saurez ce que chaque ligne
change, lesquelles sont indispensables, lesquelles sont du décor recopié de blog en blog, et
où se cachent les trois pièges qui font perdre des soirées. Aucune connaissance préalable de
Docker n’est nécessaire : on part de zéro. Si vous cherchez plutôt la procédure complète
de bout en bout, elle est dans installer n8n sur un
VPS ; et pour savoir sur quelle machine, voyez quel
VPS choisir pour n8n.

Pourquoi Docker plutôt qu’une installation classique

n8n peut s’installer directement sur une machine, comme n’importe quelle application
Node.js. Beaucoup commencent ainsi, et beaucoup le regrettent. La raison n’est pas
idéologique, elle est très concrète.

Une installation classique dépend de ce qui est déjà présent sur votre serveur : la
version de Node.js, celle de certaines bibliothèques système, les droits des dossiers. Deux
serveurs qui semblent identiques donnent des résultats différents, et le message d’erreur ne
dit jamais laquelle des trente dépendances pose problème. Vous passez la soirée à réparer un
environnement au lieu de monter des automatisations.

Docker supprime la question. L’application arrive avec tout ce dont elle a besoin, figé
dans un paquet unique. Le serveur n’a besoin de rien d’autre que Docker lui-même. La
conséquence pratique la plus utile : votre installation devient reproductible.
Le même fichier redonnera exactement la même installation dans six mois, sur une autre
machine, chez un autre hébergeur.

Deuxième conséquence, encore plus appréciable : la mise à jour cesse d’être un
événement. Changer de version consiste à récupérer un autre paquet et à relancer. Si la
nouvelle version pose problème, vous revenez à l’ancienne en une commande. Sur une
installation classique, revenir en arrière est un chantier.

Les trois mots qu’il faut comprendre

Le vocabulaire Docker fait fuir, alors qu’il tient en trois notions. Les comprendre suffit
à lire n’importe quel fichier de configuration.

L’image est le modèle. Un paquet figé, téléchargé une fois, qui contient
l’application et tout son environnement. Elle ne se modifie jamais. Mettre à jour n8n, c’est
prendre une autre image.

Le conteneur est l’application en train de tourner, créée à partir de
l’image. Il est jetable : on peut le supprimer et le recréer autant de fois
qu’on veut. C’est déroutant au début, et c’est justement ce qui rend Docker confortable.

Le volume est l’espace de stockage branché sur le conteneur. C’est lui
qui contient vos automatisations, vos identifiants et votre historique. Il survit à la
suppression du conteneur, aux mises à jour, aux redémarrages.

Retenez cette phrase, elle vous évitera l’accident le plus grave : supprimer
un conteneur ne perd rien, supprimer un volume perd tout. Beaucoup de messages
d’aide commencent par « j’ai voulu repartir propre » et se terminent par la perte
de trois mois de travail.

Le fichier compose, bloc par bloc

Le fichier de configuration décrit ce qu’il faut faire tourner et comment. On l’appelle
compose parce qu’il compose plusieurs éléments — même quand il n’y en a qu’un. Voici
le fichier minimal qui suffit réellement.

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:VERSION   # ← le numéro, jamais « latest »
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"              # ← accessible seulement en local
    environment:
      - N8N_HOST=n8n.mondomaine.fr
      - WEBHOOK_URL=https://n8n.mondomaine.fr/
      - N8N_ENCRYPTION_KEY=une-longue-chaine-aleatoire-a-vous
      - GENERIC_TIMEZONE=Europe/Paris
      - TZ=Europe/Paris
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=336         # 336 heures = 14 jours
    volumes:
      - ./donnees:/home/node/.n8n

Remplacez VERSION par le numéro publié sur la page des versions de n8n, et le domaine par le vôtre. Le port n’est ouvert que sur la machine elle-même : c’est ce qu’il faut dès qu’un mandataire assure le HTTPS. Si votre mandataire tourne lui aussi dans un conteneur, retirez le bloc ports et laissez-les communiquer par leur réseau interne.

Chaque bloc a une fonction précise, et un seul est réellement dangereux à mal régler.
Passons-les en revue.

L’image et son étiquette : le piège de « latest »

La ligne qui désigne l’image se termine par une étiquette, après le deux-points. Presque
tous les tutoriels écrivent latest, qui signifie « la plus récente ». Cela
paraît raisonnable et c’est une mauvaise idée en production.

Le problème est que cette étiquette bouge. Le fichier que vous conservez
précieusement ne décrit plus une installation précise : il décrit « ce qui était le
plus récent au moment où vous avez relancé ». Deux conséquences désagréables. D’abord,
un redémarrage banal peut vous faire changer de version sans que vous l’ayez demandé.
Ensuite, quand quelque chose casse, vous ne savez pas quelle version vous exécutez, ni vers
laquelle revenir.

Fixez un numéro de version. Vous mettrez à jour quand vous l’aurez décidé,
en changeant ce numéro — c’est-à-dire en sachant exactement d’où vous partez et où vous allez.
C’est un caractère de plus à écrire et c’est la meilleure décision de tout le fichier.

Deux étiquettes méritent en revanche d’être évitées franchement : celles qui désignent
les versions de développement. Elles contiennent des fonctionnalités non stabilisées, et une
instance de production n’est pas l’endroit où les découvrir.

Sur l’adresse de l’image elle-même : n8n est publié à la fois sur le dépôt public
généraliste et sur le registre officiel du projet. Les deux fonctionnent et contiennent la
même chose. Le registre officiel a l’avantage de ne pas être soumis aux limites de
téléchargement du dépôt public, qui peuvent bloquer une mise à jour au mauvais moment.

Le volume : où vivent réellement vos données

C’est le bloc le plus important du fichier, et celui que les tutoriels expédient en une
ligne. Tout ce que vous construisez vit dedans : les automatisations, les identifiants
chiffrés, l’historique des exécutions, et la base de données si vous restez sur la
configuration par défaut.

Deux manières de le déclarer, et le choix a des conséquences.

La première laisse Docker gérer l’emplacement : vous donnez un nom, il range où il
veut. C’est simple, robuste, et cela évite tous les problèmes de droits d’accès. L’inconvénient
est que l’emplacement réel n’est pas évident à retrouver quand vous voulez sauvegarder.

La seconde désigne un dossier de votre serveur. Vous savez exactement où sont vos données,
ce qui rend les sauvegardes triviales. Mais elle introduit le piège des droits :
l’application ne tourne pas en tant qu’administrateur à l’intérieur du conteneur, et si le
dossier appartient à quelqu’un d’autre, elle ne pourra rien y écrire. Le symptôme est un
message de permission refusée au démarrage, et c’est l’un des trois échecs les plus fréquents
d’une première installation.

Notre recommandation : prenez la seconde, mais réglez les droits du dossier
avant le premier démarrage plutôt qu’après le premier message d’erreur. Savoir où
sont ses données vaut largement les trente secondes que cela coûte.

Les variables qui comptent, et celles qu’on peut ignorer

Le bloc des variables d’environnement est le plus long, et c’est là que les fichiers
trouvés en ligne accumulent le plus de lignes inutiles — souvent recopiées d’un contexte qui
n’est pas le vôtre. Voici le tri.

Tout le reste peut attendre. n8n possède plusieurs dizaines de variables ; en régler
six suffit pour une instance saine. Ajoutez les autres quand un besoin précis se présente,
pas par précaution.

Le fuseau horaire : le piège numéro un

Si vous ne deviez retenir qu’un réglage de tout cet article, ce serait celui-là. Par défaut,
un conteneur vit en temps universel — deux heures de décalage avec la France en été, une en
hiver.

Les conséquences sont sournoises parce qu’elles ne provoquent aucune erreur. Vos
automatisations programmées se déclenchent au mauvais moment : le rapport du lundi matin
arrive le dimanche soir, le rappel de la veille part deux heures trop tôt. Rien ne casse, rien
n’alerte ; simplement, tout est décalé, et vous chercherez la cause du côté de vos
automatisations alors qu’elle est ici.

Deux réglages sont nécessaires, et c’est là que beaucoup se trompent en n’en posant qu’un.
L’un fixe l’heure du système à l’intérieur du conteneur, l’autre fixe le fuseau que n8n
utilise pour ses déclencheurs programmés. Renseignez les deux avec la même valeur.

Vérification en dix secondes après le démarrage : créez une automatisation
programmée pour dans deux minutes, et regardez si elle part à l’heure de votre montre.
Faites-le avant de monter quoi que ce soit d’important.

La clé de chiffrement : à définir soi-même

n8n chiffre les identifiants que vous enregistrez — vos accès à votre messagerie, à votre
tableur, à votre système de facturation. La clé qui protège tout cela est générée
automatiquement au premier démarrage si vous n’en fournissez pas.

C’est commode, et cela crée une dépendance invisible : cette clé vit dans le volume.
Le jour où vous voulez déplacer votre instance sur un autre serveur, restaurer une sauvegarde
partielle, ou repartir d’un volume neuf, vos identifiants deviennent illisibles. Il faut alors
tout reconnecter à la main — ce qui, sur trente automatisations, occupe une soirée entière.

Définissez la clé vous-même, dans le fichier, et conservez-la ailleurs que sur le
serveur. Une longue suite de caractères aléatoires suffit. C’est trente secondes au
montage, et c’est la différence entre une migration d’une heure et une soirée de
reconnexions.

Précaution qui va avec : ce fichier contient désormais un secret. Ne le déposez pas
dans un dépôt de code public, et si vous le versionnez, sortez les valeurs sensibles dans un
fichier séparé que vous excluez du suivi.

L’adresse publique et les webhooks

Un webhook est une adresse que vos autres outils appellent pour déclencher une
automatisation. Pour qu’ils y parviennent, n8n doit connaître sa propre adresse publique — et
il ne peut pas la deviner.

C’est la deuxième cause d’appels au secours après le fuseau horaire, et le symptôme est
caractéristique : l’interface affiche une adresse de webhook qui commence par
localhost ou par une adresse interne. Vous la collez chez votre prestataire, il
n’arrive jamais à rien, et aucun message d’erreur ne vous dit pourquoi.

La correction tient en une variable qui déclare l’adresse complète par laquelle on vous
joint, avec le protocole. Renseignez-la dès le montage : les webhooks déjà distribués à
vos prestataires ne se mettent pas à jour tout seuls, et corriger après coup suppose de
repasser chez chacun d’eux.

Le HTTPS : pourquoi il ne se règle pas dans ce fichier

Question qui revient systématiquement : où met-on le certificat ? Réponse :
nulle part ici. n8n ne gère pas le chiffrement de la connexion lui-même, et c’est très bien
ainsi.

Le travail revient à une pièce placée devant lui, qu’on appelle un serveur mandataire
inverse. Elle reçoit tout le trafic, gère le certificat, le renouvelle automatiquement, et
transmet à n8n en interne. Deux outils dominent : l’un demande trois lignes de
configuration et obtient le certificat tout seul, l’autre est plus puissant et plus verbeux.
Pour une instance n8n, le premier suffit largement.

Conséquence pratique sur le fichier : dès qu’un mandataire est en place,
n’exposez plus le port de n8n vers l’extérieur. Laissez-le accessible
uniquement en interne. Beaucoup de fichiers trouvés en ligne conservent l’ouverture publique
alors qu’un mandataire est installé : l’interface reste alors joignable en clair, sans
chiffrement, sur un autre port. C’est un défaut de sécurité discret et très répandu.

Le montage complet du mandataire, avec le fichier de configuration commenté, est décrit
dans installer n8n sur un VPS.

Les six commandes du quotidien

Une fois le fichier écrit, l’exploitation courante tient en six commandes. Toutes se
lancent depuis le dossier qui contient le fichier.

Une remarque sur la forme des commandes : il existe deux écritures, l’ancienne avec un
trait d’union et la nouvelle sans. Les documentations en ligne mélangent les deux, ce qui
désoriente. La forme sans trait d’union est la seule maintenue aujourd’hui ; si elle vous
renvoie une erreur, c’est que votre installation de Docker est ancienne.

Poser une limite de mémoire au conteneur

Voici un réglage absent de tous les fichiers que l’on trouve en ligne, et qui évite pourtant
la panne la plus désagréable : par défaut, un conteneur peut consommer toute la
mémoire de la machine. Une seule exécution qui manipule un fichier trop gros, et c’est le
système d’exploitation qui arbitre — en arrêtant brutalement ce qui consomme le plus.

Le résultat est déroutant : votre instance disparaît sans message d’erreur dans ses
propres journaux, parce qu’elle n’a pas eu le temps d’en écrire un. Vous retrouvez un conteneur
redémarré, des exécutions coupées en plein milieu, et rien qui explique pourquoi.

Déclarer un plafond change la nature de l’incident. Au lieu d’emporter la machine entière,
l’exécution trop gourmande échoue seule, proprement, avec une erreur visible dans l’historique.
Vous savez immédiatement quelle automatisation est en cause. Sur un serveur qui héberge aussi
autre chose — un mandataire, une base de données, un site — ce n’est pas un confort mais une
nécessité : sans plafond, une automatisation mal calibrée fait tomber le reste avec
elle.

La valeur à mettre : laissez environ un quart de la mémoire de la machine au système et
aux autres services. Sur un serveur de deux gigaoctets dédié à n8n, un plafond d’un
gigaoctet et demi est un bon point de départ. Si vous voyez apparaître des échecs pour dépassement
de mémoire, la question à se poser n’est pas « comment lever le plafond » mais
« pourquoi cette automatisation charge-t-elle autant de données d’un coup » — traiter
par lots règle presque toujours le problème sans toucher au serveur.

Sauvegarder le volume, concrètement

Tout ce qui précède ne sert à rien sans cette section. Un serveur se perd : erreur de
manipulation, incident chez l’hébergeur, mise à jour qui tourne mal. Ce qui décide de la gravité,
c’est uniquement l’existence d’une copie ailleurs.

La bonne nouvelle est que la sauvegarde est simple, parce que tout tient dans un seul
endroit : le volume. Pas de base à exporter séparément, pas de fichiers dispersés. Copier ce
dossier, c’est copier votre installation complète.

Trois précautions, toutes apprises à la dure. La première : arrêtez le conteneur
avant de copier, ou copiez à un moment de faible activité. Sauvegarder une base pendant
qu’elle écrit peut produire un fichier corrompu — qui se copiera très bien et ne se restaurera
pas. Quelques secondes d’arrêt suffisent.

La deuxième : la copie doit partir de la machine. Une sauvegarde sur le
même serveur ne protège que de l’erreur humaine, pas de la perte du serveur. Un espace de
stockage distant, même minuscule, suffit : on parle de quelques dizaines de mégaoctets.

La troisième, et c’est celle que personne n’applique : testez une restauration
une fois. Montez une instance vide ailleurs, remettez-y votre copie, vérifiez que vos
automatisations et vos identifiants sont là. Une sauvegarde jamais restaurée n’est pas une
sauvegarde, c’est une intention. Le test prend vingt minutes et se fait une seule fois — il
révèle presque toujours quelque chose, le plus souvent la clé de chiffrement qu’on avait oublié
de noter.

Mettre à jour proprement

C’est l’opération que Docker rend simple, à condition de la faire dans l’ordre. Cinq étapes,
dont une que presque tout le monde saute.

La première étape est la sauvegarde du volume, et c’est celle qu’on néglige parce que les
mises à jour se passent bien quatre-vingt-dix-neuf fois sur cent. Elle existe pour la
centième. Sans elle, une montée de version qui modifie le format des données ne se retire
plus : revenir à l’ancienne image ne suffit pas si les données ont déjà été
converties.

La cinquième étape est la vérification, et elle ne consiste pas à regarder si l’interface
s’affiche. Déclenchez une automatisation réelle, celle qui compte le plus pour vous, et
regardez son résultat. Une interface qui s’ouvre ne prouve rien : la panne la plus
fréquente après une mise à jour concerne un nœud particulier, pas l’application entière.

Deux habitudes qui font la différence : ne montez jamais de version un vendredi
après-midi, et lisez les notes de version avant, en cherchant les mentions de changement de
comportement. Cinq minutes de lecture évitent parfois une demi-journée.

Les erreurs les plus fréquentes

Voici celles que l’on rencontre réellement, avec ce qu’il faut regarder en premier plutôt qu’une explication théorique. Il s’agit ici des erreurs de l’installation elle-même ; pour une instance qui tourne et dont une automatisation échoue, voyez dépanner une exécution n8n.

Réflexe qui remplace la moitié de ce tableau : demandez à Docker de vous montrer les
journaux du conteneur. La cause y est écrite en clair dans la grande majorité des cas — un
port occupé, un dossier inaccessible, une variable mal orthographiée. On cherche pendant une
heure ce qui était affiché depuis le début.

FAQ — vos questions fréquentes

Faut-il vraiment Docker, ou une installation classique suffit-elle ?

Une installation classique fonctionne. Elle vous coûtera du temps au premier changement de
version de Node.js, et rendra toute migration pénible. Pour une machine que vous comptez
garder, Docker est le choix qui vous laisse tranquille — c’est aussi la méthode que la
documentation officielle privilégie.

Puis-je utiliser Docker sans fichier compose, avec une simple commande ?

Oui, et c’est même souvent ce que montrent les démonstrations rapides. Nous le déconseillons
dès que l’installation doit durer : la commande est longue, personne ne s’en souvient, et
elle n’est écrite nulle part. Le fichier joue le rôle de documentation de votre installation.
Six mois plus tard, il vous dira ce que vous aviez décidé.

Où sont mes données, exactement ?

Dans le volume, et nulle part ailleurs. Si vous l’avez déclaré comme un dossier de votre
serveur, elles sont dans ce dossier. Sinon, Docker peut vous indiquer l’emplacement qu’il a
choisi. C’est ce dossier, et lui seul, qu’il faut sauvegarder.

Que se passe-t-il si mon serveur redémarre ?

Avec la bonne politique de redémarrage déclarée dans le fichier, le conteneur repart tout
seul et vos automatisations reprennent. Sans elle, votre instance reste éteinte jusqu’à ce que
vous vous en aperceviez — souvent parce qu’une facture n’est pas partie. C’est une ligne, et
elle n’est pas optionnelle.

Comment revenir à la version précédente ?

Remettez l’ancien numéro de version dans le fichier et relancez. C’est immédiat, à une
réserve près : si la nouvelle version a converti vos données vers un nouveau format, le
retour en arrière ne suffit pas et il faut restaurer la sauvegarde. C’est exactement la raison
pour laquelle l’étape de sauvegarde vient en premier.

Puis-je faire tourner autre chose sur la même machine ?

Oui, c’est même l’usage courant : le mandataire, une base de données, parfois un outil
interne. Surveillez simplement la mémoire, et posez une limite sur le conteneur n8n pour
qu’une exécution trop gourmande ne fasse pas tomber le reste. Le dimensionnement est traité
dans quel VPS choisir pour n8n.

Le port 5678 doit-il rester ouvert ?

Non, dès qu’un mandataire est en place. Il ne doit plus être accessible que depuis la
machine elle-même. Laisser ce port ouvert sur internet expose votre interface en clair, et
c’est un défaut qu’on retrouve dans une grande partie des fichiers partagés en ligne.

Comment savoir quelle version je fais tourner ?

Elle est affichée en bas du menu de gauche dans l’interface, et Docker peut vous la donner
en listant les images présentes. Si votre fichier indique un numéro précis, la réponse est dans
le fichier — c’est précisément l’intérêt de ne pas suivre la dernière version en date.

Faut-il sortir les secrets dans un fichier séparé ?

Dès que le fichier de configuration part dans un dépôt de code, oui : la clé de
chiffrement et les mots de passe de base n’ont rien à y faire. Docker sait lire un fichier de
variables placé à côté, ce qui vous laisse partager la configuration sans les secrets. Pour une
instance unique qui ne quitte jamais le serveur, tout garder dans le même fichier reste
acceptable — à condition d’en avoir une copie ailleurs.

Faut-il une base PostgreSQL ?

Pas au démarrage. La base intégrée par défaut convient très bien et vous évite une pièce à
administrer. Vous basculerez le jour où vous constaterez des blocages d’écriture, ou si vous
passez à un fonctionnement à plusieurs exécutants.

En résumé

Un fichier de six blocs décrit toute votre installation : quelle image, comment elle
redémarre, par quelle porte on entre, quels réglages, et où sont les données. Fixez le numéro
de version plutôt que de suivre la dernière en date, définissez vous-même la clé de
chiffrement, posez les deux réglages de fuseau horaire, déclarez votre adresse publique, et
fermez le port dès qu’un mandataire est en place. Ces cinq décisions couvrent la quasi-totalité
des ennuis que l’on voit remonter.

La suite logique : mettre ce fichier en production derrière un certificat, ce que décrit installer n8n sur un VPS. Le jour où une seule instance ne suffit plus, ce même fichier s’étend à plusieurs processus : voyez le mode file d’attente. Et si vous n’avez pas
encore choisi la machine, commencez par quel VPS choisir pour
n8n.