Stirling-PDF selbst hosten: Deine eigene iLovePDF-Alternative im Heimnetz

Mietvertrag, Gehaltsabrechnung, Arztbrief: Genau die Dokumente, die du mal eben zusammenfügen oder verkleinern willst, sind oft die, die du am wenigsten auf eine fremde Website hochladen möchtest. Mit Stirling-PDF hast du die bekannten Werkzeuge von Seiten wie iLovePDF oder Smallpdf auf deinem eigenen Server. Die Dateien verlassen dein Heimnetz nicht. In diesem Guide zeige ich dir, wie du Stirling-PDF einrichtest, absicherst und für deutsche Texte mit OCR fit machst.

Kurz erklärt

• Stirling-PDF ist eine Web-App mit über 50 PDF-Werkzeugen: zusammenfügen, teilen, drehen, schwärzen, komprimieren, umwandeln, Texterkennung und mehr.
• Du öffnest sie im Browser, wie eine Online-Seite. Die Verarbeitung passiert aber auf deinem eigenen Server.
• Gedacht für alle, die regelmäßig mit PDFs arbeiten und dabei keine privaten Dokumente an Dritte schicken wollen. Auch für die Familie im Heimnetz praktisch.
• Du brauchst einen kleinen Server, zum Beispiel einen Mini-PC mit Proxmox, oder irgendeinen Rechner mit Docker.

Warum nicht einfach iLovePDF?

Die Online-Dienste funktionieren gut. Sobald du aber eine Datei hochlädst, liegt sie für eine Weile auf fremden Servern, meist irgendwo, wo du keinen Einfluss hast. Für einen Flyer ist das egal. Für Steuerunterlagen oder eine Krankmeldung sieht das anders aus. Dazu kommen Limits in den Gratis-Versionen, zum Beispiel bei der Dateigröße oder der Anzahl der Aufgaben pro Tag. Stirling-PDF hat diese Limits nicht, weil du die Rechenleistung selbst stellst.

Bei mir läuft Stirling-PDF an beiden Standorten meines Homelabs in je einem eigenen LXC mit 2 Kernen und 2 GB RAM. Wie das Homelab aufgebaut ist, liest du in Mein Homelab an zwei Standorten.

Das brauchst du

• Einen Proxmox-Host oder einen Linux-Rechner mit Docker und Docker Compose.
• 2 CPU-Kerne, mindestens 2 GB RAM und rund 8 GB Speicherplatz. Das offizielle Docker-Image empfiehlt 4 GB RAM, für normale Dokumente reichen bei mir 2 GB.
• Eine feste IP für den Container, zum Beispiel per DHCP-Reservierung im Router.
• Etwa 20 Minuten Zeit. Der größte Teil davon ist Warten auf Downloads.

Ich nutze dafür einen Mini-PC von Minisforum . Stirling-PDF läuft aber auch auf deutlich schwächerer Hardware.

Schritt 1, Variante A: Installation auf Proxmox per Helper-Script

So habe ich es selbst gemacht. Die Proxmox VE Helper-Scripts sind eine Sammlung von Community-Scripts, die einen fertigen LXC anlegen. LXC ist ein schlanker Linux-Container, der weniger Ressourcen braucht als eine komplette virtuelle Maschine. Öffne die Shell deines Proxmox-Hosts und führe aus:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/stirling-pdf.sh)"

Bevor du ein fremdes Script als root ausführst, schau es dir kurz auf GitHub an. Das Script schlägt 2 Kerne, 2 GB RAM und 8 GB Disk auf Debian vor. Diese Werte kannst du so übernehmen. Während der Installation stellt es dir eine Frage: ob du Stirling-PDF mit Login verwenden willst. Drück einfach Enter, damit ist Login aktiv. Ohne Login kann jeder in deinem Netz das Tool benutzen und die Einstellungen ändern.

