OCR Server

Der OCR Server ist ein optionaler Bestandteil von WWS MAX, der die Texterkennung in PDF-Dokumenten ermöglicht. Mit dem OCR Server können gescannte Dokumente in durchsuchbare PDF-Dateien umgewandelt werden.

Die OCR-Funktion wird dabei nicht von WWS MAX selbst bereitgestellt, sondern über einen externen Dienst.

Für die Nutzung von OCR gibt es drei Möglichkeiten:

Den WWS Max OCR Server lokal auf den Arbeitsstationen installieren
- Manuelles OCR von Dateien per Kontextmenü aus dem Dateiexplorer von WWS Max.
- Nur auf der Arbeitsstation verfügbar, auf der der WWS Max OCR Server installiert wurde.
Siehe: Installation von WWS Max OCR Server auf den Arbeitsstationen
Den WWS Max OCR Server auf dem Server installieren, auf dem auch der Systemdienst von WWS Max installiert wurde.
- Automatisches OCR von Dateien, sobald diese in WWS Max abgelegt oder entdeckt werden.
- Manuelles OCR von Dateien per Kontextmenü aus dem Dateiexplorer von WWS Max von allen Arbeitsstationen aus.
  
  Hierzu muss die Option Clients benutzen den WWS Max Server in den OCR-Einstellungen aktiviert sein.
Siehe: Installation von WWS Max OCR Server auf dem Server
Einen eigenen OCR-Server betreiben (z.B. Linux mit OCRmyPDF)
- Automatisches OCR von Dateien, sobald diese in WWS Max abgelegt werden.
- Manuelles OCR von Dateien per Kontextmenü aus dem Dateiexplorer von WWS Max von allen Arbeitsstationen aus.
- Die Clients müssen eine Direktverbindung zum OCR-Server herstellen können.
Siehe: Installation von OCRmyPDF auf Linux

Installation von WWS Max OCR Server auf dem Server

Das vorgehen ist identisch mit der Installation auf den Arbeitsstationen. Der WWS Max OCR Server kann auf dem gleichen Server installiert werden, auf dem auch der WWS Max Systemdienst läuft.

Die Aktivierung kann in WWS Max unter Hauptmenü > Systemkonfiguration > Hintergrundaktionen (Server) überprüft werden.

Dort sollte unter Server bei Warteschlangen der Eintrag ocr angezeigt werden.

Installation von WWS Max OCR Server auf den Arbeitsstationen

Voraussetzungen prüfen
- Windows 10 oder Windows 11
- Multi-Core CPU
- Mindestens 8 GB RAM
WWS Max OCR Server herunterladen

Die aktuelle Version des WWS Max OCR Servers finden Sie auf der offiziellen Download-Seite.
OCR Server installieren

Installieren Sie auf jeder Arbeitsstation, die OCR-Funktionen nutzen soll, den WWS Max OCR Server.
WWS MAX konfigurieren
- Öffnen Sie in WWS MAX im Admin-Modus unter Hauptmenü > Systemkonfiguration > PDF OCR Einstellungen die Konfiguration.
- Stellen Sie die Betriebsart auf Lokaler OCR Server ein.

Installation von OCRmyPDF auf Linux

Dieses Beispiel bezieht sich auf die Installation von OCRmyPDF auf einem Linux-Server. Für andere Systeme können die Schritte abweichen.

Voraussetzungen prüfen

Docker und Docker Compose müssen bereits auf einem per SSH erreichbaren Linux-Server installiert sein.
Terminal window
```
sudo docker --version
sudo docker compose version
```
OCR-Service-Benutzer anlegen

Für die Kommunikation zwischen WWS MAX und dem OCR-Server wird ein eigener Benutzer ocrservice angelegt:
Terminal window
```
sudo adduser --disabled-password --gecos "" ocrservice
```
Anschließend ein Kennwort für die SSH- und SFTP-Anmeldung vergeben:
Terminal window
```
sudo passwd ocrservice
```
Dieses Kennwort wird später in WWS MAX hinterlegt.

Die Benutzerinformationen können anschließend geprüft werden:
Terminal window
```
id ocrservice
```
Eine typische Ausgabe sieht beispielsweise so aus:
```
uid=1001(ocrservice) gid=1001(ocrservice) groups=1001(ocrservice)
```
Installations- und Job-Verzeichnis anlegen

