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>
This commit is contained in:
parent
4805fe75ed
commit
09c6d910a7
3 changed files with 82 additions and 16 deletions
|
|
@ -15,9 +15,10 @@ siehe [`CLAUDE.md`](CLAUDE.md).
|
|||
5. [Stimmklonung](#5-stimmklonung)
|
||||
6. [Modelle und Provider verwalten](#6-modelle-und-provider-verwalten)
|
||||
7. [Dienste starten/stoppen](#7-dienste-startenstoppen)
|
||||
8. [Suche über Chunks (Search/Ask)](#8-suche-über-chunks-searchask)
|
||||
9. [Die API in eigenen Programmen nutzen](#9-die-api-in-eigenen-programmen-nutzen)
|
||||
10. [Troubleshooting](#10-troubleshooting)
|
||||
8. [Updates einspielen](#8-updates-einspielen)
|
||||
9. [Suche über Chunks (Search/Ask)](#9-suche-über-chunks-searchask)
|
||||
10. [Die API in eigenen Programmen nutzen](#10-die-api-in-eigenen-programmen-nutzen)
|
||||
11. [Troubleshooting](#11-troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -256,7 +257,54 @@ ollama ps # aktuell geladene Modelle + GPU/CPU-Verteilung
|
|||
|
||||
---
|
||||
|
||||
## 8. Suche über Chunks (Search/Ask)
|
||||
## 8. Updates einspielen
|
||||
|
||||
Open Notebook läuft hier auf einer **festgenagelten Version** (Digest-Pin in
|
||||
`docker-compose.yml`). Weder ein Start noch ein Reboot tauscht die Anwendung unbemerkt aus — Sie
|
||||
bekommen immer genau den Stand, der zuletzt geprüft wurde.
|
||||
|
||||
**Beim Sitzungsstart** (ändert nichts, dauert Sekunden):
|
||||
|
||||
```bash
|
||||
./scripts/check_updates.sh
|
||||
```
|
||||
|
||||
Ausgabe entweder „Du laeufst auf dem aktuellen Release. Nichts zu tun." oder ein Hinweis auf ein
|
||||
neues Image.
|
||||
|
||||
**Update einspielen:**
|
||||
|
||||
```bash
|
||||
./scripts/update_stack.sh
|
||||
```
|
||||
|
||||
Das Skript sichert zuerst Datenbank und Notebook-Daten nach `backups/<Zeitstempel>/`, stellt dann
|
||||
auf das neue Image um, startet den Stack und fährt einen **Rauchtest** (API, Sprachausgabe,
|
||||
Spracherkennung, YouTube-Import, alle lokalen Anpassungen). Schlägt der fehl, wird **automatisch
|
||||
zurückgerollt** — Daten und Konfiguration landen wieder auf dem alten Stand.
|
||||
|
||||
Läuft alles, committen Sie den neuen Stand:
|
||||
|
||||
```bash
|
||||
git add docker-compose.yml && git commit -m "Update auf <Version>"
|
||||
```
|
||||
|
||||
**Warum nicht einfach immer die neueste Version?** Ein Update verändert das Datenbankschema, und
|
||||
eine ältere Version kann eine bereits migrierte Datenbank in der Regel nicht mehr lesen — ohne
|
||||
Sicherung wäre ein misslungenes Update also eine Einbahnstraße. Außerdem hängen die Anpassungen
|
||||
dieser Installation (Podcast-Vorlagen, YouTube-Sprachen, TTS-Einstellungen) an Interna der
|
||||
Anwendung und können durch ein Update **still** kaputtgehen, ohne dass etwas abstürzt. Genau
|
||||
deshalb der Rauchtest.
|
||||
|
||||
Ihn können Sie auch jederzeit einzeln laufen lassen, etwa wenn sich etwas seltsam verhält:
|
||||
|
||||
```bash
|
||||
./scripts/smoke_test.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Suche über Chunks (Search/Ask)
|
||||
|
||||
Jedes Dokument wird beim Hochladen automatisch in feste, überlappende Textabschnitte
|
||||
("Chunks", ~400 Tokens) zerlegt und eingebettet — **nicht** kapitelweise, sondern rein
|
||||
|
|
@ -300,7 +348,7 @@ weil nur die relevanten Chunks statt des ganzen Dokuments verarbeitet werden.
|
|||
|
||||
---
|
||||
|
||||
## 9. Die API in eigenen Programmen nutzen
|
||||
## 10. Die API in eigenen Programmen nutzen
|
||||
|
||||
Die REST-API ist eine ganz normale JSON-über-HTTP-API **ohne Authentifizierung** — kein API-Key
|
||||
nötig, da nur `127.0.0.1` gebunden (jeder lokale Prozess auf diesem Rechner hat Zugriff, aber
|
||||
|
|
@ -361,7 +409,7 @@ Spezifisches nötig, kein SDK erforderlich.
|
|||
|
||||
---
|
||||
|
||||
## 10. Troubleshooting
|
||||
## 11. Troubleshooting
|
||||
|
||||
### „Chat gibt keine Antwort" (leere Antwort, kein Fehler)
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue