docs: add setup guide for Beastix server and client installation

2026-04-02 00:01:05 +02:00
parent 52ba53bec4
commit 80ce1aa77c
1 changed files with 151 additions and 0 deletions
@@ -0,0 +1,151 @@
+# tüit Transkriptor — Setup-Anleitung
+
+## Architektur
+
+```
+┌─────────────────────────┐         ┌──────────────────────────────┐
+│  Client (Linux)         │         │  Beastix (LAN-Server)        │
+│                         │   WAV   │                              │
+│  Transkriptor-App       │ ──────► │  faster-whisper-server :8000 │
+│  Browser-UI :8765       │  Text   │  Ollama :11434               │
+│                         │ ◄────── │                              │
+└─────────────────────────┘         └──────────────────────────────┘
+```
+
+Jeder Client läuft komplett unabhängig. Die KI-Verarbeitung (Whisper + Ollama) kann
+entweder lokal oder auf Beastix ausgeführt werden — konfigurierbar über die
+Einstellungsseite.
+
+---
+
+## Beastix (Server-Setup, einmalig)
+
+### 1. faster-whisper-server installieren
+
+```bash
+sudo pacman -S python-pipx   # Arch Linux
+pipx install faster-whisper-server
+pipx ensurepath
+```
+
+**Bekannter Bug in Version 0.0.2** — fehlende `pyproject.toml` im pipx-venv:
+
+```bash
+cat > ~/.local/share/pipx/venvs/faster-whisper-server/lib/python*/site-packages/pyproject.toml << 'EOF'
+[project]
+name = "faster-whisper-server"
+version = "0.0.2"
+EOF
+```
+
+### 2. Als systemd-User-Service einrichten
+
+```bash
+cat > ~/.config/systemd/user/faster-whisper-server.service << 'EOF'
+[Unit]
+Description=faster-whisper-server (OpenAI-compatible Whisper API)
+After=network.target
+
+[Service]
+ExecStart=%h/.local/bin/faster-whisper-server --host 0.0.0.0 --port 8000 --model large-v3
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now faster-whisper-server.service
+```
+
+### 3. Ollama installieren (falls noch nicht vorhanden)
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+ollama pull gemma3:12b
+```
+
+### 4. Firewall — Ports freigeben (LAN-intern)
+
+```bash
+# Whisper-Server
+sudo ufw allow from 192.168.0.0/16 to any port 8000
+# Ollama
+sudo ufw allow from 192.168.0.0/16 to any port 11434
+```
+
+Ports nur für LAN freigeben — nicht ins Internet exponieren.
+
+---
+
+## Client-Setup (jeder Linux-Rechner)
+
+### 1. Transkriptor installieren
+
+```bash
+git clone git@git.tueit.de:tueit_GmbH/tueit_Transkriptor.git
+cd tueit_Transkriptor
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+### 2. App starten
+
+```bash
+.venv/bin/python main.py
+```
+
+Beim ersten Start: Browser öffnet sich automatisch (oder manuell: http://localhost:8765).
+Einmal Admin-Account anlegen, dann einloggen.
+
+### 3. Beastix konfigurieren (Einstellungen → ⚙)
+
+Als Admin einloggen → Zahnrad-Icon im Header → Einstellungen:
+
+| Feld | Wert (Beispiel) |
+|------|-----------------|
+| Whisper Server URL | `http://beastix:8000` |
+| Whisper Modell | `large-v3` |
+| Ollama Server URL | `http://beastix:11434` |
+| Ollama Modell | `gemma3:12b` (aus Dropdown wählen) |
+
+Leer lassen = lokale Verarbeitung (benötigt lokales Whisper-Modell).
+
+### 4. Als systemd-User-Service einrichten (optional)
+
+```bash
+cat > ~/.config/systemd/user/tueit-transcriber.service << 'EOF'
+[Unit]
+Description=tüit Transkriptor
+After=network.target
+
+[Service]
+WorkingDirectory=%h/work/tueit_Transkriptor
+ExecStart=%h/work/tueit_Transkriptor/.venv/bin/python main.py
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now tueit-transcriber.service
+```
+
+---
+
+## Audio — PipeWire Combined Source
+
+Um Mikrofon + System-Audio gleichzeitig aufzunehmen (z.B. für Konferenzen):
+
+Einstellungen → Audio → **Combined Source erstellen**
+
+- Mikrofon auswählen
+- System-Audio Monitor auswählen (z.B. `alsa_output.*.monitor`)
+- Erstellen → neues Device `transkriptor-combined.monitor` erscheint in der Liste
+- Als Aufnahmequelle auswählen und speichern
+
+Die PipeWire-Module werden in `~/.config/tueit-transcriber/pipewire-modules.json`
+gespeichert. Bei App-Stop können sie mit `pactl unload-module <id>` entladen werden.