Stirling-PDF: der PDF-Werkzeugkasten auf dem eigenen Server

„PDF zusammenfügen online“, „PDF komprimieren kostenlos“ – für solche Aufgaben lädt man seine Dokumente sonst auf irgendeinen Webdienst hoch, oft mit vertraulichen Inhalten. Stirling-PDF macht dasselbe auf deinem eigenen Server: über 50 PDF-Werkzeuge, deine Dateien verlassen nie deine Kontrolle.

Was bauen wir?

Einen kompletten PDF-Werkzeugkasten mit Stirling-PDF v2.14.3 hinter Traefik, abgesichert mit Login. Am Ende führst du PDFs zusammen, komprimierst und drehst sie, wandelst zwischen Formaten um, machst gescannte Dokumente per OCR durchsuchbar, schwärzt Inhalte, fügst Passwörter oder Wasserzeichen hinzu – alles im Browser, alles lokal. Genau das richtige Werkzeug, um die Dokumente aus Paperless oder Nextcloud vorzubereiten.

Das Standard-Image bringt alles mit, was die Werkzeuge brauchen: LibreOffice für Office-Konvertierungen, Tesseract 5.3.4 für OCR samt fünf Sprachpaketen, qpdf für Reparaturen und Calibre für E-Book-Formate. Dafür ist es mit 3,4 GB kein Leichtgewicht – plane den Platz auf der Systemplatte ein.

Voraussetzungen

• Ein Server mit laufendem Traefik und Docker Compose
• Eine Subdomain, die auf den Server zeigt – im Folgenden DEINE_DOMAIN
• Rund 4 GB freier Plattenplatz für das Image und mindestens 2 GB RAM; der Container belegt gut 1 GB Arbeitsspeicher

Schritt für Schritt

Schritt 1: Projekt und Compose-Datei

Stirling-PDF ist im Kern zustandslos – es verarbeitet Dateien und gibt sie zurück, ohne sie dauerhaft zu speichern. Nur Konfiguration und OCR-Sprachdaten liegen in Volumes. Lege das Projekt an:

mkdir -p /opt/stirling/data /opt/stirling/configs && cd /opt/stirling

Die beiden Ordner werden gleich als Bind Mounts eingehängt: configs hält Benutzerkonten und Einstellungen, data ist der Ablageort für zusätzliche OCR-Sprachen.

Die compose.yaml – ersetze DEINE_DOMAIN:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:2.14.3
    restart: unless-stopped
    volumes:
      - ./data:/usr/share/tessdata   # OCR-Sprachdaten
      - ./configs:/configs           # Konfiguration
    environment:
      LANGS: 'de_DE'                  # UI-Sprache
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.stirling.rule=Host(`DEINE_DOMAIN`)"
      - "traefik.http.routers.stirling.entrypoints=websecure"
      - "traefik.http.routers.stirling.tls.certresolver=le"
      - "traefik.http.services.stirling.loadbalancer.server.port=8080"

networks:
  proxy:
    external: true

Der Container veröffentlicht keinen Port nach außen – Traefik erreicht ihn über das gemeinsame proxy-Netz auf Port 8080. So ist der Dienst ausschließlich über HTTPS erreichbar.

Schritt 2: Starten und auf „healthy" warten

docker compose up -d

Das Image bringt einen eigenen Healthcheck mit, und Traefik leitet erst auf den Container, wenn dieser healthy ist. Das dauert nach dem Start etwa 20–30 Sekunden – die Java-Anwendung braucht einen Moment. Solange antwortet die Domain mit einem Traefik-404, danach springt sie auf die Anmeldeseite um. Das ist kein Fehler, sondern genau die Absicht: ein halb gestarteter Dienst geht nicht ins Netz.

Prüfe den Status:

docker compose ps --format "table {{.Name}}\t{{.Image}}\t{{.Status}}"

NAME                      IMAGE                               STATUS
stirling-stirling-pdf-1   stirlingtools/stirling-pdf:2.14.3   Up 47 seconds (healthy)

Steht dort (health: starting), warte noch einen Moment. Erst wenn (healthy) erscheint, ist die Route live.

