Installer n8n : les trois méthodes, et laquelle choisir

Installer n8n demande surtout d'éviter les recettes devenues fausses. Cette page couvre l'essai avec npx, le script local officiel et une installation Docker Compose sur VPS avec PostgreSQL, Caddy et un runner externe.

Les corrections comptent autant que les commandes. WEBHOOK_URL est déprécié au profit de N8N_WEBHOOK_URL. N8N_RUNNERS_ENABLED ne sert plus depuis n8n 2.0. L'installation npm sera dépréciée à partir de n8n 3.0, et l'ancien exemple docker run est désormais signalé comme périmé par la documentation n8n.

Trois façons d'installer n8n, et pour qui

Choisissez npx pour découvrir l'éditeur, le script officiel pour un laboratoire local avec bac à sable, et Docker Compose sur VPS pour une instance durable. La longueur d'une commande ne dit rien de son aptitude à la production.

n8n reste d'abord un automatisateur. Il exécute un workflow que vous avez dessiné, avec des déclencheurs et des étapes explicites. Un agent comme Hermes choisit plus librement ses actions et ses outils. Si votre besoin est déterministe, n8n est souvent plus lisible. Si le chemin doit être décidé pendant l'exécution, un agent correspond mieux, avec moins de prévisibilité.

Essayer n8n en cinq minutes avec npx

npx n8n ouvre directement l'éditeur sur votre ordinateur. Utilisez cette commande pour construire un premier workflow, pas pour faire tourner une automatisation permanente.

npx n8n

La commande télécharge ce qui est nécessaire, puis rend n8n accessible sur http://localhost:5678. Votre version de Node.js doit être comprise entre 20.19 et 24.x, bornes incluses. La documentation npm officielle documente encore npm install n8n -g pour une installation globale, mais cette variante ne constitue plus un choix durable.

Cette méthode reste utile pour vérifier l'interface, créer un credential sans valeur sensible et lancer un workflow manuel. Elle devient un mauvais choix dès que le workflow doit survivre à la fermeture du terminal, recevoir des webhooks publics ou être restauré après une panne.

L'installation en une ligne

Le script officiel installe une pile locale plus complète sans vous faire écrire les fichiers Compose. Il exige Docker en marche, le plugin Docker Compose v2 et un terminal capable d'exécuter un script shell.

docker compose version

curl -fsSL https://get.n8n.io | sh -s -- --version 2.35.0

Sous Windows, exécutez cette commande dans WSL, pas dans l'invite de commandes ni dans PowerShell. La page officielle de l'installation en une ligne sert actuellement la version 2.35.0 lorsque vous la demandez explicitement.

• L'éditeur n8n écoute sur http://localhost:5678.
• SQLite conserve les workflows, les credentials et l'historique d'exécution dans le volume n8n-data.
• Des services séparés fournissent l'exécution de code en bac à sable et la recherche web de l'Assistant IA.
• Seul le port 5678 est publié. Les services de bac à sable ne sont pas joignables directement depuis l'extérieur.
• L'Assistant IA reste désactivé tant qu'aucune clé de fournisseur de modèle n'est configurée.

Le script crée notamment ./n8n/compose.yml, ./n8n/.env et ./n8n/searxng-settings.yml. Utilisez ses commandes documentées pour mettre la pile à niveau ou l'arrêter. L'arrêt conserve les données persistantes, mais ne transforme pas ce montage local en service de production.

curl -fsSL https://get.n8n.io | sh -s -- --upgrade

docker compose -f ./n8n/compose.yml down

Docker Compose sur un VPS : la voie de production

Une installation de production sépare n8n, PostgreSQL, Caddy et le runner de tâches tout en conservant leurs données dans des volumes nommés. Le Compose ci-dessous fusionne les architectures des deux exemples d'hébergement officiels n8n et corrige leur ancienne variable de webhook.

