Stirling PDF

Im Gegensatz zu anderen Online-PDF-Tools mit einem vergleichbaren Funktionsumfang hat Stirling PDF den Vorteil, dass die Daten nicht in Kontakt mit fremden Servern kommen: Die Daten verlassen nicht das eigene Netzwerk, sondern die Anwendung lässt sich lokal (bspw. innerhalb einer VM auf einem NAS) betreiben. In diesem Beispiel erfolgt die Installation via Docker-Container in einer virtuellen Maschine, auf der sich zuvor nur ein frisch installiertes Betriebssystem Debian Bookworm 12.5 befindet.

Funktionsübersicht

Installation

Diese Schritt-für-Schritt-Anleitung beschreibt alle Maßnahmen, die bei einem frisch installierten Debian Linux (hier: Version 12.5 Bookworm) nötig sind, um die Anwendung (extern) nutzen zu können.

Installation

Konfiguration des Docker-Containers

Wie bei Docker-Compose üblich wird der Container mit Hilfe einer speziellen Konfigurationsdatei (docker-compose.yml) spezifiziert.
Neben den Dateien des Docker-Containers sind zudem noch weitere Daten, bspw. in Form von Trainingsdaten für die Texterkennung, zu erwarten.

Um die Organisation der Dateien auf dem Server übersichtlich zu halten, empfiehlt es sich grundsätzlich für jeden (Server-)Dienst ein separates Verzeichnis zu nutzen.
In diesem Beispiel wird daher zunächst mit dem Befehl mkdir /srv/stirling ein neues Verzeichnis für Stirling-PDF erstellt und mittels cd /srv/stirling/ dorthin gewechselt.
Dort wird dann mit Hilfe eines Text-Editors die Konfigurationsdatei angelegt. Bei der Verwendung von nano lautet der Befehl somit nano docker-compose.yml:

01_Verzeichnis_anlegen.png

Die Konfigurationsdatei wird mit Daten nach diesem Schema erstellt:

version: '3.3'
services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    ports:
      - '8080:8080'
    volumes:
      - /srv/stirling/trainingData:/usr/share/tesseract-ocr/4.00/tessdata #Required for extra OCR languages
      - /srv/stirling/extraConfigs:/configs
      - /srv/stirling/customFiles:/customFiles/
    environment:
      - DOCKER_ENABLE_SECURITY=false
    restart: always

Unter ports wird definiert, über welchen Port (links anzugeben) die Anwendung, die im Container unter dem rechts angegebenen Port läuft, später von außen zu erreichen ist. Der Eintrag :8080 darf nicht verändert werden.
Soll Stirling-PDF später unter dem üblichen HTTP-Port 80 erreichbar sein, müsste der Eintrag auf '80:8080' geändert werden.
Bei volumes muss der Pfad angepasst werden, wenn nicht wie in diesem Beispiel /srv/stirling verwendet wird.

Mit der Tastenkombination STRG und X kann der Editor nano verlassen und die Datei nach Rückfrage gespeichert werden:

02_Konfiguration_anlegen.png

Die Definition des Docker-Containers ist damit abgeschlossen.

Installation

Installation von Docker und Docker-Compose

Auf einem frisch aufgesetzten Linux-Betriebssystem (wie hier Debian 12.5 Bookworm) ist in der Regel außer SSH kein weiterer Dienst - und somit auch kein Docker - verfügbar.

Daher gilt es zunächst Docker ("Betreiber des Containers") und Docker-Compose ("Zusammenbauer des Containers") in Betrieb zu nehmen.

Dafür werden als erstes die Paketquellen mittels apt update aktualisiert und ggf. Updates per apt upgrade (in diesem Beispiel nicht erforderlich, weil alle Pakete aktuell sind) eingespielt.
Im Anschluss daran werden Docker und Docker-Compose durch den Befehl apt install docker.io docker-compose gemeinsam installiert:

03a_Docker_installieren.png

Nach der Bestätigung mit der Taste J (oder Y, wenn keine dt. Lokalisation vorliegt) ...

03b_Docker_installieren.png

... werden die Pakete heruntergeladen, entpackt ...

03c_Docker_Installation.png

... und eingerichtet:

03d_Docker_installiert.png

Docker und Docker-Compose sind jetzt betriebsbereit.

Installation

Docker-Container erstellen

In dem Verzeichnis, in dem auch die docker-compose.yml liegt, wird der Befehl docker-compose up -d abgesetzt:

04a_Container_erstellen.png

Daraufhin werden die benötigten Daten angefordert ...

04b_Container_Download.png

... ausgepackt ...

04c_Container_auspacken.png

... sowie der Container erstellt und in Betrieb genommen (Meldung done):

04d_Container_erstellt.png