Das Script installiert Stirling-PDF nativ als Java-Anwendung unter /opt/Stirling-PDF und richtet einen systemd-Service namens stirlingpdf ein. Dazu kommen LibreOffice für Office-Umwandlungen und Tesseract für die Texterkennung. Es lädt alle Tesseract-Sprachpakete, also auch Deutsch. Das dauert eine Weile und belegt einige GB. In meinem Container sind von 8 GB inzwischen über 5 GB belegt. Plane die Disk also nicht kleiner.

Am Ende zeigt das Script die Adresse an, unter der Stirling-PDF erreichbar ist: http://192.168.1.x:8080.

Schritt 1, Variante B: Installation mit Docker Compose

Ohne Proxmox nimmst du das offizielle Docker-Image. Lege einen Ordner an und wechsle hinein:

mkdir ~/stirling-pdf && cd ~/stirling-pdf

Darin legst du eine Datei docker-compose.yml an:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline
      - ./stirling-data/storage:/storage
      - ./stirling-data/tessdata:/usr/share/tessdata
    environment:
      - SYSTEM_DEFAULTLOCALE=de-DE
    mem_limit: 4g
    restart: unless-stopped

Starte den Container mit:

docker compose up -d

Das Image mit dem Tag latest bringt Login und Admin-Einstellungen direkt mit. Es gibt außerdem latest-ultra-lite mit nur 2 GB RAM-Bedarf. Dort fehlen aber OCR und die Office-Umwandlung, deshalb rate ich für diesen Guide davon ab. Willst du Updates selbst steuern, ersetze latest durch eine feste Versionsnummer. Ein Update holst du dir im selben Ordner mit docker compose pull und danach docker compose up -d. Die Variable SYSTEM_DEFAULTLOCALE=de-DE stellt die Oberfläche für neue Nutzer auf Deutsch.

Schritt 2: Erster Login und Sicherheit

Öffne http://192.168.1.x:8080 im Browser. Bei beiden Varianten ist der Standard-Login laut offizieller Doku der Benutzer admin mit dem Passwort stirling. Diese Zugangsdaten kennt jeder, der die Doku gelesen hat. Bei Docker legt Stirling-PDF diesen Standard-Admin selbst an und fordert dich beim ersten Login auf, ein neues Passwort mit mindestens 8 Zeichen zu setzen. Das Helper-Script trägt admin und stirling dagegen über die Variablen SECURITY_INITIALLOGIN_USERNAME und SECURITY_INITIALLOGIN_PASSWORD in /opt/Stirling-PDF/.env ein. So angelegte Konten fragt Stirling-PDF laut Doku nicht nach einem neuen Passwort. Kommt bei dir keine Aufforderung, änder das Passwort direkt nach dem ersten Login selbst in deinen Kontoeinstellungen. Nimm in beiden Fällen ein langes, eigenes Passwort, am besten aus deinem Passwort-Manager.

Bei Docker kannst du den Standard-Admin auch ganz vermeiden. Setze dafür vor dem ersten Start zwei Variablen im environment-Block. Sie wirken nur, solange noch kein Nutzer existiert:

      - SECURITY_INITIALLOGIN_USERNAME=<dein-benutzername>
      - SECURITY_INITIALLOGIN_PASSWORD=<dein-passwort>

Weitere Nutzer, etwa für Familienmitglieder, legst du in den Einstellungen unter Workspace → Users über Invite people an. Ohne eingerichteten Mailversand wählst du dort Create account directly und vergibst Benutzername, Passwort und Rolle selbst. Die kostenlose Version erlaubt laut Hersteller bis zu 5 Nutzer, für ein Heimnetz reicht das. Nach 5 falschen Passworteingaben sperrt Stirling-PDF ein Konto für 120 Minuten.

Stell die Oberfläche nicht ungeschützt ins Internet. Für den Zugriff von unterwegs nimmst du ein VPN wie Tailscale oder einen Reverse Proxy mit HTTPS. Bei einem Reverse Proxy denk an das Upload-Limit: nginx erlaubt standardmäßig nur 1 MB pro Anfrage, große Scans scheitern dann. Wie ich meinen Caddy zusätzlich mit CrowdSec absichere, steht in CrowdSec mit Caddy und nftables.