Prévoyez au moins 4 Go de RAM et 2 vCPU pour la configuration Compose documentée par n8n. Faites pointer le DNS du sous-domaine vers le VPS et rendez les ports 80 et 443 accessibles à Caddy. Sous Windows, gardez le projet dans le système de fichiers WSL, par exemple ~/n8n, jamais sous /mnt/c/. Les ressources d'hébergement du site peuvent vous aider à comparer les VPS, mais vous restez responsable de leur administration.

Créez un fichier .env à côté de compose.yml. Remplacez example.com et toutes les valeurs commençant par change avant le premier démarrage. La clé de chiffrement et le jeton du runner doivent être deux secrets distincts. Gardez .env hors du contrôle de version et limitez son accès.

N8N_VERSION=2.35.0
DOMAIN_NAME=example.com
SUBDOMAIN=n8n
GENERIC_TIMEZONE=Europe/Paris
POSTGRES_USER=changeUser
POSTGRES_PASSWORD=changePassword
POSTGRES_DB=n8n
RUNNERS_AUTH_TOKEN=changeRunnerAuthToken
N8N_ENCRYPTION_KEY=changeEncryptionKey

Enregistrez ensuite ce fichier sous compose.yml. Les images n8n et runner utilisent la même version. PostgreSQL attend son contrôle de santé avant le démarrage de n8n, et le port 5678 reste dans le réseau Compose au lieu de contourner Caddy.

volumes:
  caddy_data:
  caddy_config:
  db_storage:
  n8n_storage:

services:
  caddy:
    image: caddy:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - caddy_data:/data
      - caddy_config:/config
      - ./caddy_config:/etc/caddy:ro

  postgres:
    image: postgres:16
    restart: always
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - db_storage:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: docker.n8n.io/n8nio/n8n:${N8N_VERSION}
    restart: always
    environment:
      - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - N8N_WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/
      - N8N_PROXY_HOPS=1
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - TZ=${GENERIC_TIMEZONE}
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_RUNNERS_MODE=external
      - N8N_RUNNERS_AUTH_TOKEN=${RUNNERS_AUTH_TOKEN}
      - N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0
    volumes:
      - n8n_storage:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

  n8n-runner:
    image: n8nio/runners:${N8N_VERSION}
    restart: always
    environment:
      - N8N_RUNNERS_AUTH_TOKEN=${RUNNERS_AUTH_TOKEN}
      - N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679
    depends_on:
      - n8n

Créez le répertoire caddy_config, puis placez-y le fichier Caddyfile. Le montage du répertoire permet à Caddy de détecter un fichier remplacé lors d'un rechargement. Remplacez le domaine littéral par le vôtre. La syntaxe ${DOMAIN_NAME} de Compose n'est pas interpolée automatiquement dans un Caddyfile.

n8n.example.com {
  reverse_proxy n8n:5678 {
    flush_interval -1
  }
}

Ce motif Caddyfile officiel est valide. Le nom de domaine active le HTTPS automatique. n8n:5678 désigne le service dans le réseau Compose, tandis que localhost:5678 désignerait le conteneur Caddy lui-même. Démarrez ensuite la pile avec la commande documentée.

docker compose up -d

Le runner externe exécute le JavaScript et le Python du noeud Code hors du processus principal. N8N_RUNNERS_ENABLED ne doit pas réapparaître dans ce fichier. Cette ancienne variable est dépréciée depuis n8n 2.0. Elle ne remplace ni le mode external, ni le jeton partagé, ni l'URI du broker.

Deux limites restent visibles dans cet exemple autonome. caddy:latest, repris du dépôt n8n, est un tag mutable : épinglez la version Caddy que vous avez validée avant la mise en production. n8n réutilise aussi POSTGRES_USER, le compte d'initialisation privilégié de PostgreSQL. L'exemple officiel withPostgres sépare l'application avec POSTGRES_NON_ROOT_USER, POSTGRES_NON_ROOT_PASSWORD et un fichier init-data.sh. N'ajoutez pas ces deux variables sans ce script.

Les variables d'environnement qui comptent

