From 897b1ccf3d567fd0a744e024e97c5d790d75e207 Mon Sep 17 00:00:00 2001 From: dschlueter Date: Wed, 6 May 2026 01:48:24 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=C3=BCberarbeiten=20und=20BEDI?= =?UTF-8?q?ENUNGSANLEITUNG.md=20hinzuf=C3=BCgen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- BEDIENUNGSANLEITUNG.md | 228 +++++++++++++++++++++++++++++++++++++++++ README.md | 123 ++++++---------------- 2 files changed, 259 insertions(+), 92 deletions(-) create mode 100644 BEDIENUNGSANLEITUNG.md diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md new file mode 100644 index 0000000..7e4bcbf --- /dev/null +++ b/BEDIENUNGSANLEITUNG.md @@ -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/.json` +3. Falls Credentials mitgeliefert: `bash scripts/import-credentials.sh .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` | diff --git a/README.md b/README.md index bfee11f..2013297 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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 @@ -14,127 +14,66 @@ Internet → n8n.linix.de:443 ← 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 ``` n8n_stack/ -├── compose/docker-compose.yml # Stack-Definition -├── .env # Secrets (600, nie committen!) -├── .env.example # Vorlage -├── scripts/ # Hilfsskripte (700) -├── data/ # Docker-Volumes (gitignoriert) -│ ├── n8n/ -│ ├── postgres/ -│ └── redis/ -├── backups/ # Backups, max. 2 (gitignoriert) -├── imports/workflows/ # Workflow-JSONs zum Importieren -├── imports/credentials/ # Credentials-Exporte (unverschlüsselt!) -├── local-files/ # Dateien für n8n-Container (/files) -└── docs/ # nginx-Configs, Runbooks +├── compose/docker-compose.yml # Stack-Definition +├── .env # Secrets (600, nie committen!) +├── .env.example # Vorlage +├── scripts/ # Hilfsskripte (700) +│ └── yunohost-hook-restore-n8n-proxy.sh # Hook-Vorlage für YunoHost +├── data/ # Docker-Volumes (gitignoriert) +├── backups/ # Backups, max. 2 (gitignoriert) +├── imports/workflows/ # Workflow-JSONs zum Importieren +├── imports/credentials/ # Credential-Exporte (unverschlüsselt!) +├── local-files/ # Dateien für n8n-Container (/files) +└── docs/ # nginx-Configs, Runbooks ``` -## Start / Stop / Status +## Schnellstart ```bash -# Start +# Stack starten docker compose -f compose/docker-compose.yml up -d -# Stop -docker compose -f compose/docker-compose.yml down - -# Status +# Status prüfen docker compose -f compose/docker-compose.yml ps # Logs 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 - -```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/.json` -3. Falls Credentials mitgeliefert: `bash scripts/import-credentials.sh ` -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. +Ausführliche Bedienungsanleitung: [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md) ## Deployment auf neuem Host 1. Repo klonen 2. `.env.example` → `.env` kopieren, alle Werte ausfüllen 3. Neuen `N8N_ENCRYPTION_KEY` generieren: `openssl rand -base64 32` -4. `N8N_HOST` und `WEBHOOK_URL` auf die neue Domain anpassen -5. nginx-Config aus `docs/nginx-local-n8n.conf` anpassen und aktivieren -6. YunoHost-Config aus `docs/yunohost-nginx-n8n.conf` anpassen und installieren -7. `docker compose -f compose/docker-compose.yml up -d` +4. `N8N_HOST` und `WEBHOOK_URL` auf neue Domain anpassen +5. Lokale nginx-Config aus `docs/nginx-local-n8n.conf` aktivieren (Port 8088) +6. Auf YunoHost: `my_webapp` installieren, nginx-Config durch Proxy ersetzen (siehe `docs/yunohost-nginx-n8n.conf`) +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 -- **`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`). -- 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 | |---|---| | n8n Web-UI | https://n8n.linix.de | -| Erster Login | Beim ersten Aufruf Owner-Account anlegen | | Secrets-Datei | `./.env` (Rechte 600) | -| Backup-Verzeichnis | `./backups/` | | nginx lokal | `/etc/nginx/sites-available/n8n` (Port 8088) | -| YunoHost nginx | `/etc/nginx/conf.d/n8n.linix.de.conf` | - -## 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 +| 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` |