Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
# 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 |
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
| `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` |
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
|
|
|
|
|
|
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`**
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
- **`yt-dlp`** — nur für `scripts/add_video_source.py` (Videos ohne Untertitel); der übrige Stack
|
|
|
|
|
|
läuft auch ohne
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 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
|
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
|
|
|
|
mkdir -p surreal_data notebook_data # müssen dem eigenen User gehören
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
docker compose up -d
|
|
|
|
|
|
docker compose ps # beide Container sollten "Up" sein
|
|
|
|
|
|
```
|
|
|
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
|
|
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
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).
|
|
|
|
|
|
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
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.
|
|
|
|
|
|
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
### 2.5 TTS/STT-Server einrichten
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
./scripts/start_services.sh
|
|
|
|
|
|
```
|
|
|
|
|
|
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
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.
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
|
|
|
|
|
|
Für Stimmklonung mindestens eine Referenz-WAV in `services/voices/default.wav` ablegen (z. B.
|
|
|
|
|
|
Symlink auf eine eigene Sprachaufnahme, 10–30s, WAV) — siehe
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md#5-stimmklonung).
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
Gründlicher — prüft API, TTS, STT, YouTube-Extraktion und alle lokalen Anpassungen auf einmal:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
./scripts/smoke_test.sh
|
|
|
|
|
|
```
|
|
|
|
|
|
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
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
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
|
|
|
|
|
|
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)
|
Add prune_podcast_data.py: clean up podcast data Open Notebook leaves behind
Deleting an episode does not delete its data. DELETE /api/podcasts/episodes/{id}
resolves episode.audio_file and unlinks that one MP3 — the enclosing
data/podcasts/episodes/<uuid>/ directory, holding clips/ (one MP3 per dialogue
segment), outline.json and transcript.json, is never touched. Failed and
/retry-replaced runs leak a directory as well. Nothing reaps any of it: this
deployment had 15 directories on disk against 4 episodes in the database.
That is an upstream gap (roughly a shutil.rmtree of audio_path.parent.parent in
that handler), not something configurable here. Deliberately not patched by
bind-mounting a modified router — that would fork app logic into a deployment
repo and rot silently against pull_policy: always. Local cleanup instead.
scripts/prune_podcast_data.py reconciles the episode list from the API against
the directories on disk and removes:
- orphaned directories (no corresponding episode), and
- clips/ of completed episodes, since the clips are intermediate output once
the final MP3 exists.
Dry-run by default; --yes applies, --keep-clips restricts it to orphans.
Two guards, both tested: it aborts when any job is running/pending (a running
job has no audio_file yet, so its working directory is indistinguishable from an
orphan) and it skips directories touched within the last 60 minutes (--min-age).
It also refuses to act if the API is unreachable, rather than guessing.
Deletion runs inside the container (docker compose exec … rm -rf): the container
writes as root, so the host user cannot remove those directories — a plain
host-side rmtree fails with EPERM after the first directory.
Verified on this deployment: freed 13 MB (10 orphaned dirs + clips of 3 episodes,
49 MB -> 36 MB); all four surviving episodes still stream byte-identical MP3s
from /audio afterwards.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:14:19 +02:00
|
|
|
|
|
|
|
|
|
|
./scripts/prune_podcast_data.py # Podcast-Datenmüll anzeigen (Trockenlauf)
|
|
|
|
|
|
./scripts/prune_podcast_data.py --yes # ... und löschen
|
Add audio fallback so videos without captions work
Open Notebook only reads existing captions from a video. Without them the source
is created empty. yt-dlp lives on the host, not in the image, so the chain can't
run inside the app: scripts/add_video_source.py bridges it.
Captions present -> the URL goes in as a normal "link" source (fast, no download).
No captions -> yt-dlp pulls just the audio track (mono 16 kHz mp3, ~6 MB per
17 min) and uploads it as an "upload" source. Open Notebook
then transcribes it itself with its configured speech-to-text
model — the local faster-whisper server — and embeds it. The
script deliberately does not transcribe: the app's own pipeline
already does STT, chunking and embedding.
OPENAI_COMPATIBLE_BASE_URL_STT is what makes the upload path work at all. Open
Notebook passes its STT model (openai_compatible/faster-whisper-large-v3) into
content-core, but content-core builds it with
AIFactory.create_speech_to_text(provider, model, {'timeout': ...}) — with no
base_url. Esperanto can't locate the local server, content-core falls back to its
default (openai/whisper-1) and the job dies with "OpenAI API key not found". That
message is misleading: nothing is missing but the URL. The env var supplies it.
An OPENAI_API_KEY is deliberately NOT put into the container — that would ship
audio to a paid cloud service while a working Whisper sits idle on GPU 2.
Caption availability is probed with youtube-transcript-api inside the container,
not with yt-dlp. yt-dlp's automatic_captions lists YouTube's ~100 auto-translation
targets (German is always among them), which youtube-transcript-api does not
accept as transcripts — trusting it would route a Japanese-only video down the
caption path and produce an empty source again.
The uploaded mp3 is removed afterwards by the script. The API's delete_source=true
flag is meant for exactly this but is inert in this content-core version:
extract_content drops the field when building the graph state (the returned state
carries delete_source=None), so the delete_file node never fires. Verified by
running the flag through the real API path and watching the file survive. Files
are also named after the video id, since every upload previously landed as
audio.mp3 and a second video would have collided with the first.
Verified end to end: the reported video (hzxiegk9QAg, 17:14) transcribes to 22069
characters via the local Whisper server (two segment requests, both 200), embeds
into 14 chunks, and uploads/ is empty afterwards. An English video (aircAruvnKk)
works with automatic language detection. Whisper's text is noticeably cleaner than
YouTube's auto-captions ("GitHub" vs "Gitub", real punctuation), so --force-audio
is useful even when captions exist.
Known gap: the audio path stores the audio file as the source asset, so the
original video URL is not recorded on the source (the caption path records it).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:49:33 +02:00
|
|
|
|
|
|
|
|
|
|
./scripts/add_video_source.py <url> # Video als Quelle (auch ohne Untertitel)
|
Pin images by digest; add update, smoke-test and status scripts
Goal: at every session start, run exactly the application the repo says — and be able
to move to a new upstream release deliberately, with a way back.
The old setup (v1-latest + pull_policy: always) was unreliable in both directions.
`docker compose up -d` silently pulled a new application, including an irreversible
SurrealDB schema migration, while a reboot (restart: always) or `docker compose start`
kept running the old image without pulling anything. The running version was effectively
unpredictable.
Note v1-latest tracks releases, not main: the current image (v1.10.0, 2026-06-18) IS the
latest release — the repo being "ahead" is unreleased code, which is explicitly not
wanted here. So this is about guaranteeing and detecting, not catching up.
- docker-compose.yml: both images pinned by digest, pull_policy: missing.
- scripts/check_updates.sh: reports running version/digest vs the latest release and
registry digest. Changes nothing; meant for the session-start ritual.
- scripts/update_stack.sh: resolve new digest -> stop -> back up surreal_data,
notebook_data and docker-compose.yml -> repin -> start -> smoke test -> roll back data
AND compose file if the smoke test fails. The data backup is the point: the app migrates
the DB on startup and an older app cannot read a migrated DB, so a bad update would
otherwise be a one-way door. tar runs inside a container because the data dirs are
root-owned and the host user cannot restore over them.
- scripts/smoke_test.sh: checks what actually breaks here, not just "does it start".
Every local adaptation leans on upstream internals and can break silently: the
prompts/podcast directory mount masks the image's directory (a new template upstream
would be invisible), config/content_core.yaml freezes content-core's defaults (because
CCORE_CONFIG_PATH replaces rather than merges), and the env-var workarounds depend on
current content-core/esperanto/podcast_creator behaviour. So it verifies those
assumptions explicitly, plus API, TTS audio, STT and a real YouTube transcript.
Both scripts read the digest from the lfnovo/open_notebook line specifically. A naive
"first sha256 in the file" grep matches surrealdb (listed first) — caught while testing:
check_updates.sh falsely reported an update, and update_stack.sh would have rewritten the
database image instead of the application.
Verified: smoke test green against the current stack, and red (exit 1) when failures are
injected (dead TTS port, removed template variable). Backup/restore mechanics exercised
separately: 44 MB in 3.3s, restore yields 13 DB files and 91 notebook files. The update
path itself cannot be exercised end to end until a newer image exists.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:12:31 +02:00
|
|
|
|
|
|
|
|
|
|
./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?
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
```
|
|
|
|
|
|
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
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.
|
|
|
|
|
|
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
---
|
|
|
|
|
|
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
## 4. Updates
|
Pin images by digest; add update, smoke-test and status scripts
Goal: at every session start, run exactly the application the repo says — and be able
to move to a new upstream release deliberately, with a way back.
The old setup (v1-latest + pull_policy: always) was unreliable in both directions.
`docker compose up -d` silently pulled a new application, including an irreversible
SurrealDB schema migration, while a reboot (restart: always) or `docker compose start`
kept running the old image without pulling anything. The running version was effectively
unpredictable.
Note v1-latest tracks releases, not main: the current image (v1.10.0, 2026-06-18) IS the
latest release — the repo being "ahead" is unreleased code, which is explicitly not
wanted here. So this is about guaranteeing and detecting, not catching up.
- docker-compose.yml: both images pinned by digest, pull_policy: missing.
- scripts/check_updates.sh: reports running version/digest vs the latest release and
registry digest. Changes nothing; meant for the session-start ritual.
- scripts/update_stack.sh: resolve new digest -> stop -> back up surreal_data,
notebook_data and docker-compose.yml -> repin -> start -> smoke test -> roll back data
AND compose file if the smoke test fails. The data backup is the point: the app migrates
the DB on startup and an older app cannot read a migrated DB, so a bad update would
otherwise be a one-way door. tar runs inside a container because the data dirs are
root-owned and the host user cannot restore over them.
- scripts/smoke_test.sh: checks what actually breaks here, not just "does it start".
Every local adaptation leans on upstream internals and can break silently: the
prompts/podcast directory mount masks the image's directory (a new template upstream
would be invisible), config/content_core.yaml freezes content-core's defaults (because
CCORE_CONFIG_PATH replaces rather than merges), and the env-var workarounds depend on
current content-core/esperanto/podcast_creator behaviour. So it verifies those
assumptions explicitly, plus API, TTS audio, STT and a real YouTube transcript.
Both scripts read the digest from the lfnovo/open_notebook line specifically. A naive
"first sha256 in the file" grep matches surrealdb (listed first) — caught while testing:
check_updates.sh falsely reported an update, and update_stack.sh would have rewritten the
database image instead of the application.
Verified: smoke test green against the current stack, and red (exit 1) when failures are
injected (dead TTS port, removed template variable). Backup/restore mechanics exercised
separately: 44 MB in 3.3s, restore yields 13 DB files and 91 notebook files. The update
path itself cannot be exercised end to end until a newer image exists.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:12:31 +02:00
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
## 5. Verzeichnisstruktur
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
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)
|
Fix YouTube sources with German transcripts landing empty
Adding a German YouTube video created a source with a title but no content —
nothing to chat with, nothing to summarise. The failure was silent in the UI;
the reason only showed up in the container log as "Failed to get transcript for
video <id> after retries: No suitable transcript found".
Open Notebook extracts YouTube via content-core, which reads captions with
youtube-transcript-api. content_core/processors/youtube.py only looks for the
languages listed in preferred_languages, and the built-in default is
["en", "es", "pt"] — no German. All four fallback attempts in
_fetch_best_transcript use that same list, so a video carrying only a German
transcript raises NoTranscriptFound, get_best_transcript swallows it and returns
None, and the source is stored with an empty body. The title still arrives
because it is scraped separately, which is what makes this look like a success.
The youtube_transcripts.preferred_languages key in the package's own
cc_config.yaml appears to be the knob for this, but it is dead code on the
default path: load_config() copies only the "extraction" block out of that file,
so the key never reaches CONFIG and the hardcoded fallback always wins. The only
way to set it is CCORE_CONFIG_PATH.
config/content_core.yaml (bind-mounted read-only) therefore sets
preferred_languages: ["de", "en", "es", "pt"].
Note CCORE_CONFIG_PATH REPLACES the config wholesale rather than merging it
(config.py: return yaml.safe_load(file)). The file is consequently a full dump of
the effective default config plus the new key — a minimal override file would
silently drop the extraction engines and the model/timeout defaults. Its header
comment carries the command that regenerates it from inside the container, for
when an image update changes content-core's defaults.
Verified end to end on the reported video (hzxiegk9QAg): extraction now yields
21553 characters of German transcript, the source is created through
POST /api/sources with that full text, embedding produces 17 chunks in 3.4s, and
vector search returns the video as top hit.
This only covers caption languages. A video with no captions at all still yields
an empty source — there is no download-and-transcribe fallback in the image.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:20:14 +02:00
|
|
|
|
├── config/
|
|
|
|
|
|
│ └── content_core.yaml # content-core (u.a. deutsche YouTube-Transkripte)
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
├── services/
|
|
|
|
|
|
│ ├── tts_server.py # Chatterbox-Wrapper (OpenAI-API-kompatibel)
|
|
|
|
|
|
│ ├── stt_server.py # faster-whisper-Wrapper
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
│ ├── systemd/ # Unit-Dateien für die beiden Wrapper
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
│ ├── voices/ # Referenz-WAVs fürs Voice-Cloning (gitignored)
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
│ └── logs/ # (gitignored, Altlast der früheren nohup-Variante)
|
Pin images by digest; add update, smoke-test and status scripts
Goal: at every session start, run exactly the application the repo says — and be able
to move to a new upstream release deliberately, with a way back.
The old setup (v1-latest + pull_policy: always) was unreliable in both directions.
`docker compose up -d` silently pulled a new application, including an irreversible
SurrealDB schema migration, while a reboot (restart: always) or `docker compose start`
kept running the old image without pulling anything. The running version was effectively
unpredictable.
Note v1-latest tracks releases, not main: the current image (v1.10.0, 2026-06-18) IS the
latest release — the repo being "ahead" is unreleased code, which is explicitly not
wanted here. So this is about guaranteeing and detecting, not catching up.
- docker-compose.yml: both images pinned by digest, pull_policy: missing.
- scripts/check_updates.sh: reports running version/digest vs the latest release and
registry digest. Changes nothing; meant for the session-start ritual.
- scripts/update_stack.sh: resolve new digest -> stop -> back up surreal_data,
notebook_data and docker-compose.yml -> repin -> start -> smoke test -> roll back data
AND compose file if the smoke test fails. The data backup is the point: the app migrates
the DB on startup and an older app cannot read a migrated DB, so a bad update would
otherwise be a one-way door. tar runs inside a container because the data dirs are
root-owned and the host user cannot restore over them.
- scripts/smoke_test.sh: checks what actually breaks here, not just "does it start".
Every local adaptation leans on upstream internals and can break silently: the
prompts/podcast directory mount masks the image's directory (a new template upstream
would be invisible), config/content_core.yaml freezes content-core's defaults (because
CCORE_CONFIG_PATH replaces rather than merges), and the env-var workarounds depend on
current content-core/esperanto/podcast_creator behaviour. So it verifies those
assumptions explicitly, plus API, TTS audio, STT and a real YouTube transcript.
Both scripts read the digest from the lfnovo/open_notebook line specifically. A naive
"first sha256 in the file" grep matches surrealdb (listed first) — caught while testing:
check_updates.sh falsely reported an update, and update_stack.sh would have rewritten the
database image instead of the application.
Verified: smoke test green against the current stack, and red (exit 1) when failures are
injected (dead TTS port, removed template variable). Backup/restore mechanics exercised
separately: 44 MB in 3.3s, restore yields 13 DB files and 91 notebook files. The update
path itself cannot be exercised end to end until a newer image exists.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:12:31 +02:00
|
|
|
|
├── backups/ # Sicherungen vor Image-Updates (gitignored)
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
├── scripts/
|
|
|
|
|
|
│ ├── setup_models.sh # Provider/Modelle einrichten (idempotent)
|
Add prune_podcast_data.py: clean up podcast data Open Notebook leaves behind
Deleting an episode does not delete its data. DELETE /api/podcasts/episodes/{id}
resolves episode.audio_file and unlinks that one MP3 — the enclosing
data/podcasts/episodes/<uuid>/ directory, holding clips/ (one MP3 per dialogue
segment), outline.json and transcript.json, is never touched. Failed and
/retry-replaced runs leak a directory as well. Nothing reaps any of it: this
deployment had 15 directories on disk against 4 episodes in the database.
That is an upstream gap (roughly a shutil.rmtree of audio_path.parent.parent in
that handler), not something configurable here. Deliberately not patched by
bind-mounting a modified router — that would fork app logic into a deployment
repo and rot silently against pull_policy: always. Local cleanup instead.
scripts/prune_podcast_data.py reconciles the episode list from the API against
the directories on disk and removes:
- orphaned directories (no corresponding episode), and
- clips/ of completed episodes, since the clips are intermediate output once
the final MP3 exists.
Dry-run by default; --yes applies, --keep-clips restricts it to orphans.
Two guards, both tested: it aborts when any job is running/pending (a running
job has no audio_file yet, so its working directory is indistinguishable from an
orphan) and it skips directories touched within the last 60 minutes (--min-age).
It also refuses to act if the API is unreachable, rather than guessing.
Deletion runs inside the container (docker compose exec … rm -rf): the container
writes as root, so the host user cannot remove those directories — a plain
host-side rmtree fails with EPERM after the first directory.
Verified on this deployment: freed 13 MB (10 orphaned dirs + clips of 3 episodes,
49 MB -> 36 MB); all four surviving episodes still stream byte-identical MP3s
from /audio afterwards.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:14:19 +02:00
|
|
|
|
│ ├── start_services.sh # TTS/STT als systemd-User-Dienste installieren+starten
|
Pin images by digest; add update, smoke-test and status scripts
Goal: at every session start, run exactly the application the repo says — and be able
to move to a new upstream release deliberately, with a way back.
The old setup (v1-latest + pull_policy: always) was unreliable in both directions.
`docker compose up -d` silently pulled a new application, including an irreversible
SurrealDB schema migration, while a reboot (restart: always) or `docker compose start`
kept running the old image without pulling anything. The running version was effectively
unpredictable.
Note v1-latest tracks releases, not main: the current image (v1.10.0, 2026-06-18) IS the
latest release — the repo being "ahead" is unreleased code, which is explicitly not
wanted here. So this is about guaranteeing and detecting, not catching up.
- docker-compose.yml: both images pinned by digest, pull_policy: missing.
- scripts/check_updates.sh: reports running version/digest vs the latest release and
registry digest. Changes nothing; meant for the session-start ritual.
- scripts/update_stack.sh: resolve new digest -> stop -> back up surreal_data,
notebook_data and docker-compose.yml -> repin -> start -> smoke test -> roll back data
AND compose file if the smoke test fails. The data backup is the point: the app migrates
the DB on startup and an older app cannot read a migrated DB, so a bad update would
otherwise be a one-way door. tar runs inside a container because the data dirs are
root-owned and the host user cannot restore over them.
- scripts/smoke_test.sh: checks what actually breaks here, not just "does it start".
Every local adaptation leans on upstream internals and can break silently: the
prompts/podcast directory mount masks the image's directory (a new template upstream
would be invisible), config/content_core.yaml freezes content-core's defaults (because
CCORE_CONFIG_PATH replaces rather than merges), and the env-var workarounds depend on
current content-core/esperanto/podcast_creator behaviour. So it verifies those
assumptions explicitly, plus API, TTS audio, STT and a real YouTube transcript.
Both scripts read the digest from the lfnovo/open_notebook line specifically. A naive
"first sha256 in the file" grep matches surrealdb (listed first) — caught while testing:
check_updates.sh falsely reported an update, and update_stack.sh would have rewritten the
database image instead of the application.
Verified: smoke test green against the current stack, and red (exit 1) when failures are
injected (dead TTS port, removed template variable). Backup/restore mechanics exercised
separately: 44 MB in 3.3s, restore yields 13 DB files and 91 notebook files. The update
path itself cannot be exercised end to end until a newer image exists.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:12:31 +02:00
|
|
|
|
│ ├── 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
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
├── README.md # diese Datei
|
|
|
|
|
|
├── BEDIENUNGSANLEITUNG.md # ausführliche Bedienungsanleitung (Deutsch)
|
|
|
|
|
|
└── CLAUDE.md # technische Architektur-Doku für Weiterentwicklung
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
## 6. Bekannte Stolpersteine
|
Add README.md, BEDIENUNGSANLEITUNG.md, and setup/start scripts
README.md gives the precise, reproducible install path (tested the two
scripts against the live instance - both idempotent, correctly detect
already-registered credentials/models). BEDIENUNGSANLEITUNG.md covers daily
usage: notebooks/sources, the three chat context modes (and why "nur
Erkenntnisse" needs a transformation run first), podcasts, voice cloning,
and troubleshooting for the issues actually hit during setup (num_ctx
truncation, embedding GPU contention, ufw).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-10 23:50:58 +02:00
|
|
|
|
|
|
|
|
|
|
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).
|
Fix YouTube sources with German transcripts landing empty
Adding a German YouTube video created a source with a title but no content —
nothing to chat with, nothing to summarise. The failure was silent in the UI;
the reason only showed up in the container log as "Failed to get transcript for
video <id> after retries: No suitable transcript found".
Open Notebook extracts YouTube via content-core, which reads captions with
youtube-transcript-api. content_core/processors/youtube.py only looks for the
languages listed in preferred_languages, and the built-in default is
["en", "es", "pt"] — no German. All four fallback attempts in
_fetch_best_transcript use that same list, so a video carrying only a German
transcript raises NoTranscriptFound, get_best_transcript swallows it and returns
None, and the source is stored with an empty body. The title still arrives
because it is scraped separately, which is what makes this look like a success.
The youtube_transcripts.preferred_languages key in the package's own
cc_config.yaml appears to be the knob for this, but it is dead code on the
default path: load_config() copies only the "extraction" block out of that file,
so the key never reaches CONFIG and the hardcoded fallback always wins. The only
way to set it is CCORE_CONFIG_PATH.
config/content_core.yaml (bind-mounted read-only) therefore sets
preferred_languages: ["de", "en", "es", "pt"].
Note CCORE_CONFIG_PATH REPLACES the config wholesale rather than merging it
(config.py: return yaml.safe_load(file)). The file is consequently a full dump of
the effective default config plus the new key — a minimal override file would
silently drop the extraction engines and the model/timeout defaults. Its header
comment carries the command that regenerates it from inside the container, for
when an image update changes content-core's defaults.
Verified end to end on the reported video (hzxiegk9QAg): extraction now yields
21553 characters of German transcript, the source is created through
POST /api/sources with that full text, embedding produces 17 chunks in 3.4s, and
vector search returns the video as top hit.
This only covers caption languages. A video with no captions at all still yields
an empty source — there is no download-and-transcribe fallback in the image.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:20:14 +02:00
|
|
|
|
- **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.
|
Add audio fallback so videos without captions work
Open Notebook only reads existing captions from a video. Without them the source
is created empty. yt-dlp lives on the host, not in the image, so the chain can't
run inside the app: scripts/add_video_source.py bridges it.
Captions present -> the URL goes in as a normal "link" source (fast, no download).
No captions -> yt-dlp pulls just the audio track (mono 16 kHz mp3, ~6 MB per
17 min) and uploads it as an "upload" source. Open Notebook
then transcribes it itself with its configured speech-to-text
model — the local faster-whisper server — and embeds it. The
script deliberately does not transcribe: the app's own pipeline
already does STT, chunking and embedding.
OPENAI_COMPATIBLE_BASE_URL_STT is what makes the upload path work at all. Open
Notebook passes its STT model (openai_compatible/faster-whisper-large-v3) into
content-core, but content-core builds it with
AIFactory.create_speech_to_text(provider, model, {'timeout': ...}) — with no
base_url. Esperanto can't locate the local server, content-core falls back to its
default (openai/whisper-1) and the job dies with "OpenAI API key not found". That
message is misleading: nothing is missing but the URL. The env var supplies it.
An OPENAI_API_KEY is deliberately NOT put into the container — that would ship
audio to a paid cloud service while a working Whisper sits idle on GPU 2.
Caption availability is probed with youtube-transcript-api inside the container,
not with yt-dlp. yt-dlp's automatic_captions lists YouTube's ~100 auto-translation
targets (German is always among them), which youtube-transcript-api does not
accept as transcripts — trusting it would route a Japanese-only video down the
caption path and produce an empty source again.
The uploaded mp3 is removed afterwards by the script. The API's delete_source=true
flag is meant for exactly this but is inert in this content-core version:
extract_content drops the field when building the graph state (the returned state
carries delete_source=None), so the delete_file node never fires. Verified by
running the flag through the real API path and watching the file survive. Files
are also named after the video id, since every upload previously landed as
audio.mp3 and a second video would have collided with the first.
Verified end to end: the reported video (hzxiegk9QAg, 17:14) transcribes to 22069
characters via the local Whisper server (two segment requests, both 200), embeds
into 14 chunks, and uploads/ is empty afterwards. An English video (aircAruvnKk)
works with automatic language detection. Whisper's text is noticeably cleaner than
YouTube's auto-captions ("GitHub" vs "Gitub", real punctuation), so --force-audio
is useful even when captions exist.
Known gap: the audio path stores the audio file as the source asset, so the
original video URL is not recorded on the source (the caption path records it).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:49:33 +02:00
|
|
|
|
- **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.
|
Add prune_podcast_data.py: clean up podcast data Open Notebook leaves behind
Deleting an episode does not delete its data. DELETE /api/podcasts/episodes/{id}
resolves episode.audio_file and unlinks that one MP3 — the enclosing
data/podcasts/episodes/<uuid>/ directory, holding clips/ (one MP3 per dialogue
segment), outline.json and transcript.json, is never touched. Failed and
/retry-replaced runs leak a directory as well. Nothing reaps any of it: this
deployment had 15 directories on disk against 4 episodes in the database.
That is an upstream gap (roughly a shutil.rmtree of audio_path.parent.parent in
that handler), not something configurable here. Deliberately not patched by
bind-mounting a modified router — that would fork app logic into a deployment
repo and rot silently against pull_policy: always. Local cleanup instead.
scripts/prune_podcast_data.py reconciles the episode list from the API against
the directories on disk and removes:
- orphaned directories (no corresponding episode), and
- clips/ of completed episodes, since the clips are intermediate output once
the final MP3 exists.
Dry-run by default; --yes applies, --keep-clips restricts it to orphans.
Two guards, both tested: it aborts when any job is running/pending (a running
job has no audio_file yet, so its working directory is indistinguishable from an
orphan) and it skips directories touched within the last 60 minutes (--min-age).
It also refuses to act if the API is unreachable, rather than guessing.
Deletion runs inside the container (docker compose exec … rm -rf): the container
writes as root, so the host user cannot remove those directories — a plain
host-side rmtree fails with EPERM after the first directory.
Verified on this deployment: freed 13 MB (10 orphaned dirs + clips of 3 episodes,
49 MB -> 36 MB); all four surviving episodes still stream byte-identical MP3s
from /audio afterwards.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:14:19 +02:00
|
|
|
|
- **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`.
|
Fix two podcast failures: dead TTS server after reboot + CUDA OOM
Podcast generation failed twice at the audio stage, for two unrelated reasons
that look similar from the UI but need opposite fixes.
1) TTS/STT ran as nohup background processes and silently did not survive a
reboot. Podcasts then failed with "Failed to generate speech: All connection
attempts failed" (httpx.ConnectError) even though outline and transcript had
generated fine.
Both now run as systemd user units. The unit files are versioned in
services/systemd/ (using %h, not a hardcoded home) and installed by
scripts/start_services.sh, which also enables linger so they start on boot
without a login session. They pin GPU 2 by UUID, not by index: CUDA orders
devices "fastest first", so index 2 can resolve to the T600.
2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts
MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends
TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a
sync FastAPI handler, they generated genuinely in parallel on one shared
model. Activation memory multiplied, the TTS process hit 16.7 GB and threw
torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint.
tts_server.py now serializes generation behind a lock (GPU-bound work, so
parallelism buys no throughput — it only multiplies peak VRAM) and frees the
cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in
that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT
is raised to 600s as headroom.
Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking
at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed
episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM.
Docs record both failure signatures side by side, since ConnectError (server
dead) and HTTP 500 (server alive, out of VRAM) have very different remedies.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 13:02:32 +02:00
|
|
|
|
- **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).
|
2026-07-11 02:30:05 +02:00
|
|
|
|
- **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:
|
Docs: close the gaps an audit turned up
Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:
- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
.env, .gitignore)". It has not been that for a while: services/ is our own
source (TTS/STT servers + systemd units), scripts/ is tooling, and
prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
image. Those overlays are the fragile part, so the section now says so and
points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
app code "because it would rot against pull_policy: always" — both obsolete
since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
in the verification step, and section 2.3 still told you to `docker compose pull`
as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
to do periodically. New section 8 covers check_updates / update_stack / smoke_test
and, importantly, why updating is not automatic (DB migration is one-way without
a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
BEDIENUNGSANLEITUNG sections after the new 8 accordingly.
Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 14:17:06 +02:00
|
|
|
|
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md#11-troubleshooting) und [`CLAUDE.md`](CLAUDE.md).
|