dschlueter/n8n_stack
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: README überarbeiten und BEDIENUNGSANLEITUNG.md hinzufügen

Browse source 
README auf wesentliche Infos gestrafft, Link zur Bedienungsanleitung.
BEDIENUNGSANLEITUNG deckt täglichen Betrieb, Update, Backup, Import/Export,
User-Management und Troubleshooting ab.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Dieter Schlüter 2026-05-06 01:48:24 +02:00
commit 897b1ccf3d
2 changed files with 259 additions and 92 deletions
Download patch file Download diff file Expand all files Collapse all files

228
BEDIENUNGSANLEITUNG.md Normal file
View file

@ -0,0 +1,228 @@
# Bedienungsanleitung n8n Stack
Alle Befehle werden im Verzeichnis `/home/dschlueter/nvme2n1p7_home/n8n_stack` ausgeführt.
---
## Täglicher Betrieb
### Stack starten / stoppen
```bash
# Starten
docker compose -f compose/docker-compose.yml up -d
# Stoppen (Container bleiben erhalten, Daten bleiben)
docker compose -f compose/docker-compose.yml down
# Stoppen + Volumes löschen (VORSICHT: löscht alle Daten!)
docker compose -f compose/docker-compose.yml down -v
```
### Status und Logs
```bash
# Alle Container und ihr Status
docker compose -f compose/docker-compose.yml ps
# Live-Logs n8n (Ctrl+C zum Beenden)
docker compose -f compose/docker-compose.yml logs -f n8n
# Logs Worker
docker compose -f compose/docker-compose.yml logs -f n8n-worker
# Logs aller Services
docker compose -f compose/docker-compose.yml logs -f
```
### Worker skalieren
```bash
# Auf 2 Worker hochskalieren
docker compose -f compose/docker-compose.yml up -d --scale n8n-worker=2
# Zurück auf 1
docker compose -f compose/docker-compose.yml up -d --scale n8n-worker=1
```
---
## Update
```bash
bash scripts/update-n8n.sh
```
Das Script führt automatisch folgende Schritte aus:
1. Backup erstellen
2. Neue Docker-Images ziehen
3. Stack neu starten
4. Status ausgeben
---
## Backup und Restore
### Backup erstellen
```bash
bash scripts/backup-n8n.sh
```
Erstellt einen Snapshot in `backups/backup_YYYYMMDD_HHMMSS/`. Es werden maximal 2 Backups aufbewahrt — das älteste wird automatisch gelöscht.
### Restore
```bash
bash scripts/restore-n8n.sh backups/backup_20240101_120000
```
**Achtung:** Der Stack wird dabei gestoppt, Daten werden überschrieben.
---
## Workflows
### Workflow importieren
```bash
# Einzelne Datei
bash scripts/import-workflow.sh imports/workflows/mein-workflow.json
# Ganzes Verzeichnis
bash scripts/import-workflow.sh imports/workflows/
```
### Alle Workflows exportieren
```bash
bash scripts/export-workflows.sh
```
Exportiert alle Workflows als JSON-Dateien nach `imports/workflows/`.
### Fremde n8n-Projekte übernehmen
1. Workflow-JSON-Dateien nach `imports/workflows/` kopieren
2. Importieren: `bash scripts/import-workflow.sh imports/workflows/<datei>.json`
3. Falls Credentials mitgeliefert: `bash scripts/import-credentials.sh <datei>.json`
4. In der n8n-UI: Credentials der importierten Workflows prüfen und neu verknüpfen
Bei Voll-Exporten (`.zip`): entpacken, dann Verzeichnis übergeben.
---
## Credentials
### Credentials importieren
```bash
bash scripts/import-credentials.sh imports/credentials/creds.json
```
### Credentials exportieren
```bash
bash scripts/export-credentials.sh
```
**Wichtig:** Der Export enthält alle Secrets im **Klartext**. Die Export-Datei nach Gebrauch sofort löschen und niemals committen oder weitergeben.
---
## User-Management
User werden in der n8n-Web-UI verwaltet: **Settings → Users**
- **Einladen:** E-Mail-Adresse eingeben → Einladungsmail wird automatisch verschickt
- **Einladungslink öffnen:** Im **privaten/Inkognito-Fenster** öffnen, nicht im eingeloggten Browser
- **Rollen:** Owner (vollen Zugriff), Member (eingeschränkt)
---
## Konfiguration ändern
Alle Einstellungen stehen in `.env`. Nach Änderungen n8n neu starten:
```bash
# Nur n8n-Container neu starten (z.B. nach SMTP-Änderung)
docker compose -f compose/docker-compose.yml up -d n8n
# Alle Container neu starten
docker compose -f compose/docker-compose.yml up -d
```
Wichtige Variablen in `.env`:
| Variable | Bedeutung |
|---|---|
| `N8N_HOST` | Domain (z.B. `n8n.linix.de`) |
| `N8N_ENCRYPTION_KEY` | **Nie ändern nach erstem Start!** |
| `SMTP_HOST` / `SMTP_USER` / `SMTP_PASSWORD` | E-Mail-Versand |
| `TZ` | Zeitzone (Standard: `Europe/Berlin`) |
---
## Dateien im n8n-Container bereitstellen
Dateien, die n8n-Workflows lesen oder schreiben sollen, in `local-files/` ablegen. Im Container sind sie unter `/files/` erreichbar.
---
## Troubleshooting
### Stack startet nicht
```bash
# Logs prüfen
docker compose -f compose/docker-compose.yml logs --tail=50
# Einzelnen Service prüfen
docker compose -f compose/docker-compose.yml logs postgres
docker compose -f compose/docker-compose.yml logs redis
```
### n8n nicht erreichbar (https://n8n.linix.de)
```bash
# Lokaler Proxy-Check
curl -I http://127.0.0.1:5678/healthz
# YunoHost-nginx prüfen (auf YunoHost)
sudo nginx -t
sudo systemctl status nginx
```
### YunoHost: nginx-Proxy nach my_webapp-Upgrade weg
```bash
# Hook manuell ausführen (auf YunoHost)
sudo bash /etc/yunohost/hooks.d/post_app_upgrade/99-n8n-proxy
```
### Datenbank-Shell
```bash
docker compose -f compose/docker-compose.yml exec postgres psql -U n8n -d n8n
```
### Redis-Shell
```bash
docker compose -f compose/docker-compose.yml exec redis redis-cli -a "$REDIS_PASSWORD"
```
---
## Wichtige Pfade
| Was | Pfad |
|---|---|
| Stack-Konfiguration | `compose/docker-compose.yml` |
| Secrets | `.env` (Rechte 600, nie committen) |
| n8n-Daten | `data/n8n/` |
| PostgreSQL-Daten | `data/postgres/` |
| Backups | `backups/` |
| Lokale nginx-Config | `/etc/nginx/sites-available/n8n` |
| YunoHost nginx-Config | `/etc/nginx/conf.d/n8n.linix.de.d/my_webapp.conf` |
| YunoHost Upgrade-Hook | `/etc/yunohost/hooks.d/post_app_upgrade/99-n8n-proxy` |

