docs: Systemanforderungen und journald-Abhaengigkeit dokumentieren (v0.6.3)

Aus den Testlaeufen auf Debian 12 (CT 200) und Debian 13 (CT 201):

- Systemanforderungen: mindestens 2 GB RAM. Eine einzelne A4-Seite in
  300 dpi mit deskew=true hat auf einem 512-MB-Container den OOM-Killer
  ausgeloest (anon-rss:489676kB). Dazu der Zusammenhang RAM <->
  max_workers x jobs x Aufloesung, wie sich ein OOM-Kill aeussert und wie
  man ihn nachweist (/sys/fs/cgroup/memory.events, dmesg auf dem Host).
- Troubleshooting: kaputtes systemd-journald ist ein blinder Fleck, weil
  der Dienst seit v0.4.1 nur dorthin loggt. Symptom, erste Pruefung und
  ein Vordergrund-Notbehelf. Auf einem von zwei Testcontainern aufgetreten
  — kein generelles LXC-Muster.

Nebenbei korrigiert: toter Anker in docs/INSTALLATION.md (#3-ocr-sprachen
-> #4-ocr-sprachen) und eine veraltete Stelle im Briefing, die
requirements.txt noch als "ocrmypdf 16.x" beschrieb.

Reine Doku-Version, 152 Tests unveraendert gruen.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-23 00:18:45 +02:00
parent 04dc3c7b72
commit 305454eeb5
6 changed files with 201 additions and 7 deletions
+54
View File
@@ -1,5 +1,59 @@
# Changelog
## [0.6.3] - 2026-09-23
Reine Doku-Version — kein Code, kein Installer, kein Updater, keine Unit, keine
Tests angefasst (ausser dem Versionsstring). Beide Erkenntnisse stammen aus den
Testlaeufen auf Debian 12 und Debian 13.
### Added
- **Abschnitt "Systemanforderungen" in `docs/INSTALLATION.md`.** Die
Dimensionierung fehlte bisher komplett. Empfohlen werden **mindestens 2 GB
RAM**; 512 MB reichen fuer 300-dpi-Scans nachweislich nicht. Gemessen auf
einem LXC-Container mit 512 MB RAM + 512 MB Swap, Debian 13,
Ghostscript 10.05.1: eine **einzelne A4-Seite in 300 dpi** mit
`deskew = true` riss das cgroup-Limit und der Dienst wurde vom OOM-Killer
beendet (`oom-kill:constraint=CONSTRAINT_MEMCG, oom_memcg=/lxc/201,
task=python`, `total-vm:1168764kB, anon-rss:489676kB`). Dieselbe
Verarbeitung mit einer kleineren Seite (850x1100 px) lief in ca. 19 s sauber
durch.
- Dokumentiert ist der Zusammenhang **RAM <-> `max_workers` x `jobs` x
Aufloesung**: `max_workers` (Default 2) laesst zwei solcher Seiten
gleichzeitig laufen, der Spitzenbedarf multipliziert sich entsprechend.
Wer knapp dimensioniert, zieht zuerst `max_workers` herunter.
- Dazu, **wie sich ein OOM-Kill aeussert** (Dienst weg bzw. von systemd neu
gestartet, `NRestarts` steigt, Abbruch mitten in der Datei ohne Traceback,
PDF bleibt in `working/` liegen) und **wie man ihn nachweist**
(`/sys/fs/cgroup/memory.events` im Container, `dmesg` auf dem LXC-Host).
Ohne diese Pruefung sieht der Fall wie ein Anwendungsfehler aus und man
sucht in ocrmypdf, Tesseract oder der Config.
- Mit dem Hinweis, dass die Wiederaufnahme aus `working/` seit v0.6.0 den
Datenverlust abfaengt — der OOM selbst bleibt aber ein Problem: bei
unveraenderter Dimensionierung laeuft dieselbe Datei nach dem Neustart
erneut hinein.
- `README.md` bekommt im Schnellstart nur einen Einzeiler mit Verweis, keine
Dublette.
- **Troubleshooting-Eintrag "Keine Logs: No journal files were found" in
`docs/INSTALLATION.md`.** Auf einem der Testcontainer war
`systemd-journald.service` kaputt (`failed`, `status=243/CREDENTIALS`),
`journalctl` lieferte `No journal files were found.` Da der Dienst seit
v0.4.1 **ausschliesslich** nach journald loggt (kein FileHandler, kein
Logverzeichnis — bewusste Entscheidung), gibt es dann gar keine Dienstlogs:
ein blinder Fleck, der vor jeder Fehlersuche per
`systemctl status systemd-journald` auszuschliessen ist. Als Notbehelf ist
der Vordergrund-Aufruf dokumentiert
(`cd /opt/pdf-ocr-hotfolder && sudo -u pdfocr ./venv/bin/python -m
pdf_ocr_hotfolder --config ...`, das `cd` ist zwingend, s. 0.6.2).
Ausdruecklich festgehalten: das ist **kein** generelles LXC-Muster — der
zweite Testcontainer war in Ordnung, es war Schaden auf genau dieser
Maschine.
### Changed
- `AI_AGENT_BRIEFING.md`: der Kommentar zu `requirements.txt` in der
Projektstruktur nannte noch "ocrmypdf 16.x!" — genau die Version, die seit
0.6.1 als unbrauchbar gilt und gegen die der Pin schuetzt. Korrigiert auf
17.x.
## [0.6.2] - 2026-09-22
### Fixed