Kapitel 13/Tutorial.md aktualisiert

Kapitel 13/Tutorial.md

@@ -53,39 +53,180 @@ Damit ist das Fundament gelegt.
 
 ---
 
+## Abschnitt 2 – Clipper‑LXC einrichten (Benutzer, Verzeichnisse, Pakete, Skripte)
+
+In diesem Abschnitt richten wir den **Clipper‑Container** so ein, dass **SSH‑Schlüssel**, **Downloads** und **n8n‑Aufrufe** ohne Berechtigungsfehler funktionieren. Wir arbeiten jetzt **im Terminal deines Clipper‑LXC als root**.
+
+> **Entscheidung & Begründung – Benutzer mit Home & Bash**  
+> Der Benutzer **clipper** bekommt ein **Homeverzeichnis** (`/home/clipper`) und eine **Login‑Shell**. So können SSH‑Schlüssel sauber in `~clipper/.ssh` landen und n8n später per SSH Befehle ausführen. Varianten ohne Home (System‑User) führen bei `ssh-copy-id` zu Fehlern.
+
+### 2.1 Benutzer und Verzeichnisse anlegen (Terminal, als root)
+
+```bash
+adduser --home /home/clipper --shell /bin/bash clipper
+```
+Vergib ein Passwort und bestätige die Abfragen. Danach legst du die Arbeitsordner an und überträgst den Besitz an `clipper`:
+```bash
+mkdir -p /srv/clipper/{inbox,watch,out,temp,logs,bin}
+chown -R clipper:clipper /srv/clipper
+chmod 750 /srv/clipper
+```
+(optional, aber hilfreich für `ssh-copy-id` später):
+```bash
+install -d -m 700 -o clipper -g clipper /home/clipper/.ssh
+```
+
+> **Falls du den Benutzer bereits ohne Home angelegt hast:**  
+> Richte ihn so nach:  
+> `mkdir -p /home/clipper/.ssh && chown -R clipper:clipper /home/clipper && chmod 700 /home/clipper/.ssh`
+
+### 2.2 Pakete installieren (Terminal, als root)
+
+```bash
+apt update && apt install -y ffmpeg yt-dlp jq python3 python3-venv curl unzip inotify-tools sudo
+```
+- **ffmpeg**: Analyse & Schnitt  
+- **yt-dlp**: Twitch‑VOD/Clip‑Downloads (HLS)  
+- **jq**: JSON‑Handling  
+- **python3/venv**: spätere Analyse‑Tools  
+- **inotify-tools**: Dateisystem‑Events (optional)  
+- **sudo**: für gezielte Rechteerhöhungen falls nötig
+
+### 2.3 Zentrale Konfiguration (Terminal, als root)
+
+Lege eine Umgebungsdatei an, die beide Skripte laden:
+```bash
+nano /etc/clipper/clipper.env
+```
+Inhalt:
+```
+CLIPPER_INBOX=/srv/clipper/inbox
+CLIPPER_IN=/srv/clipper/watch
+CLIPPER_OUT=/srv/clipper/out
+CLIPPER_TMP=/srv/clipper/temp
+CLIPPER_LOG=/srv/clipper/logs/clipper.log
+```
+Dateirechte setzen, damit `clipper` sie lesen darf:
+```bash
+chown root:clipper /etc/clipper/clipper.env
+chmod 640 /etc/clipper/clipper.env
+```
+
+### 2.4 Python‑Umgebung vorbereiten (Wechsel zu Benutzer *clipper*)
+
+Wechsle jetzt **zum Benutzer clipper**:
+```bash
+su - clipper
+```
+Erzeuge und fülle eine virtuelle Umgebung für die spätere Analyse:
+```bash
+python3 -m venv /srv/clipper/.venv
+source /srv/clipper/.venv/bin/activate
+pip install --upgrade pip
+pip install numpy opencv-python-headless
+deactivate
+```
+Wechsle für die nächsten Schritte **im Benutzer clipper** weiter.
+
+### 2.5 Einstiegsskripte erstellen (im Benutzer *clipper*)
+
+**Analyse‑Stub** – prüft Eingaben, schreibt Logs, erzeugt leere Kandidatenliste:
+```bash
+nano /srv/clipper/bin/clipper-analyze
+```
+Inhalt:
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+ENV_FILE="/etc/clipper/clipper.env"; [ -r "$ENV_FILE" ] || { echo "ENV nicht lesbar: $ENV_FILE" >&2; exit 1; }; source "$ENV_FILE"
+IN="$1"       # absolute Datei
+JOBID="${2:-manual}"
+mkdir -p "$CLIPPER_TMP/$JOBID"
+echo "$(date '+%F %T') [ANALYZE] job=$JOBID file=$IN" | tee -a "$CLIPPER_LOG"
+OUT_JSON="$CLIPPER_TMP/$JOBID/candidates.json"
+echo '[]' > "$OUT_JSON"
+echo "$OUT_JSON"
+```
+
+**Schneid‑Stub** – protokolliert Schnittaufrufe, echte Logik folgt in Abschnitt 5:
+```bash
+nano /srv/clipper/bin/clipper-cut
+```
+Inhalt:
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+ENV_FILE="/etc/clipper/clipper.env"; [ -r "$ENV_FILE" ] || { echo "ENV nicht lesbar: $ENV_FILE" >&2; exit 1; }; source "$ENV_FILE"
+IN="$1"            # absolute Datei
+RANGES_JSON="$2"   # Zeitbereiche (kommt später aus Abschnitt 4)
+JOBID="${3:-manual}"
+mkdir -p "$CLIPPER_OUT/$JOBID"
+echo "$(date '+%F %T') [CUT] job=$JOBID file=$IN ranges=$RANGES_JSON" | tee -a "$CLIPPER_LOG"
+exit 0
+```
+
+Rechte setzen und Eigentümer korrigieren:
+```bash
+chmod +x /srv/clipper/bin/clipper-*
+chown -R clipper:clipper /srv/clipper/bin
+```
+
+### 2.6 Logrotation (zurück zu root)
+
+Beende die Session (`exit`) und kehre zu **root** zurück. Richte Logrotation ein:
+```bash
+nano /etc/logrotate.d/clipper
+```
+Inhalt:
+```
+/srv/clipper/logs/*.log {
+  rotate 14
+  daily
+  missingok
+  notifempty
+  compress
+  delaycompress
+  copytruncate
+}
+```
+
+> **Schnelltest (optional):**  
+> Zurück im **Benutzer clipper**:  
+> `/srv/clipper/bin/clipper-analyze /srv/clipper/watch/demo.mp4 job-001`  
+> `/srv/clipper/bin/clipper-cut /srv/clipper/watch/demo.mp4 /srv/clipper/temp/job-001/ranges.json job-001`  
+> `tail -n 50 /srv/clipper/logs/clipper.log`
+
+Mit dieser Einrichtung sind **SSH‑Schlüssel**, **Berechtigungen** und **Pfade** konsistent. `ssh-copy-id` aus Abschnitt 3 funktioniert dadurch ohne Fehlermeldungen – und n8n kann die Skripte stabil starten.
+
 ## Abschnitt 2 – Clipper-LXC einrichten (Basisdienste & Einstiegsskripte)
 
