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
- Konfiguration des Docker-Containers
- Installation von Docker und Docker-Compose
- Docker-Container erstellen
- Sprachpakete hinzufügen
- Bereitstellung von Stirling-PDF
Funktionsübersicht
- PDFs in mehrere Dateien mit bestimmten Seitenzahlen aufteilen
oder alle Seiten als einzelne Dateien extrahieren - mehrere PDFs zu einer einzigen Datei zusammenführen
- Konvertieren von PDFs in und aus Bildern
- PDF-Seiten in verschiedenen Reihenfolgen umsortieren
- Hinzufügen von Bildern zu PDFs an bestimmten Stellen
- PDFs drehen (90-Grad-Schritte)
- PDFs komprimieren
- Hinzufügen und Entfernen von Passwörtern
- PDF-Berechtigungen festlegen
- Wasserzeichen hinzufügen
- Konvertieren aller gängigen Dateien in PDF
- Extraktion von Bildern aus PDFs
- OCR (Texterkennung)
- Bearbeitung von Meta-Daten
- Benutzerdefinierte Download-Optionen
- Parallele Dateiverarbeitung und Downloads
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.
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
:
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:
Die Definition des Docker-Containers ist damit abgeschlossen.
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:
Nach der Bestätigung mit der Taste J
(oder Y
, wenn keine dt. Lokalisation vorliegt) ...
... werden die Pakete heruntergeladen, entpackt ...
... und eingerichtet:
Docker und Docker-Compose sind jetzt betriebsbereit.
Docker-Container erstellen
In dem Verzeichnis, in dem auch die docker-compose.yml liegt, wird der Befehl docker-compose up -d
abgesetzt:
Daraufhin werden die benötigten Daten angefordert ...
... ausgepackt ...
... sowie der Container erstellt und in Betrieb genommen (Meldung done):
Ab jetzt ist Stirling-PDF verfügbar.
(In diesem Beispiel via http://IP-Adresse:8080)
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:
Auf der Übersichtsseite aller verfügbaren Sprachpakete wird die URL des zu installierenden Paketes (in diesem Beispiel deutsch) ermittelt und kopiert:
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
.
Nach dem Download enthält das Verzeichnis trainingData die entsprechende Sprachdatei:
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.
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.
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.
Ausgangslage und Zielsetzung
Das hier behandelte Szenario basiert auf folgender Infrastruktur:
- Zur Verfügung stehen eine IPv4-Adresse und ein IPv6-Subnet (Standard 64-Bit).
Die IPv4-Adresse ist einem Proxmox-Server zugewiesen, der diverse virtuelle Maschinen beherbergt, die sich in einem separaten Netzwerk (Brücke mit NAT) befinden.
Das IPv6-Subnet wird ebenfalls vom Proxmox-Server verwaltet und über geroutete Brücken an die virtullen Maschinen verteilt. - Eine dieser virtuellen Maschinen stellt einen Webserver Apache 2.4 als ReverseProxy zur Verfügung.
Der Traffic, der beim Proxmox-Host auf den Ports 80 (HTTP) und 443 (HTTPS) ankommt, wird direkt zu diesem ReverseProxy durchgeleitet. - Stirling-PDF läuft auf einer weiteren virtuellen Maschinen.
- Die VM mit Stirling-PDF ist nicht direkt von außen zu erreichen:
Zwar könnte sie über eine IPv6-Adresse aus dem bereit gestellten Subnetz angesprochen werden -
aber damit wären all die Nutzer ausgeschlossen, die nur über eine IPv4-Anbindung verfügen.
Eine weitere (individuelle) IPv4-Adresse (nur für Stirling-PDF) scheidet aus Ressourcengründen (Kosten und Verfügbarkeit) aus.
Stirling-PDF wird über Port 8080 bereit gestellt -
dieser ist jedoch aus manchen Netzwerken nicht zu erreichen, weil insbesondere Unternehmensnetzwerke häufig sehr restriktive Firewall-Regeln haben und häufig nur HTTPS via Port 443 erlauben.
Eine Port-Weiterleitung von Port 80 am Host auf Port 8080 zur VM mit Stirling-PDF scheidet aus, weil Port 80 am Host bereits anderweitig belegt ist.
Ziel ist es, die Anwendung Stirling-PDF per sicherem HTTPS über den Standard-Port (443) zur Verfügung zu stellen.
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.