dschlueter/open_notebook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
open_notebook/README.md
dschlueter 9e6d790830 Run containers as the host user instead of root 
Everything the containers wrote into the bind mounts (surreal_data, notebook_data)
was owned by root, so the host user could not delete or back up his own podcast
data — prune_podcast_data.py and update_stack.sh had to detour through
`docker compose exec` for every rm and tar.

That was not a requirement, just the default: the open_notebook image declares no
USER, and the compose file even overrode surrealdb's own non-root user (65532)
with `user: root`, under the comment "Required for bind mounts on Linux" — which
is not true.

Both services now run as user: "1000:1000". Two things this needs:

- HOME=/tmp for open_notebook. Without it HOME resolves to "/" for a non-root uid,
  uv cannot create /.cache/uv, and api + worker exit 2 at startup. Verified by
  running the image as uid 1000 both ways.
- The data directories must be owned by that uid. Existing data was adopted with a
  throwaway root container (chown -R), no sudo needed.

Both scripts drop the container detour and operate on the host directly, which is
simpler and now honest. smoke_test.sh gained two checks so a silent regression to
root cannot go unnoticed: the container's uid must match the host user, and no
foreign-owned files may exist under the data directories.

Verified: containers run as uid 1000, new files land as dschlueter and are
deletable without sudo, SurrealDB writes as 1000, a source can be created,
embedded and deleted through the API, and the full smoke test is green.

Note this deviates from what the image expects (it assumes root), so it is exactly
the kind of assumption an update can break — hence the smoke-test checks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 15:14:47 +02:00