Schritt 3: Die Werkzeuge, die du wirklich brauchst

Die Werkzeugliste ist lang. Über das Suchfeld findest du das passende Tool schneller als durch Scrollen. Diese vier nutze ich am häufigsten:

• Zusammenführen (Merge): Mehrere PDFs hochladen, Reihenfolge per Drag-and-drop festlegen, eine Datei herunterladen. Typisch für Bewerbungen oder Unterlagen für den Steuerberater.
• Schwärzen (Redact): Es gibt eine automatische Variante, die nach Wörtern wie deiner IBAN sucht, und eine manuelle, bei der du Bereiche markierst. Ein schwarzer Kasten allein verdeckt Text oft nur, darunter lässt er sich weiter kopieren. Lass deshalb bei sensiblen Dokumenten die Option aktiv, das Ergebnis in ein Bild-PDF umzuwandeln. Danach suchst du im fertigen PDF nach dem geschwärzten Wort. Findet die Suche nichts mehr, ist es weg.
• Komprimieren (Compress): Macht gescannte PDFs kleiner, damit sie durch das Upload-Limit von Behördenportalen passen. Je höher die Stufe, desto schlechter die Bildqualität. Probier eine mittlere Stufe zuerst.
• OCR: Erkennt Text in gescannten Seiten und legt ihn unsichtbar unter das Bild. Danach kannst du im PDF suchen und Text kopieren.

Daneben gibt es Seiten drehen, teilen, Seiten löschen, Wasserzeichen, Unterschrift, Umwandlung von Word oder Bildern in PDF und zurück. Mehrere Schritte kannst du zu einer Pipeline verketten, etwa erst OCR, dann komprimieren.

Schritt 4: OCR für deutsche Dokumente

Damit die Texterkennung Umlaute und deutsche Wörter sauber liest, wählst du im OCR-Tool die Sprache Deutsch aus. Das Tool zeigt nur Sprachen an, die auf dem Server installiert sind.

• Docker: Die Standard-Images enthalten laut Doku schon Englisch, Deutsch, Französisch, Portugiesisch und vereinfachtes Chinesisch. Für weitere Sprachen legst du .traineddata-Dateien aus dem Tesseract-Projekt in den Ordner ./stirling-data/tessdata und startest den Container neu.
• Helper-Script: Hier sind schon alle Sprachen installiert. Prüfen kannst du das in der Container-Shell mit tesseract --list-langs | grep deu.
• Eigene Debian-Installation: apt install tesseract-ocr-deu.

Lösch die Datei eng.traineddata nicht. Stirling-PDF braucht Englisch immer, auch wenn du nur deutsche Texte erkennen willst.

Stirling-PDF und Paperless

Stirling-PDF ist ein Werkzeugkasten für einzelne Dateien. Es archiviert nichts und sortiert nichts. Wenn du deine Post und Rechnungen dauerhaft ablegen und wiederfinden willst, nimm dafür Paperless-ngx. Bei mir ergänzen sich beide: In Stirling-PDF bereite ich eine Datei vor, also zusammenfügen oder schwärzen, und lade sie danach in Paperless hoch. Paperless macht sein eigenes OCR, darum musst du das vorher nicht in Stirling-PDF erledigen. Wie mein Paperless-Setup mit KI-Sortierung aussieht, zeige ich in Paperless-ngx 3 mit KI: Dokumente automatisch sortieren.

So prüfst du, ob es läuft

• Die Login-Seite unter http://192.168.1.x:8080 lädt.
• Helper-Script: In der Container-Shell zeigt systemctl status stirlingpdf den Status active (running).
• Docker: docker compose ps zeigt den Container als laufend, docker compose logs -f zeigt keine Fehler.
• Als Funktionstest fügst du zwei kleine PDFs zusammen und lässt OCR mit Deutsch über einen Handy-Scan laufen. Lässt sich danach ein Wort im PDF suchen, ist alles eingerichtet.

