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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user