Schritt 3: Erster Login und Pflicht-Passwortwechsel

Öffne https://DEINE_DOMAIN/. Stirling-PDF v2 ist standardmäßig durch einen Login geschützt – ein wichtiger Unterschied zu vielen anderen Tools, das solltest du nicht deaktivieren, wenn der Dienst öffentlich erreichbar ist.

Melde dich mit den Standarddaten admin / stirling an. Danach kommen zwei Dialoge nacheinander, und der erste hat es für ein Datenschutz-Setup in sich: Stirling-PDF fragt, ob du Opt-in-Analytics aktivieren möchtest. Wenn du den Dienst gerade deshalb selbst hostest, damit nichts nach außen fließt, ist hier Nein die passende Antwort – die Telemetrie bleibt dann aus.

Direkt danach erzwingt Stirling-PDF den Passwortwechsel. Das Formular verlangt mindestens 8 Zeichen und eine Bestätigung:

Nach dem Speichern wirst du abgemeldet und landest wieder auf der Anmeldeseite. Das ist normal: Melde dich erneut an, diesmal mit dem neuen Passwort.

Schritt 4: Der Werkzeugkasten

Nach dem Login siehst du die Oberfläche: links deine Dateien, rechts der komplette Werkzeugkatalog, gruppiert in Kategorien wie Signierung, Dokumentensicherheit und Verifizierung.

Beim ersten Öffnen blendet die Anwendung noch ein „Willkommen bei Stirling V2"-Fenster ein; schließe es mit dem X oben rechts.

Der Einstieg ist immer gleich: Eine PDF per Vom Computer hochladen laden (oder per Drag & Drop), dann das gewünschte Werkzeug rechts wählen. Die Datei erscheint im eingebauten Viewer:

Die nützlichsten Werkzeuge im Alltag:

• Zusammenführen / Aufteilen: mehrere PDFs zu einer vereinen oder Seiten heraustrennen.
• Komprimieren: die Dateigröße für den Mailversand reduzieren.
• Umwandeln: PDF ↔ Bild, Word/Office → PDF und zurück.
• OCR & Scans bereinigen: gescannte Dokumente durchsuchbar machen (dafür sind die tessdata-Sprachdaten da).
• Schwärzen: vertrauliche Stellen dauerhaft entfernen – nicht nur schwarz übermalen.

Jedes Werkzeug arbeitet auf den Dateien, die links ausgewählt sind – das Ergebnis ersetzt die Auswahl im Arbeitsbereich, bis du es herunterlädst.

Schritt 5: Zwei PDFs zusammenführen

Der häufigste Handgriff im Alltag, einmal komplett durchgespielt: Lade beide PDFs in einem Rutsch hoch – die Dateiliste links zeigt sie mit Datum und Seitenzahl, etwa a.pdf · 1 Page. Wähle rechts Zusammenführen. Das Panel führt durch drei Stufen:

1. Dateien – hier steht, wie viele Dokumente ausgewählt sind.
2. Sort Files – „Dateien werden in der Reihenfolge zusammengeführt, in der sie ausgewählt wurden. Ziehen Sie zum Neuordnen oder sortieren Sie unten." Die Reihenfolge ist also nicht zufällig, sondern deine Auswahlreihenfolge; per Drag & Drop oder über Sortieren nach änderst du sie.
3. Settings – zwei Schalter: digitale Signatur im Ergebnis entfernen und ein Inhaltsverzeichnis erzeugen.

Ein Klick auf Zusammenführen (2 Dateien) erzeugt eine neue Datei mit dem Präfix merged_, etwa merged_a.pdf mit beiden Seiten in der erwarteten Reihenfolge. Unter Überprüfen liegen Rückgängig und Herunterladen – und darunter bietet Stirling-PDF direkt die nächsten sinnvollen Werkzeuge an (Compress, Convert, Sanitize, Split, OCR), damit du das Ergebnis weiterverarbeiten kannst, ohne es zwischendurch herunterzuladen.

Schritt 6: OCR an einem echten Scan

OCR ist das Werkzeug, für das sich der eigene Server am meisten lohnt: Ein Scan mit Rechnungs- oder Vertragsdaten hat auf einem fremden Webdienst nichts verloren. Der Ablauf hat vier Stufen, die die Oberfläche rechts durchnummeriert.