Das Installationsverzeichnis und das von WWS MAX verwendete Job-Verzeichnis anlegen:
Terminal window
```
sudo mkdir -p /opt/ocrmypdf/jobs
```
Der Benutzer ocrservice benötigt nur innerhalb des Job-Verzeichnisses Schreib- und Leserechte:
Terminal window
```
sudo chown -R ocrservice:ocrservice /opt/ocrmypdf/jobs
sudo chmod 2770 /opt/ocrmypdf/jobs
```
Das übergeordnete Installationsverzeichnis kann weiterhin administrativ verwaltet werden:
Terminal window
```
sudo chown root:root /opt/ocrmypdf
sudo chmod 755 /opt/ocrmypdf
```
Die Berechtigungen kontrollieren:
Terminal window
```
ls -ld /opt/ocrmypdf
ls -ld /opt/ocrmypdf/jobs
```
Der Schreibzugriff des Service-Benutzers kann getestet werden:
Terminal window
```
sudo -u ocrservice touch /opt/ocrmypdf/jobs/test.txt
sudo -u ocrservice rm /opt/ocrmypdf/jobs/test.txt
```
Benutzer- und Gruppen-ID für den Container speichern

Der OCRmyPDF-Container soll unter der gleichen Benutzer- und Gruppen-ID wie ocrservice ausgeführt werden. Dadurch gehören vom Container erzeugte PDF-Dateien auch auf dem Linux-Host dem Benutzer ocrservice.

Die Datei /opt/ocrmypdf/.env mit UID und GID von ocrservice erzeugen:
Terminal window
```
sudo sh -c 'printf "OCR_UID=%s\nOCR_GID=%s\n" "$(id -u ocrservice)" "$(id -g ocrservice)" > /opt/ocrmypdf/.env'
```
Die Konfigurationsdatei soll nur administrativ verändert werden können:
Terminal window
```
sudo chown root:root /opt/ocrmypdf/.env
sudo chmod 644 /opt/ocrmypdf/.env
```
Inhalt kontrollieren:
Terminal window
```
cat /opt/ocrmypdf/.env
```
Eine typische Ausgabe sieht beispielsweise so aus:
```
OCR_UID=1001
OCR_GID=1001
```
In der .env müssen die UID und GID von ocrservice stehen. Werte wie OCR_UID=0 und OCR_GID=0 würden dazu führen, dass der Container als Root ausgeführt wird.

Docker-Compose-Datei erstellen

cd /opt/ocrmypdf

sudo tee compose.yaml > /dev/null <<'YAML'
services:
  ocrmypdf:
    image: jbarlow83/ocrmypdf-alpine
    container_name: ocrmypdf
    restart: unless-stopped

    user: "${OCR_UID}:${OCR_GID}"

    entrypoint:
      - /bin/sh
      - -c

    command:
      - while true; do sleep 3600; done

    volumes:
      - ./jobs:/jobs
YAML

Die Datei soll nur administrativ verändert werden können:

sudo chown root:root /opt/ocrmypdf/compose.yaml
sudo chmod 644 /opt/ocrmypdf/compose.yaml

Datei anzeigen:

cat /opt/ocrmypdf/compose.yaml

Compose-Konfiguration auf Syntaxfehler prüfen:

cd /opt/ocrmypdf
sudo docker compose config

Docker-Image herunterladen

cd /opt/ocrmypdf
sudo docker compose pull

Installierte OCRmyPDF-Version prüfen:

sudo docker run --rm \
  jbarlow83/ocrmypdf-alpine \
  --version

Verfügbare OCR-Sprachen prüfen
Terminal window
```
sudo docker run --rm \
  --entrypoint tesseract \
  jbarlow83/ocrmypdf-alpine \
  --list-langs
```
In der Ausgabe müssen mindestens folgende Sprachkennungen enthalten sein:
```
deu
eng
```
Falls deu fehlt, kann die deutsche OCR-Erkennung mit diesem Image nicht verwendet werden.

OCR-Container starten

cd /opt/ocrmypdf
sudo docker compose up -d

Containerstatus anzeigen:

sudo docker compose ps

Erwartete Ausgabe:

NAME       IMAGE                       STATUS
ocrmypdf   jbarlow83/ocrmypdf-alpine   Up

Prüfen, ob OCRmyPDF innerhalb des laufenden Containers verfügbar ist:

sudo docker exec ocrmypdf ocrmypdf --version

Geschütztes OCR-Skript erstellen

WWS MAX erhält keinen direkten Zugriff auf Docker. Stattdessen wird ein fest definiertes Skript angelegt, welches ausschließlich die benötigte OCRmyPDF-Verarbeitung ausführt.

Das Skript /usr/local/sbin/ocr-run erstellen:

sudo tee /usr/local/sbin/ocr-run > /dev/null <<'SH'
#!/bin/sh
set -eu

if [ "$#" -ne 2 ]; then
    echo "Usage: ocr-run <input-file> <output-file>" >&2
    exit 2
fi

INPUT="$1"
OUTPUT="$2"

# Nur einfache Dateinamen zulassen.
# Verzeichnispfade und Shell-Sonderzeichen sind nicht erlaubt.
case "$INPUT" in
    *[!A-Za-z0-9._-]*|"")
        echo "Invalid input filename" >&2
        exit 2
        ;;
esac

case "$OUTPUT" in
    *[!A-Za-z0-9._-]*|"")
        echo "Invalid output filename" >&2
        exit 2
        ;;
esac

# Versteckte Dateien und relative Pfadangaben verhindern.
case "$INPUT" in
    .*|".."*)
        echo "Invalid input filename" >&2
        exit 2
        ;;
esac

case "$OUTPUT" in
    .*|".."*)
        echo "Invalid output filename" >&2
        exit 2
        ;;
esac

if [ "$INPUT" = "$OUTPUT" ]; then
    echo "Input and output filenames must differ" >&2
    exit 2
fi

INPUT_PATH="/jobs/$INPUT"
OUTPUT_PATH="/jobs/$OUTPUT"

exec /usr/bin/docker exec ocrmypdf \
    ocrmypdf \
    -l deu+eng \
    --mode skip \
    --rotate-pages \
    --deskew \
    --output-type pdf \
    "$INPUT_PATH" \
    "$OUTPUT_PATH"
SH

Besitzer und Berechtigungen setzen:

sudo chown root:root /usr/local/sbin/ocr-run
sudo chmod 755 /usr/local/sbin/ocr-run

Berechtigungen kontrollieren:

ls -l /usr/local/sbin/ocr-run

Erwartet wird beispielsweise:

-rwxr-xr-x 1 root root ... /usr/local/sbin/ocr-run

Ausschließlich das OCR-Skript über sudo erlauben

Für ocrservice wird eine eigene sudo-Regel eingerichtet. Diese erlaubt ausschließlich die Ausführung von /usr/local/sbin/ocr-run mit Root-Rechten und ohne erneute Kennwortabfrage.

Die sudoers-Datei erstellen:
Terminal window
```
sudo tee /etc/sudoers.d/ocrservice > /dev/null <<'SUDOERS'
ocrservice ALL=(root) NOPASSWD: /usr/local/sbin/ocr-run
SUDOERS
```
Besitzer und zwingend erforderliche Zugriffsrechte setzen:
Terminal window
```
sudo chown root:root /etc/sudoers.d/ocrservice
sudo chmod 0440 /etc/sudoers.d/ocrservice
```
Dateien unter /etc/sudoers.d/ müssen korrekte Zugriffsrechte besitzen. Für diese Datei ist der Modus 0440 erforderlich.

Die sudo-Konfiguration anschließend validieren:
Terminal window
```
sudo visudo -c
```
Die Ausgabe sollte unter anderem enthalten:
```
/etc/sudoers: Syntax OK
/etc/sudoers.d/ocrservice: Syntax OK
```
Prüfen, welche privilegierten Befehle ocrservice ausführen darf:
Terminal window
```
sudo -u ocrservice sudo -l
```
/usr/local/sbin/ocr-run muss dort als erlaubter NOPASSWD-Befehl erscheinen.
Einschränkung des Service-Benutzers testen optional / empfohlen

Zunächst prüfen, dass ocrservice keinen direkten Docker-Zugriff besitzt:
Terminal window
```
sudo -u ocrservice docker ps
```
Dieser Befehl soll mit einer Zugriffsverletzung fehlschlagen.

Auch Docker über sudo darf nicht erlaubt sein:
Terminal window
```
sudo -u ocrservice sudo docker ps
```
Dieser Befehl muss ebenfalls abgewiesen werden.

Dagegen muss das OCR-Skript grundsätzlich aufrufbar sein:
Terminal window
```
sudo -u ocrservice sudo /usr/local/sbin/ocr-run test-input.pdf test-output.pdf
```
Ohne vorhandene gültige Eingabedatei wird OCRmyPDF zwar InputFileError: File not found melden, der Aufruf des Skripts selbst muss jedoch von sudo erlaubt werden.
OCR-Verarbeitung mit einer PDF testen optional