Typische Probleme

Die Seite lädt nach dem Start nicht. Stirling-PDF ist eine Java-Anwendung und braucht nach dem Start etwa eine Minute. Warte kurz und lade neu.

Umwandlung von Word nach PDF schlägt fehl. Dafür nutzt Stirling-PDF LibreOffice im Hintergrund. Beim Helper-Script läuft dafür ein eigener Service namens unoserver. Prüf ihn mit systemctl status unoserver, fehlgeschlagene Services zeigt dir systemctl --failed. Bei Docker brauchst du das normale Image, die Ultra-Lite-Variante kann das nicht.

Das Update per Helper-Script bricht ab. Ein Update startest du, indem du in der Konsole des LXC den Befehl update eingibst. Ich hatte einen Container, den ich vor über einem Jahr angelegt hatte. Das Update-Script meldet dort „Legacy installation detected“ und verlangt, den Container mit dem aktuellen Script neu anzulegen. Das liegt daran, dass sich der Aufbau der Installation geändert hat. Bei mir war das kein Drama: neuen LXC anlegen, Nutzer neu einrichten, alten Container löschen. Lösch den alten Container aber erst, wenn der neue läuft, und mach vorher in Proxmox ein Backup davon. Deine Nutzer und Einstellungen liegen im Ordner /opt/Stirling-PDF/configs, laut Doku steckt dort auch die eingebaute Datenbank. Willst du sie mitnehmen, kopierst du den Ordner in der Shell des Proxmox-Hosts in den neuen LXC:

pct exec <alte-id> -- tar czf /root/configs.tgz -C /opt/Stirling-PDF configs
pct pull <alte-id> /root/configs.tgz /root/configs.tgz
pct push <neue-id> /root/configs.tgz /root/configs.tgz
pct exec <neue-id> -- systemctl stop stirlingpdf
pct exec <neue-id> -- tar xzf /root/configs.tgz -C /opt/Stirling-PDF
pct exec <neue-id> -- systemctl start stirlingpdf

Der Container läuft voll. Alle OCR-Sprachen, LibreOffice und temporäre Dateien brauchen Platz. Bei unter 1 GB freiem Speicher brechen große Aufträge ab. Vergrößere die Disk in Proxmox unter Ressourcen: Root-Disk auswählen, dann Volumen-Aktion → Größe anpassen.

Große Dateien lassen sich über den Reverse Proxy nicht hochladen. Erhöhe das Upload-Limit deines Proxys, bei nginx über client_max_body_size. Stirling-PDF selbst erlaubt standardmäßig bis zu 2000 MB.

Ob dein Stirling-PDF noch erreichbar ist, kannst du mit Uptime Kuma überwachen. Wie ich das mit Push-Nachrichten aufs Handy gelöst habe, steht in Uptime Kuma und ntfy im Homelab.

Fazit

Stirling-PDF ist eines der Tools, die ich nach der Installation einfach benutze, ohne viel daran zu denken. Die Einrichtung dauert per Helper-Script oder Docker nur ein paar Minuten, danach kannst du PDFs zusammenfügen, schwärzen, verkleinern und durchsuchbar machen, ohne private Dokumente bei einem Online-Dienst hochzuladen. Ändere direkt das Admin-Passwort, lass die Oberfläche im Heimnetz oder hinter einem VPN und gib dem Container genug Speicherplatz. Dann läuft es.

Hat dir der Guide geholfen? Dann spendier mir gern einen Kaffee auf Ko-fi. Damit bleibt MappleBox werbefrei.

Weitere Guides

• Proxmox VE Helper-Scripts: Dienste mit einem Befehl installieren
• Paperless-ngx KI: Dokumente mit Claude sortieren, ohne Tag-Chaos
• Tailscale –accept-routes macht dein LAN kaputt? So fixt du es mit einer ip rule