Quelques variables déterminent l'adresse publique, le chiffrement, la base et l'exécution du code. Les définir au hasard produit souvent une interface accessible avec des workflows pourtant inutilisables.

RUNNERS_AUTH_TOKEN dans .env est seulement une variable de substitution utilisée par Compose. La variable réellement comprise par les deux conteneurs reste N8N_RUNNERS_AUTH_TOKEN. Ne donnez jamais deux valeurs différentes au service n8n et au runner.

HTTPS et reverse proxy : ce qui casse quand c'est mal fait

Le cas trompeur est une interface qui fonctionne en HTTPS tandis que les webhooks échouent. n8n écoute en interne sur 5678, mais les services externes doivent recevoir une URL publique en 443 sans ce port interne.

Définissez N8N_WEBHOOK_URL=https://n8n.example.com/ avec votre domaine et N8N_PROXY_HOPS=1. N'utilisez plus WEBHOOK_URL. Cette ancienne variable est dépréciée et n8n écrit désormais un avertissement lorsqu'elle est encore présente.

• X-Forwarded-For conserve l'information sur le client d'origine.
• X-Forwarded-Host transmet le domaine public demandé.
• X-Forwarded-Proto transmet le protocole public https.

Caddy définit ces trois en-têtes par défaut avec reverse_proxy. Le Caddyfile précédent n'a donc pas besoin de directives header_up ajoutées de mémoire. Si l'éditeur affiche encore localhost ou :5678 dans une URL de production, corrigez la configuration avant d'activer le workflow. Un service tiers ne peut pas appeler une adresse interne à votre VPS.

La clé de chiffrement, la seule chose à ne jamais perdre

n8n génère une clé aléatoire au premier démarrage et l'écrit dans ~/.n8n, sauf si vous fournissez N8N_ENCRYPTION_KEY. Cette clé chiffre les credentials avant leur stockage en base.

Fixez votre valeur avant le premier docker compose up -d. Ne remplacez pas ensuite la clé pour nettoyer votre fichier .env. En mode file d'attente, le processus principal et tous les workers doivent partager exactement la même valeur. Le conteneur de task runner externe n'est pas un worker de file d'attente et ne reçoit pas cette clé dans le Compose présenté ici.

Sauvegarder : ce qu'il faut copier et où

Une sauvegarde n8n cohérente réunit la base, les fichiers persistants et la clé qui permet de déchiffrer les credentials. Copier uniquement PostgreSQL donne l'apparence d'une sauvegarde sans garantir une restauration utilisable.

• Sauvegardez PostgreSQL avec un dump cohérent ou un instantané pris lorsque le service est arrêté. Une copie brute de db_storage pendant les écritures peut être incohérente.
• Sauvegardez n8n_storage, monté sur /home/node/.n8n. Ce dossier reste nécessaire avec PostgreSQL pour la clé, les journaux d'instance et les fichiers du contrôle de source.
• Conservez séparément la valeur exacte de N8N_ENCRYPTION_KEY. Elle ne doit pas dépendre de la seule copie du serveur.

Le volume caddy_data contient les certificats et les clés gérés par Caddy. Il ne déchiffre pas les credentials n8n, mais sa sauvegarde facilite une reprise complète du proxy. Testez la restauration de la base, du volume n8n et de la clé ensemble. Le simple succès d'une copie de fichiers ne prouve pas que les credentials se rouvrent.

Mettre à jour et revenir en arrière

Épinglez une version, lisez ses notes de version et sauvegardez avant de la changer. Une mise à jour n8n peut inclure une migration de base qui rend un retour par simple changement d'image insuffisant.

Dans le Compose présenté, modifiez N8N_VERSION dans .env vers la version choisie. Les images n8n et runner suivront ensemble. Exécutez ensuite la séquence officielle depuis le dossier du projet.

docker compose pull
docker compose down
docker compose up -d

Pour un conteneur Docker simple, la documentation montre aussi le tirage d'une version précise. Le tag évite qu'une reconstruction ultérieure télécharge silencieusement une autre version.