Lade eine gescannte PDF hoch (ein reines Bild ohne Textebene) und wähle rechts OCR & Scans bereinigen. Unter Einstellungen stehen zwei Dinge zur Wahl:

• OCR-Modus: „Auto" überspringt Seiten, die schon Text enthalten, „Erzwingen" erfasst alles neu und ersetzt den vorhandenen Text, „Strikt" bricht ab, sobald auswählbarer Text gefunden wird. Für einen echten Scan ist „Auto" richtig.
• Sprachen: die erwarteten Dokumentsprachen – mehrere sind erlaubt, das verbessert die Trefferquote.

Ein Klick auf OCR verarbeiten und überprüfen startet den Lauf. Eine einseitige A4-Rechnung ist nach rund 3 Sekunden fertig; unter Punkt 4 liegt das Ergebnis zum Prüfen und Herunterladen bereit:

Die Datei wächst dabei nur wenig (etwa von 42 auf 49 KB), denn OCR legt eine unsichtbare Textebene hinter das Bild. Das Aussehen des Scans bleibt also unverändert, aber Suchen, Markieren und Kopieren funktionieren – und Werkzeuge wie Paperless finden den Inhalt anschließend im Volltext.

Schritt 7: OCR-Sprachen ergänzen

Das Standard-Image bringt fünf Sprachen mit, die sofort im OCR-Werkzeug auswählbar sind: Deutsch, Englisch, Französisch, Portugiesisch und Chinesisch. Brauchst du eine weitere, legst du die passende .traineddata-Datei in den gemounteten data-Ordner. Für Spanisch zum Beispiel:

cd /opt/stirling/data
curl -fsSL -O https://github.com/tesseract-ocr/tessdata_fast/raw/main/spa.traineddata

Die Sprachdateien stammen aus dem offiziellen Tesseract-Repository; tessdata_fast ist die schnelle Variante und für Scans völlig ausreichend (gut 2 MB je Sprache). Danach die Anwendung neu starten, damit sie das Verzeichnis neu einliest:

cd /opt/stirling && docker compose restart

Nach dem Neustart steht die Sprache in der Auswahlliste des OCR-Werkzeugs – „Spanisch" taucht dann direkt unter den mitgelieferten Sprachen auf.

Wenn es nicht funktioniert

Dein Problem ist nicht dabei? Alle Fehlermeldungen durchsuchen →

Wartung & Backups

• Updates. Setze den Image-Tag (stirlingtools/stirling-pdf:2.14.3) gelegentlich auf die aktuelle Version und docker compose up -d. Stirling-PDF wird aktiv entwickelt und bekommt häufig neue Werkzeuge; ein Blick in die Release-Notes lohnt sich. Weil das Image groß ist, räumst du nach dem Update mit docker image prune die alte Schicht weg. Der Rest läuft über deinen normalen Update-Prozess.
• Backup ist klein. Weil die Dateiverarbeitung zustandslos ist, musst du nur den configs-Ordner (Login, Einstellungen) und ggf. eigene OCR-Sprachdaten sichern – am besten mit Restic. Die verarbeiteten PDFs speicherst du ohnehin selbst.
• Ressourcen im Blick behalten. Der Container belegt rund 1 GB RAM im Ruhezustand; ein OCR- oder Konvertierungslauf kommt kurzzeitig obendrauf. Läuft auf demselben Server noch eine schwere Anwendung, lohnt ein Speicherlimit in der Compose-Datei.
• Sicherheit. Der Login ist die erste Verteidigungslinie – halte das Admin-Passwort stark und aktuell. Da hier potenziell vertrauliche Dokumente durchlaufen, ist der Betrieb hinter HTTPS (Traefik) und Login Pflicht; ein öffentlich erreichbares Stirling-PDF ohne Passwort wäre ein ernstes Datenleck. Wer den Werkzeugkasten nur selbst nutzt, legt am besten eine zweite Hürde davor: eine Traefik-Middleware mit Basic-Auth oder IP-Beschränkung oder gleich den Betrieb nur im VPN.