-Jetzt richten wir Clipper so ein, dass er klare Einstiegspunkte zum **Analysieren** und **Schneiden** hat. Die eigentliche Logik füllen wir in Abschnitt 4 und 5, hier bauen wir das Gerüst.
+Damit der Benutzer `clipper` sauber funktioniert, legen wir ihn **immer mit Home-Verzeichnis und Shell** an. So können wir später SSH-Schlüssel ohne Fehler hinterlegen.
 
 ### Benutzer und Verzeichnisse
 
-Zuerst legen wir den Service-Benutzer an und weisen ihm die Arbeitsordner zu:
+Als root:
+```bash
+adduser --home /home/clipper --shell /bin/bash clipper
+```
+Vergib ein Passwort und bestätige die Abfragen. Danach richte das Konfigurationsverzeichnis ein:
 ```bash
-adduser clipper
 mkdir -p /etc/clipper
 chown root:clipper /etc/clipper
 chmod 750 /etc/clipper
 ```
 
 ### Pakete installieren
-
 ```bash
 apt install -y ffmpeg jq python3 python3-venv curl unzip inotify-tools sudo
 ```
-- **ffmpeg** für Analyse und Schnitt
-- **jq** für JSON-Verarbeitung
-- **python3/venv** für optionale Analyse-Tools (z. B. Szenenerkennung, Face-Detection)
-- **inotify-tools** für Dateisystem-Events
-- **sudo** damit der Benutzer clipper bei Bedarf Rechte anheben kann
 
-Anschließend geben wir dem Benutzer clipper Sudo-Rechte:
+- **ffmpeg**: Kern für Analyse/Schnitt  
-```bash
+- **jq**: JSON-Auswertung  
-usermod -aG sudo clipper
+- **python3/venv**: Virtuelle Umgebung für Analyse  
-```
+- **inotify-tools**: Events  
+- **sudo**: für Rechteeskalation
 
 ### Konfiguration anlegen
-
-Wir legen eine Konfigurationsdatei an, die von allen Skripten geladen wird:
 ```bash
 nano /etc/clipper/clipper.env
 ```
@@ -96,11 +237,14 @@ CLIPPER_OUT=/srv/clipper/out
 CLIPPER_TMP=/srv/clipper/temp
 CLIPPER_LOG=/srv/clipper/logs/clipper.log
 ```
-Datei speichern und mit `chown root:clipper /etc/clipper/clipper.env && chmod 640 /etc/clipper/clipper.env` die Rechte setzen.
+
+Rechte setzen:
+```bash
+chown root:clipper /etc/clipper/clipper.env
+chmod 640 /etc/clipper/clipper.env
+```
 
 ### Python-Umgebung vorbereiten
-
-Die eigentliche Analyse binden wir erst in Abschnitt 4 ein. Damit die Basis steht, richten wir jetzt schon eine virtuelle Umgebung ein:
 ```bash
 su - clipper
 python3 -m venv /srv/clipper/.venv
@@ -109,17 +253,11 @@ pip install --upgrade pip
 pip install numpy opencv-python-headless
 ```
 
-So haben wir erste Bibliotheken, mit denen Szenen- und Gesichtserkennung später möglich wird.
+### Einstiegsskripte erstellen
-
+**Analyse-Stub:**
-### Einstiegsskripte (Stubs)
-
-Wir erstellen zwei Einstiegspunkte, die n8n direkt aufruft. Sie tun noch nichts außer Logging und Validierung.
-
-**Analyse-Stub**
 ```bash
 nano /srv/clipper/bin/clipper-analyze
 ```
-Inhalt:
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
@@ -133,11 +271,10 @@ echo '[]' > "$OUT_JSON"
 echo "$OUT_JSON"
 ```
 
-**Schneid-Stub**
+**Schneid-Stub:**
 ```bash
 nano /srv/clipper/bin/clipper-cut
 ```
-Inhalt:
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
@@ -156,25 +293,10 @@ chmod +x /srv/clipper/bin/clipper-*
 chown -R clipper:clipper /srv/clipper/bin
 ```
 
-### Direktaufruf und Tests
+### Logs und Rotation
-
-Wir verzichten bewusst auf systemd-Templates und rufen die Skripte direkt über n8n oder manuell auf. Beispiel:
-```bash
-su - clipper
-/srv/clipper/bin/clipper-analyze /srv/clipper/watch/demo.mp4 job-001
-/srv/clipper/bin/clipper-cut /srv/clipper/watch/demo.mp4 /srv/clipper/temp/job-001/ranges.json job-001
-
-tail -n 50 /srv/clipper/logs/clipper.log
-```
-Wenn alles passt, siehst du Einträge `[ANALYZE]` und `[CUT]` mit deiner Job-ID.
-
-### Logrotation
-
-Zum Schluss sorgen wir dafür, dass Logs nicht unendlich wachsen:
 ```bash
 nano /etc/logrotate.d/clipper
 ```
-Inhalt:
 ```
 /srv/clipper/logs/*.log {
   rotate 14
@@ -189,9 +311,6 @@ Inhalt:
 
 ---
 
-Damit ist der Clipper-LXC vorbereitet: Benutzer, Verzeichnisse, Pakete, Konfiguration und Einstiegsskripte sind eingerichtet. In den nächsten Abschnitten bauen wir die Anbindung an Twitch/n8n, implementieren die Analyse-Logik (inklusive Facecam, Hochformat und Untertitel) und fügen den eigentlichen Schnitt hinzu, bevor alles sauber in Nextcloud abgelegt wird.
-
-
 ## Abschnitt 3 – n8n ↔ Twitch: VOD & Clips importieren, in Nextcloud ablegen, Clipper starten
 
 In diesem Abschnitt verbinden wir n8n mit Twitch, Nextcloud und dem Clipper. Das Ziel: n8n erkennt automatisch neue VODs auf Twitch, lädt sie zusammen mit Clips herunter, legt sie in Nextcloud ab und startet dann die Analyse auf dem Clipper. Wir gehen Schritt für Schritt vor – immer mit klaren Hinweisen, ob wir uns gerade in der **n8n‑Weboberfläche**, im **Terminal** oder in **Nextcloud** befinden.