Die wichtigsten Umgebungsvariablen erklärt (N8N_HOST, WEBHOOK_URL, GENERIC_TIMEZONE ...)

Wer n8n selbst hostet, konfiguriert Erreichbarkeit, Zeitzone, Datenbank und Sicherheit nicht über die Oberfläche. Diese Einstellungen kommen aus Umgebungsvariablen, die beim Start des Containers oder Prozesses gesetzt werden.

Von den über hundert dokumentierten Variablen entscheiden nur rund fünfzehn über einen stabilen Betrieb. Dieser Artikel ordnet sie nach Themenbereich, nennt die Standardwerte aus der n8n-Dokumentation und zeigt lauffähige Beispiele.

So setzen Sie Umgebungsvariablen in n8n

Umgebungsvariablen setzen Sie dort, wo n8n startet: bei Docker über das -e-Flag oder den environment:-Block der Compose-Datei, bei einer npm-Installation über export vor dem Start.

Ein Minimalstart für ein deutsches Setup sieht so aus:

1docker run -it --rm \
2  --name n8n \
3  -p 5678:5678 \
4  -e GENERIC_TIMEZONE="Europe/Berlin" \
5  -e N8N_EDITOR_BASE_URL="https://n8n.ihrefirma.de" \
6  -e N8N_DEFAULT_LOCALE="de" \
7  -v n8n_data:/home/node/.n8n \
8  n8nio/n8n:2.36.9
Copy

Der Image-Tag ist bewusst fest gesetzt. Ein Betrieb auf latest bedeutet, dass ein beliebiger Neustart die Version wechselt.

Für Geheimnisse gibt es einen zweiten Weg. An fast jede Variable lässt sich _FILE anhängen, dann liest n8n den Wert aus der angegebenen Datei. Damit funktionieren Docker- und Kubernetes-Secrets, ohne dass Passwörter in der Compose-Datei stehen.

Grundkonfiguration: Erreichbarkeit, URL und Zeitzone

Diese sieben Variablen legen fest, unter welcher Adresse n8n erreichbar ist und in welcher Zeitzone zeitgesteuerte Workflows auslösen.

Variable | Standardwert | Bedeutung | Beispielwert

Variable: N8N_HOST · Standardwert: localhost · Bedeutung: Hostname, unter dem n8n läuft · Beispielwert: n8n.ihrefirma.de

Variable: N8N_PORT · Standardwert: 5678 · Bedeutung: HTTP-Port des Prozesses · Beispielwert: 5678

Variable: N8N_PROTOCOL · Standardwert: http · Bedeutung: Protokoll, über das n8n erreicht wird · Beispielwert: http hinter TLS-Proxy

Variable: N8N_EDITOR_BASE_URL · Standardwert: leer · Bedeutung: Öffentliche Editor-URL, auch für E-Mails und SAML-Rücksprung · Beispielwert: https://n8n.ihrefirma.de

Variable: N8N_WEBHOOK_URL · Standardwert: leer · Bedeutung: Basis-URL für Test- und Produktiv-Webhooks hinter einem Proxy · Beispielwert: https://n8n.ihrefirma.de/

Variable: GENERIC_TIMEZONE · Standardwert: America/New_York · Bedeutung: Zeitzone der Instanz, maßgeblich für Schedule- und Cron-Knoten · Beispielwert: Europe/Berlin

Variable: N8N_PROXY_HOPS · Standardwert: 0 · Bedeutung: Anzahl der vorgelagerten Reverse Proxies · Beispielwert: 1

Der Standardwert von GENERIC_TIMEZONE passt zu keiner deutschen Installation. Ohne Anpassung laufen alle Zeitpläne in der Zeitzone New York.

Zusätzlich stellt N8N_DEFAULT_LOCALE die Oberflächensprache. Der Standard ist en, regionale Kennungen wie de-AT unterstützt n8n nicht.

WEBHOOK_URL oder N8N_WEBHOOK_URL: was gilt heute?

Seit n8n 2.35.0 heißt die Variable N8N_WEBHOOK_URL. Die alte Schreibweise WEBHOOK_URL funktioniert weiterhin als Alias, erzeugt beim Start aber eine Deprecation-Warnung im Log.

Variable | Status | Wirkung | Empfehlung

Variable: N8N_WEBHOOK_URL · Status: aktuell · Wirkung: Setzt die vollständige Basis-URL für Produktiv- und Test-Webhooks · Empfehlung: Für neue Installationen verwenden

Variable: WEBHOOK_URL · Status: veraltet seit 2.35.0 · Wirkung: Alias auf N8N_WEBHOOK_URL, warnt beim Start · Empfehlung: Bei nächster Wartung umbenennen

Variable: N8N_ENDPOINT_WEBHOOK · Status: aktuell · Wirkung: Ändert nur den Pfad, Standard webhook, nicht die Domain · Empfehlung: Nur bei Pfadkonflikten anfassen