Ab jetzt ist Stirling-PDF verfügbar.
(In diesem Beispiel via http://IP-Adresse:8080)

Installation

Sprachpakete hinzufügen

In der Grundinstallation verfügt Stirling-PDF nur über das englischsprachige Paket für die Texterkennung.

Um bspw. deutschsprachige Texte verarbeiten zu können, bedarf es somit weiterer Sprachpakete.

Die optionalen Sprachpakete befinden sich unterhalb des Installationsverzeichnisses (hier /srv/stirling) im Verzeichnis trainingData.
Daher wird zunächst in dieses Verzeichnis gewechselt, das nach der Installation noch leer ist:

05a_Sprachdateien_Verzeichnis.png

Auf der Übersichtsseite aller verfügbaren Sprachpakete wird die URL des zu installierenden Paketes (in diesem Beispiel deutsch) ermittelt und kopiert:

05b_Sprachdateien_Links.png

Im Verzeichnis der Sprachpakete kann die gewünschte Datei dann mittels wget URL empfangen werden.
Für das Beispiel lautet der gesamte Befehl somit wget https://github.com/tesseract-ocr/tessdata_fast/blob/main/deu.traineddata.

05c_Sprachdateien_Link_laden.png

Nach dem Download enthält das Verzeichnis trainingData die entsprechende Sprachdatei:

05d_Sprachdateien_geladen.png

Obwohl die Datei jetzt vorhanden ist, weiß die Anwendung (Stirling-PDF) noch nichts von ihr.
Hierfür muss abschließend der Container neu gestartet werden.
Im ersten Schritt wird die laufende Anwendung per docker-compose down heruntergefahren und im zweiten Schritt durch docker-compose up -d wieder gestartet.

05e_Container_Neustart.png

Das zusätzliche Sprachpaket steht Stirling-PDF ab sofort zur Verfügung.

Bereitstellung von Stirling-PDF

Dieser Abschnitt beschreibt, wie Stirling-PDF normalerweise aufgerufen wird und wie sich dies optimieren lässt.

Bereitstellung von Stirling-PDF

Zugang zur Anwendung

Out-of-the-Box ist Stirling-PDF nach dem Schema HTTP://IP-ADRESSE:PortNummer erreichbar,
konkret bedeutet dies bspw.:
bei IPv4 http://1.2.3.4:8080
bei IPv6 http://[2:3:4:5:a:b:c:d]:8080

Die Bereitstellung von Diensten per unverschlüsseltem HTTP ist unzeitgemäß und ein Sicherheitsrisiko.

Außerdem ist der Port 80 (Standard-Port für HTTP) häufig bereits durch einen (anderen) Webserver belegt und alternative Ports (hier 8080) können häufig aufgrund restriktiver Firewall-Regeln bspw. in Unternehmensnetzwerken nicht erreicht werden.

 

Bereitstellung von Stirling-PDF

Ausgangslage und Zielsetzung

Das hier behandelte Szenario basiert auf folgender Infrastruktur:

Ziel ist es, die Anwendung Stirling-PDF per sicherem HTTPS über den Standard-Port (443) zur Verfügung zu stellen.

Bereitstellung von Stirling-PDF

Zugang per ReverseProxy

Die Konfiguration eines ReverseProxy und der Einsatz von Let's Encrypt werden in einem separaten Buch aufgegriffen.
Hier an dieser Stelle daher nur eine kurze Zusammenfassung.

Auf dem ReverseProxy (hier ein Apache 2.4 Web-Server) wird für dieses Beispiel folgende Konfiguration (bspw. als /etc/apache2/sites-enabled/stirling.conf) angelegt:

<VirtualHost subdomain.schubert.si:80>
        ServerAdmin webmaster@schubert.si
        ServerName subdomain.schubert.si
        ServerSignature Off
        DocumentRoot /var/www/html/stirling
        RewriteEngine on
        RewriteCond %{SERVER_NAME} =subdomain.schubert.si
        RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Das unter DocumentRoot angegebene Verzeichnis ist nur ein Dummy mit einer leeren index.html-Datei.
Gebraucht wird das leere Verzeichnis nur für den Einsatz des Certbot von Let's Encrypt.

Auch wenn es zunächst so aussehen mag:
Es wird kein Dienst unter Port 80 (unverschlüsseltes HTTP) angeboten, sondern per Rewrite wird jeglicher Aufruf von HTTP auf HTTPS umgeschrieben.

Analog zur Konfiguration für Anfragen an Port 80 gibt es eine weitere Konfiguration (bspw. als /etc/apache2/sites-enabled/stirling-le-ssl.conf) oder als weiteren Abschnitt in der ersten Konfigurationsdatei, um eben die Anfragen an Port 443 (HTTPS) zu beantworten:

<IfModule mod_ssl.c>
<VirtualHost subdomain.schubert.si:443>
        ServerAdmin webmaster@schubert.si
        ServerName subdomain.schubert.si
        ServerSignature Off
        ProxyPreserveHost On
        ProxyPass / http://192.168.1.11:8080/
        ProxyPassReverse / http://192.168.1.11:8080/
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
        SSLCertificateFile /etc/letsencrypt/live/subdomain.schubert.si/fullchain.pem
        SSLCertificateKeyFile /etc/letsencrypt/live/subdomain.schubert.si/privkey.pem
        Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
</IfModule>

Hinter ProxyPass... wird die (interne) IPv4-Adresse der virtuellen Maschine angegeben, die Stirling-PDF bereitstellt.
Dafür müssen sich natürlich sowohl die VM mit dem ReverseProxy als auch die VM mit Stirling-PDF im gleichen Subnetz befinden.
Sollte der ReverseProxy auf der gleichen Maschine laufen wie Stirling-PDF selbst, wird stattdessen localhost (http://localhost:8080 oder http://127.0.0.1:8080) verwendet

Nach Anlage der Konfiguration muss diese Apache noch mittels systemctl reload apache2 bekannt gemacht werden.

Somit kann Stirling-PDF per HTTPS unter dem Standard-Port 443 anstatt über eine unverschlüsselte HTTP-Verbindung genutzt werden.