n8n zelfhosting met Docker

Dit bestand is door ToolBrain vertaald en inhoudelijk gewijzigd op 2026-08-30, op basis van n8n-self-hosting SKILL.md uit czlonkowski/n8n-skills (MIT), zie de bron_url hierboven en ../LICENSES/n8n-skills-MIT.txt.

Scope-opmerking: dit item vertaalt uitsluitend het overzichtsbestand SKILL.md van de oorspronkelijke skill. Dit is een overzicht op basis van het SKILL.md-bestand; de volledige installatiestappen (SINGLE_MODE, QUEUE_MODE, SECURITY, DAY2) staan alleen in de Engelstalige bronrepo, samen met de bijbehorende assets/-templates (Docker Compose-bestanden, Caddyfile, .env-voorbeelden). Gebruik dit bestand als beslissingskader en checklist, niet als zelfstandige, volledige installatiehandleiding.

Deze skill brengt een verse Linux-VM (Ubuntu/Debian, root- of sudo-SSH-toegang) naar een draaiende, HTTPS-beveiligde, productierijpe n8n-installatie via Docker Compose achter Caddy (automatische Let's Encrypt-TLS). Dit is voor zelfgehoste n8n op Docker — niet voor n8n Cloud, en niet voor het bouwen van workflows zelf.

Er zijn twee uitrolmodi. De architectuur verschilt fundamenteel, dus kies de modus vóórdat je iets doet.

Je stuurt dit end-to-end via SSH aan: preflight → Docker installeren → het project neerzetten → secrets genereren → opstarten → TLS verifiëren → overdragen.

Regel 0 — kies de modus (vraag het de gebruiker)

Gok het niet, vraag het en kies vervolgens definitief:

	Single / regulier	Queue
Processen	één n8n-proces	hoofdproces + N workers
Extra diensten	geen (SQLite)	Redis (queue) + Postgres (database)
Voert workflows uit	in het hoofdproces	op workers, parallel
Geschikt voor	1 gebruiker, lichte/gematigde belasting, eenvoudigste beheer	hoog volume, zware/lange executies, horizontale schaling

Bij twijfel: begin single — dat is de eenvoudigste correcte keuze en dekt de meeste behoeften. Later overstappen naar queue betekent het compose-bestand vervangen én SQLite naar Postgres migreren; verwacht je al écht volume, begin dan meteen met queue.

Regel 1 — secret-hygiëne (niet onderhandelbaar)

Een misstap hier lekt klantcredentials. Wees hier zorgvuldig in:

1. Genereer elk secret vers, op de doelmachine zelf. Kopieer nooit een encryptiesleutel, een databasewachtwoord, of een .env-bestand van een andere n8n-installatie naar deze.
2. Secrets leven alleen in .env (permissies 600), waar het compose-bestand ze als variabele uitleest. Zet nooit een secret rechtstreeks in docker-compose.yml, het Caddyfile, of iets wat je commit.
3. De encryptiesleutel is heilig. Die versleutelt elke opgeslagen credential. Gaat hij verloren of verandert hij, dan worden alle opgeslagen credentials onleesbaar. Zet hem expliciet, en vertel de gebruiker dat hij die buiten de machine zelf moet bewaren. Echo hem niet onnodig naar langlevende logs of chatgeschiedenis.
4. Stel nooit interne diensten bloot. Alleen Caddy (poorten 80/443) is publiek. n8n zelf, de database en de queue blijven op het private Docker-netwerk — de templates laten hun host- poortkoppeling bewust weg. Voeg die niet toe.
5. Het .env-bestand en het Caddy-certificatenvolume zijn geen artefacten om te delen. Werk je binnen een git-repo, bevestig dan dat .env in .gitignore staat vóór je commit.

Vooraf te verzamelen gegevens

• SSH-doel — gebruiker@host en hoe je authenticeert (sleutelpad, of bevestiging dat er al toegang is). Root of een sudo-gebruiker.
• Domein — de volledige hostnaam waar n8n op komt, bijvoorbeeld n8n.voorbeeld.nl. De gebruiker moet zeggenschap hebben over het DNS.
• TLS-e-mailadres — voor Let's Encrypt.
• Tijdzone — de IANA-naam voor Schedule/Cron-nodes (bijvoorbeeld Europe/Amsterdam), anders Etc/UTC.
• Modus — single of queue (zie Regel 0). Bij queue: bevestig dat de machine genoeg RAM heeft (vuistregel: minimaal ~4 GB, elke worker wil er ~1-2 GB bij).
• Optionele modules — sommige functies (op dit moment onder meer een Agents-module) staan standaard uit tenzij expliciet ingeschakeld. Vraag hier alleen naar als de gebruiker het zelf aankaart.

Het uitrolproces, stap voor stap

1. Preflight. SSH in, bevestig dat het een Debian/Ubuntu-achtig systeem is. Het DNS moet al naar de machine wijzen — vergelijk het publieke IP van de machine met wat het domein daadwerkelijk oplost (doe dit zowel vanaf de machine als vanaf je eigen laptop). Komen ze niet overeen, stop: Caddy's ACME-uitdaging zal falen. Laat de gebruiker het A-record aanmaken en wacht op propagatie. Controleer ook dat poorten 80 en 443 vanaf internet bereikbaar zijn — check zowel de host-firewall als een eventuele cloud-firewall (bijvoorbeeld een security group), want die laatste is een veelvoorkomende stille blokkade.
2. Docker installeren (indien afwezig) — controleer de Docker- en Compose-versie, installeer anders de Docker Engine plus de Compose-plugin, en verifieer opnieuw.
3. Het project neerzetten. Kies een absoluut pad voor de databasemap (bijvoorbeeld /opt/n8n) en gebruik exact datzelfde pad overal in .env — de compose mount daar submappen op basis van dit pad, dus draai docker compose altijd vanuit deze map. Zet de juiste templatebestanden (het gekozen compose-bestand, het Caddyfile, en bij queue-modus ook het database-initscript) op de juiste plek en onder de juiste naam neer.
4. .env invullen en secrets genereren. Vul domein, subdomein, e-mailadres en tijdzone in. Genereer elk secret op de machine zelf en zet het in .env op de plek van de placeholder: de encryptiesleutel altijd, en bij queue-modus ook de databasewachtwoorden. Controleer vóór het opstarten dat er geen placeholder is blijven staan — een vergeten placeholder wordt anders het letterlijke wachtwoord en de database/n8n kunnen dan niet verbinden. Zet de bestandspermissies van .env op 600 en noteer de encryptiesleutel zodat de gebruiker die apart kan bewaren.
5. Firewall. Sta alleen SSH, poort 80 en poort 443 toe; open nooit de interne database-/queue-/n8n-poorten naar buiten.
6. Opstarten. Start de compose-stack op. Bij queue-modus komen database, queue, hoofdproces en workers allemaal omhoog; extra workers kun je later bijschalen.
7. Verifiëren — verklaar pas succes na deze checks. Elke dienst moet draaien en gezond zijn. Controleer dat n8n intern al reageert vóórdat je concludeert dat er iets mis is met TLS — een nog niet uitgegeven certificaat (de eerste ACME-uitgifte kan een paar minuten duren) betekent niet dat n8n zelf niet draait. Controleer daarna de publieke bereikbaarheid met een paar retries. Bij queue-modus: vergelijk de omgevingsvariabelen van hoofdproces en worker — alleen de publieke-URL-/proxy-variabelen mogen verschillen; verschilt er iets anders, dan heeft een gedragsinstelling het hoofdproces wel bereikt maar de workers niet, en workers zijn wat de workflows daadwerkelijk uitvoert. Open tot slot de installatie-URL in de browser: wie als eerste het setup-formulier invult, claimt de instantie als eigenaar — dus maak dat account meteen aan, vóór je de URL deelt, en schakel tweestapsverificatie in.
8. Overdragen. Geef de gebruiker de URL, de locatie van het project, de encryptiesleutel om veilig te bewaren, en de basisprincipes voor bijwerken/back-uppen/herstellen.

Wat je niet moet doen

• De DNS-/poorten-preflight overslaan — een verkeerd A-record of een dichte cloud-firewall is verreweg de meest voorkomende reden dat Caddy geen certificaat krijgt en n8n "kapot" lijkt.
• De interne poorten publiceren naar de host — Caddy bereikt n8n al via het private netwerk.
• De encryptiesleutel of het .env-bestand van een andere installatie hergebruiken.
• Queue-modus draaien op SQLite — queue vereist Postgres.
• Secrets in docker-compose.yml of het Caddyfile zetten — uitsluitend in .env.
• Een gedragsinstelling alleen op het hoofdproces zetten in queue-modus zonder de workers mee te nemen.
• Blind de latest-image-tag gebruiken — pin een expliciete versie en werk bewust bij.

Praktijkvoorbeeld (NL)

Een Nederlands administratiekantoor met acht medewerkers wil de eigen documentverwerking automatiseren en kiest voor een zelfgehoste n8n-instantie op een Hetzner-VPS, in plaats van de cloudvariant, vanwege de gevoelige klantdata die door de workflows stroomt. Omdat het kantoor maar een handvol gelijktijdige workflows draait en geen zwaar volume verwacht, valt de keuze op de single-modus met SQLite in plaats van de zwaardere queue-opzet met aparte workers. Vóór de uitrol wordt eerst het DNS-record voor automatisering.hetkantoor.nl aangemaakt en gecontroleerd dat dit al naar het nieuwe IP-adres wijst, precies zoals de preflight-stap hierboven voorschrijft — zodat de TLS-uitgifte in één keer goed gaat en er geen tweede sessie nodig is om een gemiste DNS-wijziging recht te zetten.