Wichtig ist der Unterschied in der Wirkung. N8N_ENDPOINT_WEBHOOK ersetzt ausschließlich das Pfadsegment, nicht die öffentliche Adresse.

Sicherheit und Datenschutz

Fünf Variablen entscheiden darüber, wie gut Zugangsdaten und Sitzungen einer selbst gehosteten Instanz geschützt sind.

Variable | Standardwert | Wirkung

Variable: N8N_ENCRYPTION_KEY · Standardwert: zufällig generiert · Wirkung: Schlüssel für die Verschlüsselung der Zugangsdaten in der Datenbank

Variable: N8N_SECURE_COOKIE · Standardwert: true · Wirkung: Cookies werden nur über HTTPS gesendet

Variable: N8N_SAMESITE_COOKIE · Standardwert: lax · Wirkung: Steuert das Cookie-Verhalten bei seitenübergreifenden Aufrufen

Variable: N8N_BLOCK_ENV_ACCESS_IN_NODE · Standardwert: false · Wirkung: Auf true blockiert n8n den Zugriff auf Server-Umgebungsvariablen aus Expressions und Code-Knoten

Variable: N8N_DIAGNOSTICS_ENABLED · Standardwert: true · Wirkung: Steuert das Senden anonymisierter Telemetrie an n8n

Setzen Sie N8N_ENCRYPTION_KEY in produktiven Umgebungen immer fest. Ohne festen Schlüssel erzeugt n8n beim ersten Start einen zufälligen Wert und legt ihn im .n8n-Ordner ab.

Für Mehrbenutzer-Instanzen empfiehlt sich N8N_BLOCK_ENV_ACCESS_IN_NODE=true. Sonst kann jeder Nutzer mit Editor-Zugriff die Server-Umgebung auslesen.

Datenbank und Betrieb

Für den produktiven Betrieb wechseln die meisten Installationen von SQLite auf PostgreSQL, konfiguriert über eigene Variablen. MySQL und MariaDB unterstützt n8n seit Version 1.0 nicht mehr.

Variable | Standardwert | Bedeutung

Variable: DB_TYPE · Standardwert: sqlite · Bedeutung: Datenbanktyp, gültig sind sqlite und postgresdb

Variable: DB_POSTGRESDB_HOST · Standardwert: localhost · Bedeutung: Hostname des PostgreSQL-Servers

Variable: DB_POSTGRESDB_PORT · Standardwert: 5432 · Bedeutung: Port des PostgreSQL-Servers

Variable: DB_POSTGRESDB_DATABASE · Standardwert: n8n · Bedeutung: Name der Datenbank

Variable: DB_POSTGRESDB_USER · Standardwert: postgres · Bedeutung: Datenbankbenutzer

Variable: DB_POSTGRESDB_PASSWORD · Standardwert: leer · Bedeutung: Passwort, besser über DB_POSTGRESDB_PASSWORD_FILE

Variable: DB_POSTGRESDB_SCHEMA · Standardwert: public · Bedeutung: Schema innerhalb der Datenbank

Variable: DB_POSTGRESDB_POOL_SIZE · Standardwert: 2 · Bedeutung: Anzahl paralleler Verbindungen zur Datenbank

Ein vollständiges Compose-Beispiel mit Postgres und persistentem Volume:

1volumes:
2  n8n_data:
3  db_data:
4
5services:
6  postgres:
7    image: postgres:16.4
8    environment:
9      POSTGRES_DB: n8n
10      POSTGRES_USER: n8n
11      POSTGRES_PASSWORD: bitte-ersetzen
12    volumes:
13      - db_data:/var/lib/postgresql/data
14
15  n8n:
16    image: n8nio/n8n:2.36.9
17    depends_on:
18      - postgres
19    ports:
20      - "127.0.0.1:5678:5678"
21    environment:
22      DB_TYPE: postgresdb
23      DB_POSTGRESDB_HOST: postgres
24      DB_POSTGRESDB_PORT: "5432"
25      DB_POSTGRESDB_DATABASE: n8n
26      DB_POSTGRESDB_USER: n8n
27      DB_POSTGRESDB_PASSWORD: bitte-ersetzen
28      N8N_ENCRYPTION_KEY: bitte-ersetzen
29      N8N_HOST: n8n.ihrefirma.de
30      N8N_PROTOCOL: http
31      N8N_EDITOR_BASE_URL: https://n8n.ihrefirma.de
32      N8N_WEBHOOK_URL: https://n8n.ihrefirma.de/
33      N8N_PROXY_HOPS: "1"
34      GENERIC_TIMEZONE: Europe/Berlin
35    volumes:
36      - n8n_data:/home/node/.n8n
Copy

Der Port ist absichtlich an 127.0.0.1 gebunden. Nach außen spricht nur der Reverse Proxy, der die TLS-Terminierung übernimmt.

Ausführungsdaten begrenzen

