pdf-ocr-hotfolder/README.md

PDF OCR Hotfolder

Verwandelt eingehende gescannte PDFs automatisch in durchsuchbare PDFs (PDF/A optional) per OCR. Hauptanwendung: Kunden-Scanner schiebt PDF in einen Ordner — Sekunden später liegt die OCR-Version im Ausgang oder wird in Nextcloud / per SFTP weitergeleitet.

Features

• 🔍 OCR via ocrmypdf + Tesseract (Library-Call, kein Subprozess-Overhead)
• 📂 Hotfolder via watchdog — reagiert auf created, moved, closed Events
• 🧠 Stabilitäts-Erkennung: wartet bis Scanner fertig geschrieben hat
• 🔁 Parallelverarbeitung mehrerer PDFs (ThreadPool, konfigurierbar)
• ✅ PDF/A-Output (1, 2 oder 3) optional
• 🛡️ veraPDF-Validierung optional
• ☁️ Upload-Ziele: lokaler Ordner, Nextcloud (WebDAV via Python), SFTP
• 📧 E-Mail-Notify (immer / nur Fehler / nie)
• 🔐 Service-User-Support für lokale und AD-User mit lokaler UID (SSSD/Winbind)
• ⚙️ Saubere systemd-Integration mit auto-Restart

Schnellstart

git clone https://gitea.sonith.de/sonith_ug/pdf-ocr-hotfolder.git
cd pdf-ocr-hotfolder
sudo ./install.sh

Der Installer fragt nach dem Service-User. Standardmäßig wird ein lokaler System-User pdfocr angelegt. Wenn der User bereits existiert (z.B. AD via SSSD), wird er einfach übernommen.

Danach Konfiguration anpassen:

sudo nano /etc/pdf-ocr-hotfolder/config.toml
sudo systemctl restart pdf-ocr-hotfolder

Test:

cp irgendein-scan.pdf /var/lib/pdf-ocr-hotfolder/incoming/
journalctl -u pdf-ocr-hotfolder -f

Nach wenigen Sekunden liegt das OCR-PDF unter /var/lib/pdf-ocr-hotfolder/outgoing/OCR_irgendein-scan.pdf.

Verzeichnisse

Pfad	Zweck
/etc/pdf-ocr-hotfolder/config.toml	Konfiguration
/var/lib/pdf-ocr-hotfolder/incoming	Eingang (Scanner schreibt hier rein)
/var/lib/pdf-ocr-hotfolder/working	Arbeitsverzeichnis während OCR
/var/lib/pdf-ocr-hotfolder/outgoing	Ausgang (fertige PDFs)
/var/lib/pdf-ocr-hotfolder/error	PDFs, die nicht verarbeitet werden konnten
/opt/pdf-ocr-hotfolder/	Code + venv
/var/log/pdf-ocr-hotfolder/	Logs (zusätzlich zu journald)

Konfiguration

Vollständiges Beispiel: config.example.toml. Wichtigste Sektionen:

[ocr]

languages = "deu+eng"   # Tesseract-Sprachen
jobs = 4                 # Threads pro PDF
skip_text = true         # bereits OCR-haltige Seiten überspringen
pdfa_level = "2"         # "1", "2", "3" oder "" für reines PDF
deskew = true
max_workers = 2          # parallele PDFs
timeout = 1800

[upload.nextcloud]

enabled = true
url = "https://cloud.example.com"
username = "scanuser"
password = "app-password"
remote_path = "Scans/Inbox"

[upload.sftp]

enabled = true
host = "sftp.example.com"
username = "scanuser"
key_file = "/etc/pdf-ocr-hotfolder/sftp_key"
remote_path = "/uploads"

[notify.email]

enabled = true
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_user = "alerts@example.com"
smtp_password = "secret"
from_addr = "PDF OCR <alerts@example.com>"
to_addrs = ["admin@example.com"]
on = "errors"   # always | errors | never

Service-Verwaltung

sudo systemctl status pdf-ocr-hotfolder
sudo systemctl restart pdf-ocr-hotfolder
journalctl -u pdf-ocr-hotfolder -f

Update

cd /pfad/zum/repo
git pull
sudo ./update.sh

Das Repo muss bestehen bleiben — update.sh kopiert daraus.

Manueller Lauf (One-Shot)

Bestehende PDFs im Eingang einmalig verarbeiten und beenden:

sudo -u pdfocr /opt/pdf-ocr-hotfolder/venv/bin/python -m pdf_ocr_hotfolder \
    --config /etc/pdf-ocr-hotfolder/config.toml --once

Troubleshooting

Tesseract findet die Sprache nicht

sudo apt install tesseract-ocr-deu tesseract-ocr-eng

"PriorOcrFoundError"

ocrmypdf erkennt bereits vorhandenen OCR-Text. skip_text = true in der Config setzen.

Berechtigungsprobleme bei AD-User

Service-User braucht rw auf alle vier Verzeichnisse unter /var/lib/pdf-ocr-hotfolder/. Bei AD-User mit lokaler UID:

sudo chown -R DOMAIN\\scanuser:DOMAIN\\scangroup /var/lib/pdf-ocr-hotfolder

veraPDF-Validierung schlägt immer fehl

veraPDF binary prüfen ([verapdf].binary). Wenn nicht zwingend gebraucht: enabled = false.

Architektur

   ┌──────────┐    watchdog     ┌──────────────┐    ocrmypdf    ┌──────────┐
   │ Scanner  │ ──────────────▶ │   incoming/  │ ─────────────▶ │ working/ │
   └──────────┘   PDF-Datei     └──────────────┘   (Library)    └────┬─────┘
                                                                     │
                                                              optional veraPDF
                                                                     │
                                                                     ▼
                                                              ┌──────────────┐
                                                              │  outgoing/   │
                                                              └──────┬───────┘
                                                                     │
                                              ┌──────────────────────┼──────────────────────┐
                                              ▼                      ▼                      ▼
                                       ┌────────────┐        ┌────────────┐        ┌────────────┐
                                       │ Nextcloud  │        │    SFTP    │        │  E-Mail    │
                                       │  (WebDAV)  │        │ (paramiko) │        │  Notify    │
                                       └────────────┘        └────────────┘        └────────────┘

Lizenz

MIT — © Sonith UG

---

Version: 0.1.0 Repo: https://gitea.sonith.de/sonith_ug/pdf-ocr-hotfolder