105
README.md
View file

@ -1,6 +1,6 @@
# n8n Stack # n8n Stack
Produktionsnaher n8n-Stack auf Docker Compose mit PostgreSQL, Redis und Queue-Mode. Produktionsnaher n8n-Stack auf Docker Compose mit PostgreSQL 16, Redis 7 und Queue-Mode.
## Architektur ## Architektur
@ -14,6 +14,10 @@ Internet → n8n.linix.de:443
← n8n-worker (n8n-stack-n8n-worker-1) ← n8n-worker (n8n-stack-n8n-worker-1)
``` ```
YunoHost-SSOwat-Bypass: `my_webapp` als registrierter Platzhalter, nginx-Proxy-Block in
`/etc/nginx/conf.d/n8n.linix.de.d/my_webapp.conf` (wird durch Hook `99-n8n-proxy`
nach Upgrades automatisch wiederhergestellt).
## Verzeichnisstruktur ## Verzeichnisstruktur
``` ```
@ -22,119 +26,54 @@ n8n_stack/
├── .env # Secrets (600, nie committen!) ├── .env # Secrets (600, nie committen!)
├── .env.example # Vorlage ├── .env.example # Vorlage
├── scripts/ # Hilfsskripte (700) ├── scripts/ # Hilfsskripte (700)
│ └── yunohost-hook-restore-n8n-proxy.sh # Hook-Vorlage für YunoHost
├── data/ # Docker-Volumes (gitignoriert) ├── data/ # Docker-Volumes (gitignoriert)
│ ├── n8n/
│ ├── postgres/
│ └── redis/
├── backups/ # Backups, max. 2 (gitignoriert) ├── backups/ # Backups, max. 2 (gitignoriert)
├── imports/workflows/ # Workflow-JSONs zum Importieren ├── imports/workflows/ # Workflow-JSONs zum Importieren
├── imports/credentials/ # Credentials-Exporte (unverschlüsselt!) ├── imports/credentials/ # Credential-Exporte (unverschlüsselt!)
├── local-files/ # Dateien für n8n-Container (/files) ├── local-files/ # Dateien für n8n-Container (/files)
└── docs/ # nginx-Configs, Runbooks └── docs/ # nginx-Configs, Runbooks
``` ```
## Start / Stop / Status ## Schnellstart
```bash ```bash
# Start # Stack starten
docker compose -f compose/docker-compose.yml up -d docker compose -f compose/docker-compose.yml up -d
# Stop # Status prüfen
docker compose -f compose/docker-compose.yml down
# Status
docker compose -f compose/docker-compose.yml ps docker compose -f compose/docker-compose.yml ps
# Logs # Logs
docker compose -f compose/docker-compose.yml logs -f n8n docker compose -f compose/docker-compose.yml logs -f n8n
# Worker skalieren (z.B. auf 2)
docker compose -f compose/docker-compose.yml up -d --scale n8n-worker=2
``` ```
## Update Ausführliche Bedienungsanleitung: [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md)
```bash
bash scripts/update-n8n.sh
```
Führt automatisch ein Backup aus, zieht neue Images und startet den Stack neu.
## Backup / Restore
```bash
# Backup erstellen (behält immer die letzten 2)
bash scripts/backup-n8n.sh
# Restore aus Backup-Verzeichnis
bash scripts/restore-n8n.sh backups/backup_20240101_120000
```
## Import / Export von Workflows
```bash
# Einzelne Workflow-JSON importieren
bash scripts/import-workflow.sh imports/workflows/mein-workflow.json
# Ganzes Verzeichnis importieren
bash scripts/import-workflow.sh imports/workflows/
# Alle Workflows exportieren
bash scripts/export-workflows.sh
```
## Import / Export von Credentials
```bash
# Credentials importieren
bash scripts/import-credentials.sh imports/credentials/creds.json
# Credentials exportieren (UNVERSCHLÜSSELT — sicher aufbewahren!)
bash scripts/export-credentials.sh
```
**Wichtig:** Credential-Exporte enthalten alle Secrets im Klartext. Export-Dateien nach Gebrauch löschen.
## Übernahme fremder n8n-Projekte
1. Workflow-JSON-Dateien nach `imports/workflows/` kopieren
2. `bash scripts/import-workflow.sh imports/workflows/<datei>.json`
3. Falls Credentials mitgeliefert: `bash scripts/import-credentials.sh <datei.json>`
4. In der n8n-UI: Credentials der importierten Workflows prüfen und neu verknüpfen
Bei Voll-Exporten (`.zip` mit mehreren JSONs): entpacken, dann Verzeichnis übergeben.
## Deployment auf neuem Host ## Deployment auf neuem Host
1. Repo klonen 1. Repo klonen
2. `.env.example` → `.env` kopieren, alle Werte ausfüllen 2. `.env.example` → `.env` kopieren, alle Werte ausfüllen
3. Neuen `N8N_ENCRYPTION_KEY` generieren: `openssl rand -base64 32` 3. Neuen `N8N_ENCRYPTION_KEY` generieren: `openssl rand -base64 32`
4. `N8N_HOST` und `WEBHOOK_URL` auf die neue Domain anpassen 4. `N8N_HOST` und `WEBHOOK_URL` auf neue Domain anpassen
5. nginx-Config aus `docs/nginx-local-n8n.conf` anpassen und aktivieren 5. Lokale nginx-Config aus `docs/nginx-local-n8n.conf` aktivieren (Port 8088)
6. YunoHost-Config aus `docs/yunohost-nginx-n8n.conf` anpassen und installieren 6. Auf YunoHost: `my_webapp` installieren, nginx-Config durch Proxy ersetzen (siehe `docs/yunohost-nginx-n8n.conf`)
7. `docker compose -f compose/docker-compose.yml up -d` 7. YunoHost-Hook deployen: `scripts/yunohost-hook-restore-n8n-proxy.sh` → `/etc/yunohost/hooks.d/post_app_upgrade/99-n8n-proxy`
8. `docker compose -f compose/docker-compose.yml up -d`
## Kritische Hinweise ## Kritische Hinweise
- **`N8N_ENCRYPTION_KEY`** darf nach dem ersten Start **nie geändert** werden — eine Änderung macht alle gespeicherten Credentials unbrauchbar. Key steht in `.env`. - **`N8N_ENCRYPTION_KEY`** darf nach dem ersten Start **nie geändert** werden — macht alle gespeicherten Credentials unbrauchbar.
- **`.env`** nie committen (steht in `.gitignore`). - **`.env`** nie committen (steht in `.gitignore`).
- Backup vor jedem Update läuft automatisch via `update-n8n.sh`. - Credential-Exporte enthalten Secrets im **Klartext** — nach Gebrauch löschen.
- Backup läuft automatisch vor jedem Update via `update-n8n.sh`.
## URLs und Zugangspfade ## URLs
| Was | Wert | | Was | Wert |
|---|---| |---|---|
| n8n Web-UI | https://n8n.linix.de | | n8n Web-UI | https://n8n.linix.de |
| Erster Login | Beim ersten Aufruf Owner-Account anlegen |
| Secrets-Datei | `./.env` (Rechte 600) | | Secrets-Datei | `./.env` (Rechte 600) |
| Backup-Verzeichnis | `./backups/` |
| nginx lokal | `/etc/nginx/sites-available/n8n` (Port 8088) | | nginx lokal | `/etc/nginx/sites-available/n8n` (Port 8088) |
| YunoHost nginx | `/etc/nginx/conf.d/n8n.linix.de.conf` | | YunoHost nginx | `/etc/nginx/conf.d/n8n.linix.de.d/my_webapp.conf` |
| YunoHost Hook | `/etc/yunohost/hooks.d/post_app_upgrade/99-n8n-proxy` |
## Setup-Status
- [x] DNS: `n8n.linix.de` → `92.50.108.218`
- [x] YunoHost: Domain + Let's Encrypt
- [x] YunoHost: `my_webapp` als SSOwat-Shim installiert, nginx-Proxy auf 192.168.179.124:8088
- [x] SMTP-Credentials in `.env` eingetragen
- [x] Owner-Account angelegt