317 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Open Notebook (lokales Deployment)
Selbst gehostetes [Open Notebook](https://github.com/lfnovo/open-notebook) per Docker Compose —
KI-gestützter Notiz-/Recherche-Assistent mit Chat, Quellenverwaltung und Podcast-Erstellung.
**Nur zwei KI-Provider:**
- **Ollama** (lokal, auf dem Host, GPU 1+2 — RTX 3090) für Chat, Embedding, Tools
- **OpenRouter** (Cloud, einziger externer Provider) als Alternative/Ergänzung
Text-to-Speech und Speech-to-Text laufen ebenfalls lokal: [Chatterbox TTS](https://github.com/resemble-ai/chatterbox)
(mit Stimmklonung) und [faster-whisper](https://github.com/SYSTRAN/faster-whisper), beide über
schlanke selbstgeschriebene OpenAI-kompatible HTTP-Wrapper in `services/`.
Ausführliche Bedienung (Chat-Modi, Podcasts, Stimmen, Troubleshooting): siehe
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md). Architektur- und Betriebsdetails für
Weiterentwicklung: siehe [`CLAUDE.md`](CLAUDE.md).
---
## Architektur
| Komponente | Läuft wo | Zweck |
|---|---|---|
| `surrealdb` | Docker | Datenbank (nur `127.0.0.1:8000`) |
| `open_notebook` | Docker | Web-UI (`:8502`) + REST-API (`:5055`) |
| Ollama | Host (systemd) | Chat-/Embedding-Modelle, GPU 1+2 |
| `services/tts_server.py` | Host (systemd-User-Dienst) | Chatterbox TTS, GPU 2, Port `8901` |
| `services/stt_server.py` | Host (systemd-User-Dienst) | faster-whisper STT, GPU 2, Port `8902` |
Der `open_notebook`-Container erreicht Ollama und die TTS/STT-Wrapper über
`host.docker.internal` (Linux-Route via `extra_hosts: host-gateway`).
---
## 1. Voraussetzungen
- **Docker** + Docker Compose (Plugin), Daemon läuft
- **Ollama** installiert und als Dienst aktiv (`systemctl status ollama`), erreichbar auf `11434`
- Empfohlene systemd-Umgebung für Multi-GPU-Setups mit dedizierter Desktop-GPU:
`CUDA_VISIBLE_DEVICES=1,2` (GPU 0 ausschließen), `OLLAMA_KEEP_ALIVE=-1`,
`OLLAMA_CONTEXT_LENGTH=131072`
- Benötigte Modelle: `qwen3.5:27b`, `nomic-embed-text` (weitere optional, siehe
`scripts/setup_models.sh`) — mit `ollama pull <modell>` laden
- **Python-Umgebungen für TTS/STT** (bereits vorhandene Installationen dieses Systems):
- Conda-Env `chatterbox` mit [chatterbox-tts](https://github.com/resemble-ai/chatterbox)
(`~/miniforge3/envs/chatterbox`, siehe `~/chatterbox-tts-cli/`)
- System-Python mit `faster-whisper`, `fastapi`, `uvicorn`
- **OPENROUTER_API_KEY** als Umgebungsvariable im Environment verfügbar (für die Secret-Generierung
in Schritt 2)
- **`ufw`** (falls als Firewall aktiv) — Standardrichtlinie „deny incoming“ wird vorausgesetzt
- **`openssl`**, **`ffmpeg`**, **`curl`**, **`python3`**
- **`yt-dlp`** — nur für `scripts/add_video_source.py` (Videos ohne Untertitel); der übrige Stack
läuft auch ohne
---
## 2. Installation
### 2.1 Repository
```bash
cd ~/open-notebook # bzw. Zielverzeichnis
git status # falls schon vorhanden: prüfen statt neu klonen
```
### 2.2 Secrets erzeugen (`.env`)
```bash
ENC_KEY=$(openssl rand -base64 32)
DB_PASS=$(openssl rand -base64 24 | tr -d '/+=')
cat > .env <<EOF
OPEN_NOTEBOOK_ENCRYPTION_KEY=${ENC_KEY}
SURREAL_USER=root
SURREAL_PASSWORD=${DB_PASS}
OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
EOF
chmod 600 .env
```
`.env` wird nicht committed (siehe `.gitignore`). `.env.example` ist das Template.
### 2.3 Container starten
```bash
mkdir -p surreal_data notebook_data # müssen dem eigenen User gehören
docker compose up -d
docker compose ps # beide Container sollten "Up" sein
```
Die Container laufen als **Host-User** (`user: "1000:1000"`), nicht als root — sonst gehörten alle
Daten, die sie schreiben (Notebooks, Podcasts, Datenbank), root, und Sie könnten sie ohne `sudo`
weder löschen noch sichern. Bei abweichender UID/GID (`id -u`, `id -g`) den Eintrag in
`docker-compose.yml` anpassen.
Die Images sind in `docker-compose.yml` auf einen **Digest gepinnt** (`pull_policy: missing`) —
`up -d` lädt sie beim ersten Mal und danach nie wieder unbemerkt eine andere Version. Aktualisiert
wird bewusst, siehe [Abschnitt 4](#4-updates).
Web-UI: `http://localhost:8502` · REST-API: `http://localhost:5055` (beide nur `127.0.0.1`).
### 2.4 Firewall öffnen für TTS/STT
Die TTS/STT-Wrapper laufen auf dem Host; der Docker-Container erreicht sie über die
Docker-Bridge, was bei aktiver `ufw`-Firewall (Standard: deny incoming) explizit erlaubt werden muss —
analog zur bestehenden Regel für Ollama (`11434/tcp`):
```bash
sudo ufw allow 8901/tcp comment 'open-notebook TTS (chatterbox)'
sudo ufw allow 8902/tcp comment 'open-notebook STT (faster-whisper)'
```
Ohne diesen Schritt bleiben TTS/STT vom Container aus unerreichbar (Timeout), obwohl sie lokal
laufen und funktionieren.
### 2.5 TTS/STT-Server einrichten
```bash
./scripts/start_services.sh
```
Installiert `services/systemd/*.service` nach `~/.config/systemd/user/`, aktiviert `linger`
(damit die Dienste auch ohne aktive Login-Session laufen) und startet beide. Sie laufen auf
GPU 2 — nicht GPU 0/1, um die Desktop-GPU und Ollamas Chat-Modell nicht zu verdrängen.
Das Skript ist idempotent und **überlebt Reboots**: die Dienste starten automatisch mit. Status
und Logs:
```bash
systemctl --user status open-notebook-tts open-notebook-stt
journalctl --user -u open-notebook-tts -f
```
> Der erste Start dauert bis zu einer Minute, weil whisper `large-v3` geladen wird.
Für Stimmklonung mindestens eine Referenz-WAV in `services/voices/default.wav` ablegen (z. B.
Symlink auf eine eigene Sprachaufnahme, 10–30s, WAV) — siehe
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md#5-stimmklonung).
### 2.6 KI-Provider und Modelle registrieren
```bash
./scripts/setup_models.sh
```
Richtet automatisch ein:
- Ollama-Credential (Chat + Embedding) mit `num_ctx=98304` — **wichtig**, siehe Warnkasten unten
- Kuratierte Ollama-Modelle: `qwen3.5:27b` (Standard für Chat/Tools/großer Kontext),
`nomic-embed-text` (Standard-Embedding), `qwen3-coder-30b-128k` (optional für Code)
- OpenRouter-API-Key aus `.env`/Environment in die verschlüsselte Datenbank migriert
- Kuratierte OpenRouter-Modelle (Claude Sonnet 5, Qwen3-Max, Gemini 3.5 Flash)
- Lokale TTS/STT-Wrapper als `openai_compatible`-Credentials + Standardmodelle
> **Warum `num_ctx` explizit gesetzt werden muss:** Ohne diese Einstellung begrenzt die
> zugrunde liegende Bibliothek (`esperanto`) jede Ollama-Chat-Anfrage stillschweigend auf
> 8192 Tokens Kontext — unabhängig vom eigentlichen Modell-Limit. Größere Chat-Kontexte
> (z. B. ganze Bücher im „Volltext"-Modus) werden dann abgeschnitten, und weil `qwen3.5:27b`
> ein „denkendes" Modell ist, kommt dabei oft eine **leere Antwort statt eines Fehlers**
> heraus. `98304` ist der größte Wert, der auf dieser Hardware (RTX 3090, 24 GB) noch
> vollständig auf der GPU bleibt (`ollama ps` → `100% GPU`). Details:
> [`CLAUDE.md`](CLAUDE.md).
### 2.7 Verifikation
```bash
curl -s http://127.0.0.1:5055/api/models/providers | python3 -m json.tool
```
Erwartung: `"available": ["openrouter", "ollama"]`. TTS/STT-Gesundheit:
```bash
curl -s http://127.0.0.1:8901/health # Chatterbox TTS
curl -s http://127.0.0.1:8902/health # faster-whisper STT
```
Gründlicher — prüft API, TTS, STT, YouTube-Extraktion und alle lokalen Anpassungen auf einmal:
```bash
./scripts/smoke_test.sh
```
UI öffnen (`http://localhost:8502`), ein Notebook anlegen, eine Quelle hinzufügen und chatten —
siehe [`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md) für die weitere Bedienung.
---
## 3. Alltägliche Befehle
```bash
docker compose up -d # starten
docker compose down # stoppen (Daten bleiben erhalten)
docker compose logs -f open_notebook # Logs verfolgen
docker compose ps # Status
systemctl --user status open-notebook-tts open-notebook-stt # TTS/STT-Status
systemctl --user restart open-notebook-tts # z.B. nach neuer Stimme
journalctl --user -u open-notebook-tts -f # TTS-Logs
./scripts/start_services.sh # Units neu installieren + starten (idempotent)
./scripts/prune_podcast_data.py # Podcast-Datenmüll anzeigen (Trockenlauf)
./scripts/prune_podcast_data.py --yes # ... und löschen
./scripts/add_video_source.py <url> # Video als Quelle (auch ohne Untertitel)
./scripts/check_updates.sh # gibt es ein neues Release? (ändert nichts)
./scripts/update_stack.sh # Update mit Backup, Rauchtest und Rollback
./scripts/smoke_test.sh # tut der Stack noch, worauf wir uns verlassen?
```
TTS/STT starten nach einem Reboot von selbst — `start_services.sh` ist nur für die
Ersteinrichtung bzw. nach Änderungen an den Unit-Dateien nötig.
---
## 4. Updates
Die Images sind **auf einen Digest gepinnt** — es läuft immer genau der Stand, der im Repo steht.
Weder ein `docker compose up -d` noch ein Reboot tauscht die Anwendung unbemerkt aus.
Beim Sitzungsstart (oder wann immer Sie mögen):
```bash
./scripts/check_updates.sh # zeigt nur: läuft X, verfügbar ist Y
```
Wenn ein neues Release da ist:
```bash
./scripts/update_stack.sh # Backup -> Update -> Rauchtest -> bei Fehler Rollback
```
Warum nicht automatisch das Neueste bei jedem Start? Ein Update **migriert die Datenbank**, und
eine ältere Anwendung kann eine migrierte Datenbank in der Regel nicht mehr lesen — ein
misslungenes Update ohne Backup wäre eine Einbahnstraße. Zudem hängen die lokalen Anpassungen
dieses Projekts (Podcast-Vorlagen, content-core-Config, Env-Variablen) an Interna der Anwendung
und können still brechen. Genau das prüft der Rauchtest; schlägt er fehl, rollt das Skript
Daten und Compose-Datei automatisch zurück.
Hinweis: `v1-latest` folgt den **Releases**, nicht dem `main`-Branch — der Repository-Stand ist
typischerweise Wochen voraus, aber unveröffentlicht. Wer den will, müsste selbst bauen.
---
## 5. Verzeichnisstruktur
```
open-notebook/
├── docker-compose.yml # SurrealDB + open_notebook
├── .env # Secrets (gitignored)
├── .env.example # Template
├── surreal_data/ # DB-Daten (gitignored)
├── notebook_data/ # Notebook-Dateien/Uploads (gitignored)
├── config/
│ └── content_core.yaml # content-core (u.a. deutsche YouTube-Transkripte)
├── services/
│ ├── tts_server.py # Chatterbox-Wrapper (OpenAI-API-kompatibel)
│ ├── stt_server.py # faster-whisper-Wrapper
│ ├── systemd/ # Unit-Dateien für die beiden Wrapper
│ ├── voices/ # Referenz-WAVs fürs Voice-Cloning (gitignored)
│ └── logs/ # (gitignored, Altlast der früheren nohup-Variante)
├── backups/ # Sicherungen vor Image-Updates (gitignored)
├── scripts/
│ ├── setup_models.sh # Provider/Modelle einrichten (idempotent)
│ ├── start_services.sh # TTS/STT als systemd-User-Dienste installieren+starten
│ ├── prune_podcast_data.py # verwaiste Podcast-Ordner + Zwischenclips aufräumen
│ ├── add_video_source.py # Video als Quelle (Untertitel oder Tonspur+Whisper)
│ ├── check_updates.sh # neues Release verfügbar? (ändert nichts)
│ ├── update_stack.sh # Update mit Backup/Rauchtest/Rollback
│ └── smoke_test.sh # prüft die Annahmen, auf denen die Anpassungen beruhen
├── README.md # diese Datei
├── BEDIENUNGSANLEITUNG.md # ausführliche Bedienungsanleitung (Deutsch)
└── CLAUDE.md # technische Architektur-Doku für Weiterentwicklung
```
---
## 6. Bekannte Stolpersteine
Kurzreferenz — Details jeweils in [`CLAUDE.md`](CLAUDE.md):
- **Embedding-Modell muss klein sein.** `qwen3-embedding` (ein zweckentfremdetes 8B-LLM,
~13 GB geladen) konkurriert mit dem Chat-Modell um GPU-Speicher und fällt dann teilweise auf
die CPU zurück — einzelne Embeddings dauern dann 40+ Sekunden und reißen Timeouts.
`nomic-embed-text` (274 MB) ist der Standard hier.
- **`num_ctx` beim Ollama-Chat-Credential ist Pflicht** (siehe Warnkasten in 2.6) — sonst
leere Chat-Antworten bei größerem Kontext, ohne sichtbaren Fehler.
- **Neue Host-Ports brauchen eine `ufw`-Regel**, sonst kann der Container sie nicht erreichen
(Timeout, keine Fehlermeldung in Open Notebook selbst).
- **YouTube-Transkripte brauchen `config/content_core.yaml`.** `content-core` sucht Untertitel
standardmäßig nur in `en`/`es`/`pt` — deutsche Videos landen sonst als **leere Quelle** im
Notebook (Titel da, Inhalt leer, Fehler nur im Log). Die eingehängte Config setzt Deutsch an
erste Stelle. Achtung: `CCORE_CONFIG_PATH` ersetzt die Konfiguration komplett (kein Merge) —
die Datei muss vollständig bleiben, siehe Kopfkommentar darin.
- **Videos ohne Untertitel** gehen über `./scripts/add_video_source.py <url>` (yt-dlp lädt die
Tonspur, der lokale Whisper-Server transkribiert sie). Dafür ist
`OPENAI_COMPATIBLE_BASE_URL_STT` in `docker-compose.yml` zwingend: content-core reicht dem
STT-Modell sonst keine `base_url` durch, fällt auf OpenAI zurück und scheitert mit
„OpenAI API key not found" — das ist **kein** fehlender Key, sondern eine fehlende URL. Keinen
`OPENAI_API_KEY` in den Container legen: das schickte Audio in die Cloud, obwohl Whisper lokal
auf GPU 2 bereitsteht.
- **Episoden löschen räumt nicht auf.** Der Mülleimer-Button (bzw.
`DELETE /api/podcasts/episodes/{id}`) entfernt nur die finale MP3 und den DB-Eintrag — der
Ordner `notebook_data/podcasts/episodes/<uuid>/` mit den Einzelclips, `outline.json` und
`transcript.json` bleibt liegen. Das ist eine Lücke im Upstream-Code, kein lokales
Konfigurationsproblem. Abhilfe: `./scripts/prune_podcast_data.py`.
- **GPU 2 teilen sich drei Prozesse** (TTS, STT und der separate `chatterbox-tts`-MCP-Dienst auf
Port 9999) — es bleiben nur ~12 GB Arbeitsspeicher für die Sprachsynthese. Deshalb serialisiert
`tts_server.py` seine Generierung intern und `TTS_BATCH_SIZE=1` steht in `docker-compose.yml`:
ohne beides schickt der Podcast-Generator 5 Clips gleichzeitig, die parallel auf der GPU laufen
und sie mit `CUDA out of memory` sprengen (sichtbar als `HTTP 500` beim Vertonen).
- **Podcast-Sprache** wird über das `language`-Feld des Episode-Profils gesteuert, aber nur
dank der gepatchten Prompt-Vorlagen unter `prompts/podcast/` (per Bind-Mount in
`docker-compose.yml` eingehängt) — die Original-Vorlagen im Image ignorieren `language`, was
englische Podcasts (von der deutsch-fixierten TTS mit Akzent vorgelesen) verursachte. Die
Vorlagen enthalten zusätzlich `/no_think`, damit `qwen3.5:27b` bei langem Quellinhalt nicht
durch überlange Reasoning-Blöcke ungültiges JSON liefert. Änderst du die Vorlagen, danach
`docker compose up -d --force-recreate open_notebook`. Details:
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md#11-troubleshooting) und [`CLAUDE.md`](CLAUDE.md).
Reference in a new issue View git blame Copy permalink