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

```bash
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:

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

Test:

```bash
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`](config.example.toml). Wichtigste Sektionen:

### `[ocr]`
```toml
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]`
```toml
enabled = true
url = "https://cloud.example.com"
username = "scanuser"
password = "app-password"
remote_path = "Scans/Inbox"
```

### `[upload.sftp]`
```toml
enabled = true
host = "sftp.example.com"
username = "scanuser"
key_file = "/etc/pdf-ocr-hotfolder/sftp_key"
remote_path = "/uploads"
```

### `[notify.email]`
```toml
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

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

## Update

```bash
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:

```bash
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
```bash
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:
```bash
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