n8n räumt alte Ausführungsdaten von sich aus auf, die Grenzwerte lassen sich aber anpassen. Wer nichts setzt, behält vierzehn Tage Historie und maximal zehntausend Ausführungen.

Variable | Standardwert | Bedeutung

Variable: EXECUTIONS_DATA_PRUNE · Standardwert: true · Bedeutung: Löscht Daten vergangener Ausführungen fortlaufend

Variable: EXECUTIONS_DATA_MAX_AGE · Standardwert: 336 · Bedeutung: Alter in Stunden, ab dem eine Ausführung gelöscht wird

Variable: EXECUTIONS_DATA_PRUNE_MAX_COUNT · Standardwert: 10000 · Bedeutung: Höchstzahl gespeicherter Ausführungen, 0 hebt die Grenze auf

Bei Instanzen mit vielen Durchläufen wächst die Datenbank sonst spürbar. Ein niedrigerer Wert für EXECUTIONS_DATA_MAX_AGE hält sie klein.

Typische Fehler und Ursachen

Die folgenden fünf Störungen lassen sich jeweils auf eine einzelne Umgebungsvariable zurückführen. Jeder Eintrag nennt Ursache, Lösung und die Fundstelle in der n8n-Dokumentation.

Zeitgesteuerte Workflows starten zur falschen Uhrzeit. Ursache ist der Standardwert America/New_York in GENERIC_TIMEZONE. Lösung: auf Europe/Berlin setzen und n8n neu starten. Quelle: Timezone and localization.

Der Editor zeigt Webhook-URLs mit `localhost:5678`. Ursache ist ein Reverse Proxy ohne gesetzte Basis-URL. Lösung: N8N_WEBHOOK_URL und N8N_EDITOR_BASE_URL auf die öffentliche Domain setzen. Quelle: Endpoints.

Nach einem Container-Neuaufbau lassen sich Zugangsdaten nicht mehr entschlüsseln. Ursache ist ein zufällig erzeugter Schlüssel ohne persistenten Speicher. Lösung: N8N_ENCRYPTION_KEY fest setzen und /home/node/.n8n als Volume einbinden. Quelle: Deployment.

In den Logs erscheint immer die IP des Proxys. Ursache ist N8N_PROXY_HOPS mit dem Standardwert 0. Lösung: auf die Anzahl der vorgelagerten Proxies setzen, bei einem einzelnen Nginx oder Traefik auf 1. Quelle: Deployment.

Ask AI im Code-Knoten lässt sich nicht aktivieren. Ursache ist N8N_DIAGNOSTICS_ENABLED=false, das die Funktion mit abschaltet. Lösung: bewusst entscheiden, ob Telemetrie oder Ask AI wichtiger ist. Quelle: Deployment.

Die meisten Probleme beim n8n-Self-Hosting entstehen nicht durch fehlende Variablen, sondern durch falsch gesetzte URLs und eine unpassende Zeitzone. Wer die eigene Instanz einrichten, absichern oder auf Postgres umziehen lassen möchte, findet bei den n8n-Leistungen von NordFlux Unterstützung bei Aufbau und Konfiguration. Passend dazu: n8n mit Docker Compose selbst hosten und n8n hinter Caddy oder Nginx per HTTPS betreiben.

Häufige Fragen zu n8n-Umgebungsvariablen

Wo setze ich Umgebungsvariablen bei n8n?

Das hängt von der Installationsart ab. Bei Docker über -e-Flags oder den environment:-Block der Compose-Datei, bei einer npm-Installation über export vor dem Start des Prozesses.

Was passiert, wenn ich N8N_ENCRYPTION_KEY nicht setze?

n8n erzeugt beim ersten Start einen zufälligen Schlüssel und legt ihn im .n8n-Ordner ab. Geht dieser Ordner verloren, lassen sich gespeicherte Zugangsdaten nicht mehr entschlüsseln.

Muss ich N8N_WEBHOOK_URL immer setzen?

Nur wenn n8n hinter einem Reverse Proxy oder unter einer anderen öffentlichen Adresse läuft. Bei direktem Zugriff über N8N_HOST und N8N_PORT ist die Variable nicht nötig.

Kann ich Umgebungsvariablen nachträglich ändern?

Ja, die meisten Werte wirken nach einem Neustart des n8n-Prozesses. Laufende Workflows und gespeicherte Daten bleiben unberührt, solange die Datenbankverbindung gleich bleibt.

Wie halte ich Passwörter aus der Compose-Datei heraus?

Hängen Sie _FILE an den Variablennamen an, etwa DB_POSTGRESDB_PASSWORD_FILE. n8n liest den Wert dann aus der angegebenen Datei, was Docker- und Kubernetes-Secrets ermöglicht.

Weitere Details zu allen dokumentierten Variablen finden sich in der n8n-Dokumentation zu Umgebungsvariablen sowie speziell zur Datenbankkonfiguration.