Installer n8n avec Docker Compose : guide complet

Pour installer n8n avec Docker Compose, créez un dossier dédié, stockez les secrets dans un fichier .env, lancez n8n avec PostgreSQL et conservez les données dans des volumes persistants. Ajoutez ensuite un reverse proxy HTTPS, verrouillez le port 5678 et testez un webhook avant de mettre l’instance en production. Cette méthode prend environ 30 minutes sur un VPS Ubuntu déjà équipé de Docker et évite de perdre vos workflows lors d’un redémarrage.

n8n est un outil d’automatisation visuelle qui relie des API, des bases de données et des services web. Docker Compose décrit les conteneurs, leur réseau, leurs variables et leurs volumes dans un seul fichier versionné. Vous obtenez ainsi une installation reproductible, plus simple à sauvegarder et à mettre à jour qu’un processus manuel.

Préparer le serveur avant l’installation de n8n

Prévoyez un VPS Linux récent avec au moins 2 Go de mémoire pour un usage personnel ou une petite équipe. Il vous faut un nom de domaine ou un sous-domaine qui pointe vers l’adresse IP du serveur, ainsi que les ports 80 et 443 ouverts pour le certificat TLS. Docker Engine et le plugin Docker Compose doivent être installés depuis les dépôts officiels de votre distribution.

Ne publiez pas directement l’interface n8n sur Internet avec le port 5678. Ce port sert au réseau interne et au proxy HTTPS. Avant de commencer, créez un utilisateur non administrateur, activez le pare-feu et appliquez les mises à jour de sécurité du système. Le compte qui exécute Docker doit être traité comme un compte privilégié.

# Vérifier les outils disponibles
 docker --version
 docker compose version

# Préparer le projet
 mkdir -p /opt/n8n
 cd /opt/n8n
 umask 077

Le dossier /opt/n8n n’est qu’un exemple. L’important est de choisir un emplacement documenté, sauvegardé et accessible à l’administrateur du serveur. N’ajoutez jamais le fichier .env dans un dépôt Git public.

Créer les secrets et la configuration d’environnement

La configuration doit séparer les valeurs publiques, comme le nom de domaine, des secrets, comme le mot de passe PostgreSQL et la clé de chiffrement n8n. La clé N8N_ENCRYPTION_KEY protège les identifiants enregistrés dans les workflows. Si vous la perdez, les credentials chiffrés ne pourront plus être déchiffrés après restauration.

# Générer deux secrets longs et aléatoires
 openssl rand -hex 32
 openssl rand -hex 32

# Créer le fichier protégé
 nano /opt/n8n/.env
 chmod 600 /opt/n8n/.env

Ajoutez ensuite ce contenu en remplaçant le domaine et les valeurs entre crochets. Le fuseau doit correspondre à celui des déclencheurs planifiés, pas seulement à celui de votre navigateur.

DOMAIN=n8n.exemple.fr
GENERIC_TIMEZONE=Europe/Brussels
POSTGRES_DB=n8n
POSTGRES_USER=n8n
POSTGRES_PASSWORD=remplacez_par_un_secret_long
N8N_ENCRYPTION_KEY=remplacez_par_une_cle_stable

La configuration officielle distingue TZ, qui influence l’environnement du conteneur, et GENERIC_TIMEZONE, utilisé notamment par les nœuds de planification. Définissez les deux pour éviter qu’un workflow parte à une heure inattendue.

Écrire le fichier Docker Compose pour n8n et PostgreSQL

Créez docker-compose.yml dans le même dossier. L’exemple ci-dessous utilise l’image officielle n8n, PostgreSQL pour la persistance principale et deux volumes nommés. Le nom de service postgres devient le nom d’hôte interne de la base, ce qui évite d’utiliser une adresse IP fragile.

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      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_HOST: ${DOMAIN}
      N8N_PROTOCOL: https
      N8N_PORT: 5678
      WEBHOOK_URL: https://${DOMAIN}/
      GENERIC_TIMEZONE: ${GENERIC_TIMEZONE}
      TZ: ${GENERIC_TIMEZONE}
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
      N8N_RUNNERS_ENABLED: "true"
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  n8n_data:
  postgres_data:

Le volume n8n_data conserve la configuration et les données locales n8n. PostgreSQL conserve les workflows, les exécutions et les paramètres de la base dans postgres_data. Le binding sur 127.0.0.1 empêche une connexion directe depuis Internet.

Évitez latest en production si vous devez maîtriser précisément les changements. Après un test sur une copie, remplacez cette étiquette par une version publiée et notez la version dans votre journal de maintenance.

Démarrer n8n avec Docker Compose et contrôler les logs

Depuis /opt/n8n, validez la configuration puis démarrez les services en arrière-plan. La commande config permet de repérer une variable absente ou une erreur YAML avant de créer les conteneurs.

cd /opt/n8n
 docker compose config
 docker compose pull
 docker compose up -d
 docker compose ps
 docker compose logs --tail=50 n8n

Le conteneur PostgreSQL doit passer son contrôle de santé avant que n8n ne démarre complètement. Ouvrez ensuite le domaine derrière votre proxy. Au premier accès, n8n demande la création du propriétaire de l’instance. Utilisez une adresse professionnelle protégée par un mot de passe unique et activez la double authentification dans votre profil.

Un test utile consiste à créer un workflow manuel avec un nœud Webhook, puis à envoyer une requête depuis un autre terminal. Vérifiez que l’URL de test et l’URL de production ne sont pas confondues. En production, le workflow doit être activé avant de tester son endpoint public.

# Vérifier la réponse locale du service
 curl -I http://127.0.0.1:5678/healthz

# Voir l’état détaillé des conteneurs
 docker compose ps
 docker compose logs --tail=100 postgres

Ajouter HTTPS avec un reverse proxy

n8n doit être servi sous HTTPS pour protéger la session, les credentials et les données transitant dans les webhooks. Un reverse proxy comme Nginx ou Caddy reçoit les requêtes sur 443, gère le certificat et transmet le trafic à 127.0.0.1:5678. Configurez également WEBHOOK_URL avec l’URL publique finale, sinon les services externes recevront une adresse locale ou en HTTP.