Eine Test-PDF in das Job-Verzeichnis kopieren:
Terminal window
```
sudo cp /pfad/zur/test.pdf /opt/ocrmypdf/jobs/test-input.pdf
```
Der Datei ocrservice als Besitzer zuweisen:
Terminal window
```
sudo chown ocrservice:ocrservice /opt/ocrmypdf/jobs/test-input.pdf
```
OCR-Verarbeitung als ocrservice starten:
Terminal window
```
sudo -u ocrservice sudo /usr/local/sbin/ocr-run test-input.pdf test-output.pdf
```
Anschließend das Ergebnis prüfen:
Terminal window
```
ls -lh /opt/ocrmypdf/jobs/test-input.pdf
ls -lh /opt/ocrmypdf/jobs/test-output.pdf
```
Wenn test-output.pdf erzeugt wurde, funktionieren Dateirechte, Docker-Volume und das OCR-Skript korrekt zusammen.

Testdateien anschließend löschen:
Terminal window
```
sudo -u ocrservice rm /opt/ocrmypdf/jobs/test-input.pdf
sudo -u ocrservice rm /opt/ocrmypdf/jobs/test-output.pdf
```
SSH- und SFTP-Zugriff testen optional

Von einem anderen Rechner kann die Anmeldung mit dem zuvor vergebenen Kennwort getestet werden:
Terminal window
```
ssh ocrservice@<Hostname oder IP-Adresse>
```
Nach erfolgreicher Anmeldung:
Terminal window
```
whoami
```
Erwartete Ausgabe:
```
ocrservice
```
Den Schreibzugriff auf das Job-Verzeichnis prüfen:
Terminal window
```
touch /opt/ocrmypdf/jobs/ssh-test.txt
rm /opt/ocrmypdf/jobs/ssh-test.txt
```
Den erlaubten OCR-Befehl prüfen:
Terminal window
```
sudo /usr/local/sbin/ocr-run test-input.pdf test-output.pdf
```
Der Benutzer besitzt weiterhin keine Berechtigung für einen direkten Docker-Zugriff.
WWS MAX konfigurieren

In WWS MAX im Admin-Modus unter Hauptmenü > Systemkonfiguration > PDF OCR Einstellungen die Konfiguration zum OCR-Server eintragen.

Dies ist ein Minimalbeispiel, das an die jeweilige Umgebung angepasst werden muss:
- Allgemein
  - Betriebsart: SSH Job
- SSH
  - Benutzername: ocrservice
  - Kennwort: <Kennwort von ocrservice>
  - Hostname: <Hostname oder IP-Adresse des OCR-Servers>
  - Port: 22
  - Unbekannte Hosts akzeptieren: Ja
  - OCR Befehl: sudo /usr/local/sbin/ocr-run {input} {output}
- Verarbeitung
  - Zeitüberschreitung: 240 Sekunden
- Verzeichnisse
  - Job-Ordner: /opt/ocrmypdf/jobs
    
    Dies ist der Job-Ordner auf dem OCR-Server.
Wenn die Option Bevorzuge lokalen Server aktiviert ist, wird WWS MAX zunächst versuchen, den lokal installierten WWS Max OCR Server zu verwenden. Wenn dieser nicht verfügbar ist, wird auf den konfigurierten externen OCR-Server zurückgegriffen.

WWS MAX führt die Verarbeitung anschließend nach folgendem Schema aus:
1. Falls Bilder für OCR ausgewählt wurden, werden diese zunächst in PDF-Dateien umgewandelt.
2. Es wird geprüft, ob die PDF-Dateien bereits durchsuchbar sind.
3. PDF per SFTP nach /opt/ocrmypdf/jobs übertragen.
4. sudo /usr/local/sbin/ocr-run {input} {output} per SSH ausführen
5. Auf das Ende des OCR-Befehls warten
6. Ausgabe-PDF per SFTP herunterladen und Original ersetzen
7. Temporäre Ein- und Ausgabedateien per SFTP löschen
Die Platzhalter {input} und {output} enthalten dabei nur die jeweiligen Dateinamen. Das serverseitige Skript legt fest, dass ausschließlich Dateien innerhalb von /jobs im Docker-Container verarbeitet werden können.

Die Option Unbekannte Hosts akzeptieren kann für die erste Einrichtung verwendet werden. Für den produktiven Betrieb sollte der SSH-Hostschlüssel geprüft und dessen SHA256-Fingerabdruck in WWS MAX hinterlegt werden.

Starten Sie nach der Aktivierung oder Deaktivierung der OCR Funktion den WWS Max Systemdienst neu, damit die entsprechende Warteschlange angelegt oder entfernt wird.