n8n_stack/BEDIENUNGSANLEITUNG.md

# 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` |