docker pull docker.n8n.io/n8nio/n8n:2.35.0

Pour revenir, arrêtez la pile, remettez l'ancienne valeur de N8N_VERSION, restaurez ensemble la base, le volume n8n et la clé d'avant mise à jour, puis redémarrez. La méthode exacte dépend de votre sauvegarde PostgreSQL. Une procédure générique risquerait d'écraser la bonne base ou de restaurer un état incompatible.

Ce que l'édition communautaire ne fait pas

L'édition communautaire gratuite contient presque tout n8n et inclut le mode file d'attente. Elle ne comprend pas certaines fonctions de gouvernance, de stockage et de haute disponibilité.

• Les variables personnalisées et les environnements.
• Les secrets externes et le stockage externe des données binaires.
• La diffusion des journaux vers un système tiers.
• Le mode multi-main, même si le mode file d'attente reste inclus.
• Les projets et le partage des workflows ou des credentials entre utilisateurs.
• L'authentification unique SAML et LDAP.
• Le contrôle de version par Git.

Toutes les installations auto-hébergées utilisent le même produit sous-jacent. L'enregistrement gratuit de l'édition communautaire débloque les dossiers, les outils de débogage dans l'éditeur et les données d'exécution personnalisées. Il ne débloque pas les fonctions de la liste précédente.

Les Agent Skills ne remplacent pas ces fonctions. Ils structurent les instructions et les capacités réutilisables d'un agent, tandis que les limites ci-dessus concernent les droits, le partage et l'exploitation de l'instance n8n.

Résoudre les problèmes fréquents

Commencez par le symptôme observable plutôt que par une réinstallation. Les cinq pannes suivantes viennent généralement d'une URL publique, d'un secret, d'un volume ou d'un fuseau mal aligné.

Les webhooks pointent vers localhost ou vers le port 5678

Vérifiez N8N_WEBHOOK_URL avec l'adresse HTTPS complète, puis N8N_PROXY_HOPS=1. Confirmez que Caddy reçoit le domaine public et transmet X-Forwarded-For, X-Forwarded-Host et X-Forwarded-Proto. Retirez WEBHOOK_URL au lieu de conserver les deux variables. Une URL correcte dans le navigateur ne corrige pas un webhook déjà enregistré avec la mauvaise adresse.

Mes credentials sont illisibles après une restauration

La base restaurée n'est pas associée à sa clé d'origine. Rétablissez la valeur exacte de N8N_ENCRYPTION_KEY ou le fichier de configuration provenant du bon volume /home/node/.n8n. Redémarrer avec une nouvelle clé ne déchiffre pas les anciennes données. Si la clé d'origine est perdue, les credentials concernés doivent être recréés.

Le conteneur redémarre en boucle

Contrôlez d'abord que le volume monté sur /home/node/.n8n reste accessible à l'utilisateur du conteneur. N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true demande à n8n de resserrer les permissions de son fichier de réglages, mais ne répare pas à lui seul une propriété incorrecte de tout le volume. Une boucle après restauration indique souvent que les fichiers ont repris de mauvais droits ou un mauvais propriétaire.

Les exécutions planifiées partent à la mauvaise heure

Ne confondez pas TZ et GENERIC_TIMEZONE. TZ règle le fuseau du système utilisé par les scripts. GENERIC_TIMEZONE règle celui des noeuds de planification. Dans l'exemple, les deux reçoivent Europe/Paris pour éviter qu'un script et un déclencheur interprètent la même heure différemment.

L'interface répond mais un noeud de code échoue

L'éditeur et le runner sont deux services distincts. Vérifiez que les images n8n et n8nio/runners portent la même version, que le jeton N8N_RUNNERS_AUTH_TOKEN est identique, et que le runner utilise N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679. Côté n8n, le broker doit écouter sur 0.0.0.0. Une interface disponible prouve seulement que le service principal répond, pas que le runner s'est authentifié.