Am Ende dieses Kurses läuft n8n stabil im Heimnetz auf Raspberry Pi OS Lite 64-bit – mit Persistenz, sauberem Docker-Compose-Setup, praxisnaher Fehlerbehebung und optionalem Python Task Runner (External Mode).

• Raspberry Pi (Pi 4 / 2 GB reicht für den Einstieg)
• Raspberry Pi OS Lite 64-bit
• SSH-Zugriff (Terminal)
• Internet für Docker-Installation & Images
• Browser im gleichen LAN

• ``docker-compose.yml`` (n8n + n8n-runners)
• ``.env.example`` (inkl. Pruning + Secure Cookie + Runner-Token)
• ``00-runbook.md`` (Start/Stop/Update/Backup)
• ``troubleshooting.md`` (EACCES, Key-Mismatch, Cookie-Warnung)

Lernziel: Sie verstehen den Aufbau: Docker + Compose + Persistenz + Zugriff im LAN.

• Was ist n8n, wofür wird es genutzt?
• Warum Docker Compose für Stabilität & Updates?
• Warum Persistenz (Bind-Mount) Pflicht ist

Lernziel: Sie kennen Ports und Datenpfade.

• Web-UI: ``5678``
• Task Broker: ``5679`` (für Runner)
• Datenpfad: ``/srv/docker/n8n/data`` → ``/home/node/.n8n``

Lernziel: Basis-Update, saubere Ausgangslage.

sudo apt update
sudo apt upgrade -y

Lernziel: Docker läuft, Compose ist verfügbar.

sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
 
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

Optional (ohne sudo arbeiten):

sudo usermod -aG docker $USER

Lernziel: Sie prüfen Docker/Compose.

docker --version
docker compose version
docker run --rm hello-world

Lernziel: Saubere Ordnerstruktur unter ``/srv/docker``.

sudo mkdir -p /srv/docker/n8n
sudo mkdir -p /srv/docker/n8n/data
sudo chown -R 1000:1000 /srv/docker/n8n/data
sudo chmod 700 /srv/docker/n8n/data

Lernziel: n8n läuft stabil, Logs bleiben klein, Cookies passen im LAN. Key erzeugen:

openssl rand -base64 32

Datei erstellen:

sudo nano /srv/docker/n8n/.env

Beispiel:

N8N_HOST=mcp.local
N8N_PORT=5678
N8N_PROTOCOL=http

# Session im LAN/HTTP
N8N_SECURE_COOKIE=false

# Verschlüsselung (einmalig setzen und behalten!)
N8N_ENCRYPTION_KEY=PASTE_DEINEN_KEY_HIER

GENERIC_TIMEZONE=Europe/Berlin
TZ=Europe/Berlin

# Execution-Logs klein halten (Pi freundlich)
EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=168
EXECUTIONS_DATA_PRUNE_MAX_COUNT=5000

Lernziel: n8n startet und ist erreichbar.

sudo nano /srv/docker/n8n/docker-compose.yml

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped

    ports:
      - "5678:5678"

    env_file:
      - .env

    volumes:
      - /srv/docker/n8n/data:/home/node/.n8n

    user: "1000:1000"

Start:

cd /srv/docker/n8n
docker compose up -d
docker compose logs -f n8n

Lernziel: Sie diagnostizieren systematisch.

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
docker logs --tail 80 n8n
sudo ss -tulpn | grep -E ':(5678|5679)\b' || true

Symptom: ``EACCES: permission denied, open '/home/node/.n8n/config'`` Ursache: Host-Ordner gehört nicht UID 1000 oder falsche Mounts.

Fix:

cd /srv/docker/n8n
docker compose down
sudo chown -R 1000:1000 /srv/docker/n8n/data
sudo chmod 700 /srv/docker/n8n/data
docker compose up -d
docker compose logs -f n8n

Symptom: Key in ``/home/node/.n8n/config`` passt nicht zu ``N8N_ENCRYPTION_KEY`` Regel: Einmal setzen – dann nicht mehr wechseln, außer geplant.

Key aus Config prüfen:

sudo cat /srv/docker/n8n/data/config

Option A (behalten): ``N8N_ENCRYPTION_KEY`` exakt anpassen. Option B (neu): ``/srv/docker/n8n/data`` leeren (Achtung: löscht n8n-Setup).

Lernziel: External Mode aktivieren. Token erzeugen:

openssl rand -base64 24

.env ergänzen:

# Task Runners (External Mode)
N8N_RUNNERS_ENABLED=true
N8N_RUNNERS_MODE=external
N8N_RUNNERS_AUTH_TOKEN=PASTE_DEINEN_RUNNER_TOKEN

# Broker muss für Runner erreichbar sein (nicht nur 127.0.0.1)
N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0

Lernziel: Runner startet als Sidecar und verbindet sich zum Broker.

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped

    ports:
      - "5678:5678"

    env_file:
      - .env

    volumes:
      - /srv/docker/n8n/data:/home/node/.n8n

    user: "1000:1000"

  n8n-runners:
    image: n8nio/runners:latest
    container_name: n8n-runners
    restart: unless-stopped
    depends_on:
      - n8n
    environment:
      - N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679
      - N8N_RUNNERS_AUTH_TOKEN=${N8N_RUNNERS_AUTH_TOKEN}

Neustart:

cd /srv/docker/n8n
docker compose up -d --force-recreate
docker compose logs -f n8n-runners

Lernziel: Python läuft im Workflow.

• Node: Code
• Sprache: Python
• Test:

import sys
return {"python_version": sys.version}

Lernziel: Sie bedienen n8n sicher im Alltag.

cd /srv/docker/n8n
 
# Start
docker compose up -d
 
# Stop
docker compose down
 
# Update (Images ziehen + neu erstellen)
docker compose pull
docker compose up -d --force-recreate
 
# Logs
docker compose logs -f n8n

• Pro-Modul: Reverse Proxy + HTTPS (Apache/Traefik)
• Backup-Modul: Pull-Backup (core.local zieht von mcp.local)
• CoreStack: n8n + Postgres + DokuWiki + Gitea + code-server + FileBrowser