server {
    listen 80;
    server_name n8n.exemple.fr;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Demandez ensuite un certificat avec Certbot ou utilisez la gestion automatique de Caddy. Vérifiez que le renouvellement fonctionne avant de considérer l’installation terminée. Les webhooks doivent répondre en HTTPS, avec un certificat valide et un code HTTP cohérent.

Sauvegarder, mettre à jour et sécuriser l’instance

Une installation n8n n’est pas fiable tant qu’elle n’est pas restaurable. Sauvegardez PostgreSQL, le dossier Compose et le fichier .env dans un emplacement chiffré. Le fichier de secrets ne doit pas être envoyé sans protection dans un stockage partagé. Testez régulièrement une restauration sur un serveur temporaire, car une sauvegarde jamais restaurée n’est qu’une hypothèse.

# Export logique de la base dans un fichier local temporaire
 docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" > n8n-backup.sql

# Mise à jour contrôlée
 docker compose pull
 docker compose up -d
 docker compose logs --tail=100 n8n

Avant chaque mise à jour, lisez les notes de version n8n, copiez les volumes et conservez l’ancienne référence d’image. Ne lancez pas une mise à jour automatique sans fenêtre de retour arrière. Limitez aussi les exécutions conservées, protégez l’accès administrateur, mettez le pare-feu à jour et surveillez la consommation mémoire.

Si votre volume augmente fortement, séparez les exécutions réussies des erreurs et réduisez la durée de conservation adaptée à votre besoin. Pour les traitements lourds, prévoyez une architecture queue avec Redis et des workers dédiés, plutôt que de surcharger le conteneur principal.

Diagnostiquer les erreurs fréquentes après installation

Si n8n affiche une erreur de connexion à PostgreSQL, vérifiez d’abord le nom postgres, les identifiants du fichier .env et l’état du healthcheck. Si l’interface fonctionne mais qu’un webhook renvoie 404, contrôlez l’URL publique, le proxy, le chemin final et l’activation du workflow. Une erreur de fuseau vient généralement d’une valeur incohérente entre TZ et GENERIC_TIMEZONE.

# Inspecter les variables rendues sans afficher les secrets
 docker compose config | sed 's/POSTGRES_PASSWORD:.*/POSTGRES_PASSWORD: [masqué]/'

# Vérifier le réseau Compose
 docker compose exec n8n getent hosts postgres

# Contrôler les ports ouverts
 ss -lntp | grep -E ':80|:443|:5678'

Une boucle de redirection indique souvent que le proxy ne transmet pas X-Forwarded-Proto ou que N8N_PROTOCOL ne correspond pas à l’URL publique. Un écran vide après une mise à jour peut venir d’un cache navigateur, d’un volume non monté ou d’une version d’image incompatible. Revenez à la version précédente uniquement après avoir conservé les journaux.

Avant de confier des données sensibles à un workflow, définissez une règle de minimisation. Ne transmettez au nœud suivant que les champs nécessaires, masquez les secrets dans les journaux et séparez les identifiants par environnement. Un compte de service dédié permet aussi de révoquer un accès sans casser les connexions personnelles de l’équipe.

Documentez enfin le propriétaire de chaque workflow, sa fréquence, ses dépendances et son comportement en cas d’échec. Cette fiche réduit le temps de diagnostic et évite qu’une personne soit la seule à connaître la configuration. Pour une instance critique, ajoutez une alerte externe lorsque le conteneur s’arrête ou que le disque dépasse un seuil défini.

FAQ sur l’installation de n8n avec Docker Compose

Docker Compose est-il obligatoire pour installer n8n ?

Non, n8n peut fonctionner avec docker run ou avec n8n Cloud. Docker Compose est recommandé dès que vous utilisez PostgreSQL, car il décrit les services, les volumes et leur démarrage dans une configuration reproductible.

Quel serveur faut-il pour n8n ?

Un VPS Linux avec 2 Go de mémoire convient pour une petite instance et quelques workflows légers. La mémoire nécessaire augmente avec le nombre d’exécutions simultanées, les fichiers traités et les nœuds qui exécutent du code ou des modèles externes.

Où n8n stocke-t-il les workflows ?

Avec cette architecture, PostgreSQL stocke les données principales et le volume n8n_data conserve la configuration locale. Les deux volumes doivent être inclus dans votre stratégie de sauvegarde et de restauration.

Pourquoi un webhook n8n ne fonctionne-t-il pas après l’installation ?

Vérifiez que le workflow est actif, que WEBHOOK_URL contient le domaine HTTPS public et que le reverse proxy transmet les en-têtes et les connexions persistantes. Testez aussi l’URL de production depuis un réseau extérieur au VPS.

Comment mettre n8n à jour avec Docker Compose ?

Sauvegardez d’abord PostgreSQL et les volumes, lisez les notes de version, tirez l’image voulue avec docker compose pull, puis relancez avec docker compose up -d. Contrôlez les logs et gardez l’ancienne version disponible pour un retour arrière.

Sources et documentation

1. Documentation n8n sur l’installation Docker
2. Dépôt n8n Hosting avec Docker Compose et PostgreSQL
3. Documentation officielle Docker Compose
4. Image n8n sur Docker Hub
5. Documentation PostgreSQL sur les sauvegardes
6. Instructions Certbot pour HTTPS

Pour choisir l’outil adapté à votre contexte, comparez aussi n8n et Make, puis notre comparatif Zapier, Make et n8n. Si votre automatisation cible un site WordPress, le guide sur WordPress avec Docker et Nginx complète la partie déploiement.

Pour résoudre une intégration bloquée, consultez aussi notre diagnostic n8n webhook ne fonctionne pas avec les tests curl, le proxy et les variables d’environnement.