StirlingPDF im Eigenbau: Dein PDF-Kraftpaket mit Docker

Na, wer kennt das nicht? Man braucht schnell mal ein PDF zusammenführen, eine Seite löschen oder ein Dokument komprimieren, und zack – landet man wieder auf irgendeiner dubiosen Online-Seite, die einem erst mal 20 Pop-ups um die Ohren haut und dann auch noch die Datei in die Cloud lädt. Mir ging das jahrelang auf die Nerven. Gerade im professionellen Umfeld, aber auch im Heimlabor, wo ich meine Dokumente lieber lokal behalte, war das ein echter Pain. Deshalb bin ich immer auf der Suche nach Tools, die ich selbst hosten kann. Und da bin ich über StirlingPDF gestolpert – ein absolutes Must-Have, das ich dir heute näherbringen möchte.

StirlingPDF ist für mich die eierlegende Wollmilchsau unter den PDF-Tools. Es ist Open Source, läuft in einem Docker-Container und bietet eine Fülle von Funktionen, die man sonst nur von teuren Suiten kennt. Und das Beste: Es bleibt alles in deinem eigenen Netzwerk. Keine Daten, die ungewollt ins Internet hochgeladen werden, volle Kontrolle über deine Dokumente. Das ist mir persönlich extrem wichtig, besonders wenn es um sensible Unterlagen geht.

In meiner Erfahrung ist die Einrichtung mit Docker super einfach und schnell erledigt. Egal, ob du einen ausgewachsenen Proxmox-Server, einen kleinen Raspberry Pi oder eine VM in der Cloud hast, solange Docker läuft, ist StirlingPDF ruckzuck einsatzbereit. Ich habe es auf verschiedenen Systemen laufen gehabt, von einem alten NUC bis zu einem aktuellen Proxmox LXC, und es hat sich immer als extrem zuverlässig erwiesen.

Was ist StirlingPDF eigentlich?

Kurz gesagt: StirlingPDF ist eine webbasierte PDF-Toolbox. Stell dir vor, du hast Adobe Acrobat, aber als schlanke, schnelle Web-App, die du selbst betreibst. Die Funktionsliste ist beeindruckend und deckt eigentlich alle gängigen Anwendungsfälle ab, die man so im Alltag oder im Büro hat:

PDFs zusammenführen und aufteilen: Mehrere Dokumente zu einem machen oder ein großes PDF in einzelne Seiten zerlegen.
Seiten neu anordnen, löschen und drehen: Perfekt, um Scans zu korrigieren oder unnötige Seiten zu entfernen.
PDFs komprimieren: Wenn die E-Mail-Anhänge mal wieder zu groß sind.
PDFs in andere Formate konvertieren und umgekehrt: Von PDF zu Word, Excel, JPG, PNG oder HTML und natürlich auch andersherum.
Bilder in PDF umwandeln: Schnelle Erstellung von PDF-Dokumenten aus Scans oder Fotos.
PDFs mit Passwörtern schützen oder entsperren: Für zusätzliche Sicherheit oder um vergessene Passwörter zu entfernen (wenn du die Berechtigung dazu hast, versteht sich).
Wasserzeichen hinzufügen: Branding oder Statusvermerke auf Dokumenten anbringen.
OCR-Funktionalität: Texte in gescannten PDFs erkennbar machen, damit sie durchsuchbar und kopierbar werden. Das ist ein echter Game Changer für Archivierungszwecke!
PDFs reparieren: Wenn mal ein Dokument beschädigt ist.

Diese Funktionsvielfalt macht StirlingPDF für mich zu einem echten Schweizer Taschenmesser im digitalen Büro. Und das alles ohne Abo, ohne Cloud-Zwang und mit voller Kontrolle über deine Daten. Das ist doch mal eine Ansage, oder?

Voraussetzungen für dein StirlingPDF-Kraftpaket

Bevor wir loslegen, lass uns kurz klären, was du brauchst. Keine Sorge, die Anforderungen sind nicht hoch, aber ein paar Dinge sollten gegeben sein, damit alles reibungslos läuft.

Hardware

CPU: Ein moderner Dual-Core-Prozessor ist ideal. StirlingPDF ist nicht extrem CPU-hungrig, aber bei größeren PDFs oder OCR-Vorgängen freut es sich über etwas Leistung. Auch ein Raspberry Pi 4 oder 5 reicht hier völlig aus, wie ich selbst schon festgestellt habe. Für meinen Hauptserver nutze ich aber lieber etwas potenteres, wie einen Intel NUC oder eine VM mit 2 vCPUs.
RAM: Mindestens 2 GB RAM solltest du für den Container reservieren. Wenn du planst, sehr große PDFs zu bearbeiten oder viele OCR-Aufgaben gleichzeitig laufen zu lassen, schaden 4 GB nicht.
Speicher: Eine SSD ist immer von Vorteil, vor allem für die Performance bei Dateizugriffen. 10-20 GB freier Speicherplatz sind ein guter Startpunkt für das System und die Daten. Bedenke, dass StirlingPDF temporäre Dateien ablegt und deine bearbeiteten PDFs speichert.

Mein Tipp: Wenn du einen Raspberry Pi oder ein ähnliches ARM-System nutzen möchtest, stelle sicher, dass es ein Modell mit ausreichend RAM ist (RPi 4 mit 4GB oder 8GB ist top). Die Performance war für meine Zwecke immer mehr als ausreichend.

Software und System

Ein Linux-basiertes Betriebssystem: Ich persönlich setze meistens auf Debian oder Ubuntu Server, oft in einem Proxmox LXC. Aber auch andere Distributionen wie Fedora oder CentOS funktionieren, solange sie Docker unterstützen.
Docker und Docker Compose (Version 2): Das ist das Herzstück unserer Installation. Wenn du beides noch nicht auf deinem Server hast, zeige ich dir gleich, wie du es nachrüstest.
SSH-Zugang und Sudo-Rechte: Du solltest in der Lage sein, dich per SSH mit deinem Server zu verbinden und Befehle mit Root-Rechten auszuführen.
Netzwerk: Ein freier Port auf deinem Host-System (standardmäßig 8080) für den Zugriff auf die Weboberfläche von StirlingPDF.

Installation und Einrichtung – Mein bewährter Weg

Jetzt geht's ans Eingemachte! Ich zeige dir Schritt für Schritt, wie ich StirlingPDF in meinem Homelab aufgesetzt habe. Das ist ein erprobtes Vorgehen, das dir viel Kopfzerbrechen ersparen wird.

1. Server vorbereiten und Verzeichnisstruktur anlegen

Zuerst verbinden wir uns mit unserem Server per SSH. Dann aktualisieren wir das System und legen ein dediziertes Verzeichnis für StirlingPDF an. Das ist bewährte Praxis, um Ordnung zu halten und die Konfiguration später leicht wiederzufinden.

sudo apt update && sudo apt upgrade -y
mkdir -p /opt/stirling-pdf
cd /opt/stirling-pdf

Mit mkdir -p stellen wir sicher, dass das Verzeichnis /opt/stirling-pdf erstellt wird, auch wenn /opt noch nicht existiert. Danach wechseln wir direkt in dieses Verzeichnis, da wir dort unsere docker-compose.yml ablegen werden.

2. Docker und Docker Compose installieren (falls noch nicht geschehen)

Wenn du Docker und Docker Compose schon am Start hast, kannst du diesen Schritt überspringen. Für alle anderen, hier ist der schnelle Weg:

Docker Engine installieren

Der einfachste Weg ist das offizielle Installationsskript von Docker. Das erledigt die meisten Abhängigkeiten und Konfigurationen für dich.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

Wichtig zu wissen: Der Befehl sudo usermod -aG docker $USER fügt deinen aktuellen Benutzer zur Docker-Gruppe hinzu. Das ist entscheidend, damit du Docker-Befehle ohne sudo ausführen kannst. Nach diesem Befehl musst du dich entweder einmal abmelden und wieder anmelden oder newgrp docker ausführen, damit die Gruppenmitgliedschaft aktiv wird. Wenn du das nicht machst, wirst du später bei docker compose Befehlen Fehlermeldungen bekommen!

Docker Compose installieren (Plugin-Version)

Mit der modernen Docker-Installation ist Docker Compose V2 (als Plugin) oft schon dabei. Du kannst es prüfen, indem du docker compose version eingibst. Wenn es nicht funktioniert, installierst du es so:

sudo apt install docker-compose-plugin

Das installiert das Plugin für Docker Compose V2, das du dann mit docker compose (ohne Bindestrich) aufrufst. Wenn du aus irgendeinem Grund eine ältere Version oder eine manuelle Installation bevorzugst (was ich aber nicht mehr empfehle), könntest du es auch so machen:

# Dies ist der ältere Weg für Docker Compose V1 oder manuelle Installationen
# Ich empfehle die obige Methode für Docker Compose V2
# sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# sudo chmod +x /usr/local/bin/docker-compose
# docker-compose version

Verifizier die Installation mit docker compose version. Du solltest eine Ausgabe ähnlich wie diese sehen:

Docker Compose version v2.24.5

3. Die `docker-compose.yml` – Herzstück der Konfiguration

Jetzt erstellen wir die Konfigurationsdatei für unseren StirlingPDF-Container. Diese Datei definiert, wie Docker den Container starten soll, welche Ports er nutzen soll, wo die Daten gespeichert werden und so weiter. Ich nenne sie immer docker-compose.yml.

nano docker-compose.yml

Füge den folgenden Inhalt in die Datei ein:

version: '3.8'
services:
  stirling-pdf:
    image: stirlingpdf/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    environment:
      # Optional: Zeitzone für Logs und interne Zeitstempel
      - TZ=Europe/Berlin

Lass uns kurz die einzelnen Zeilen durchgehen, damit du verstehst, was hier passiert:

version: '3.8': Definiert die Version der Docker Compose Spezifikation. Ich nutze hier eine relativ aktuelle Version, die alle modernen Features unterstützt.
services:: Hier definieren wir unsere Dienste. In diesem Fall nur einen: stirling-pdf.
image: stirlingpdf/stirling-pdf:latest: Sagt Docker, welches Image gezogen werden soll. Wir nehmen das offizielle stirlingpdf/stirling-pdf Image und den latest Tag, um immer die neueste stabile Version zu haben.
container_name: stirling-pdf: Gibt unserem Container einen sprechenden Namen. Das macht es später einfacher, ihn in der Docker-Liste zu finden.
ports: - "8080:8080": Das ist das Port-Mapping. Der erste 8080 ist der Port auf deinem Host-System, der zweite 8080 ist der Port im Container. StirlingPDF läuft intern auf Port 8080. Du kannst den ersten Port anpassen, falls 8080 auf deinem Host schon belegt ist (z.B. "8081:8080").
volumes: - ./data:/app/data: Hier definieren wir die Persistenz. ./data ist ein Unterverzeichnis in unserem aktuellen Verzeichnis (/opt/stirling-pdf/data auf dem Host). Dieses Verzeichnis wird in den Container unter /app/data gemountet. Das ist extrem wichtig! Hier speichert StirlingPDF seine Konfiguration und temporäre Dateien. Ohne dieses Volume wären alle deine Einstellungen und Uploads nach einem Neustart des Containers weg.
restart: unless-stopped: Sorgt dafür, dass der Container automatisch neu startet, falls er abstürzt oder der Host neu gebootet wird, es sei denn, du stoppst ihn manuell. Sehr praktisch für den Homelab-Betrieb.
environment: - TZ=Europe/Berlin: Setzt die Zeitzone im Container. Das ist optional, aber hilfreich, damit Zeitstempel in Logs und der Anwendung korrekt sind. Passe Europe/Berlin an deine eigene Zeitzone an.

Speichere die Datei (Strg+O, Enter, Strg+X bei nano).

4. StirlingPDF starten

Jetzt kommt der spannendste Teil: Wir starten unseren Container! Navigiere in das Verzeichnis, in dem deine docker-compose.yml liegt (falls du es nicht schon bist: cd /opt/stirling-pdf), und führe den folgenden Befehl aus:

docker compose up -d

Der Befehl docker compose up startet die in der docker-compose.yml definierten Dienste. Der Parameter -d (detached) sorgt dafür, dass der Container im Hintergrund läuft und du deine SSH-Sitzung schließen kannst, ohne dass der Container stoppt.

Docker wird nun das Image herunterladen (das kann beim ersten Mal etwas dauern, je nach Internetverbindung) und den Container starten. Du kannst den Status überprüfen mit:

docker compose ps

Du solltest eine Ausgabe sehen, die anzeigt, dass stirling-pdf im Status Up ist.

5. Zugriff auf die Weboberfläche und erster Blick

Sobald der Container läuft, kannst du StirlingPDF in deinem Browser erreichen. Öffne einfach:

http://<Deine-Server-IP>:8080

Ersetze <Deine-Server-IP> mit der tatsächlichen IP-Adresse deines Servers (z.B. http://192.168.1.100:8080). Du solltest die schicke Oberfläche von StirlingPDF sehen. Nimm dir einen Moment Zeit, um die verschiedenen Funktionen zu erkunden. Probiere ruhig mal aus, ein Test-PDF hochzuladen und eine der Funktionen zu nutzen – du wirst staunen, wie schnell und intuitiv das Ganze ist.

Häufige Fehler und meine Lösungen

Auch als erfahrener Admin stolpert man mal über Kleinigkeiten. Hier sind ein paar typische Probleme, die mir oder anderen Homelab-Enthusiasten begegnet sind, und wie ich sie gelöst habe.

Fehler 1: Port 8080 ist bereits belegt

Problembeschreibung: Du versuchst, StirlingPDF zu starten, und Docker wirft einen Fehler wie Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use.

Erklärung: Das bedeutet, dass ein anderer Dienst auf deinem Host-System bereits Port 8080 belegt. Das kann ein anderer Webserver, eine andere Docker-Anwendung oder sogar ein Prozess deines Betriebssystems sein.

Lösung: Der einfachste Weg ist, den Host-Port für StirlingPDF zu ändern. Du kannst zum Beispiel Port 8081 verwenden. Bearbeite dazu deine docker-compose.yml:

nano docker-compose.yml

Ändere die ports-Zeile von "8080:8080" zu "8081:8080":

# ...
    ports:
      - "8081:8080" # Hier den Host-Port ändern
# ...

Speichere die Datei und starte den Container neu. Wenn er bereits läuft, musst du ihn erst stoppen und dann neu erstellen:

docker compose down
docker compose up -d

Jetzt erreichst du StirlingPDF unter http://<Deine-Server-IP>:8081.

Fehler 2: Daten sind nach Neustart weg

Problembeschreibung: Du hast PDFs hochgeladen, bearbeitet oder Einstellungen vorgenommen, und nach einem Neustart des Containers (oder des Servers) sind alle Änderungen verschwunden.

Erklärung: Das ist ein klassisches Problem, wenn das Volume-Mapping nicht korrekt eingerichtet ist oder die Berechtigungen im gemounteten Verzeichnis nicht stimmen. Docker-Container sind standardmäßig "stateless" – ihre internen Daten gehen verloren, sobald der Container gelöscht oder neu erstellt wird, es sei denn, du persistierst sie über Volumes.

Lösung:

Volume-Mapping überprüfen: Stelle sicher, dass in deiner docker-compose.yml die Zeile - ./data:/app/data korrekt ist und das Verzeichnis /opt/stirling-pdf/data auf deinem Host existiert.
Berechtigungen prüfen: Oft hat der Container nicht die nötigen Schreibrechte im gemounteten Verzeichnis. Der StirlingPDF-Container läuft in der Regel mit einem Standardbenutzer (oft UID 1000). Du kannst die Berechtigungen des Host-Verzeichnisses anpassen:

sudo chown -R 1000:1000 /opt/stirling-pdf/data
sudo chmod -R 775 /opt/stirling-pdf/data

Der Befehl chown -R 1000:1000 ändert den Besitzer des Verzeichnisses (und aller Unterverzeichnisse) auf den Benutzer und die Gruppe mit der ID 1000. Das ist eine gängige ID für den ersten Nicht-Root-Benutzer in vielen Linux-Distributionen und oft auch die ID, mit der Prozesse in Docker-Containern laufen. Mit chmod -R 775 gibst du dem Besitzer und der Gruppe volle Lese-, Schreib- und Ausführrechte, während andere nur Lese- und Ausführrechte haben. Nach der Änderung der Berechtigungen den Container neu starten.

Fehler 3: "Exec format error" auf Raspberry Pi oder ARM-Systemen

Problembeschreibung: Du versuchst, den Container auf einem Raspberry Pi oder einem anderen ARM-basierten System zu starten, und erhältst eine Fehlermeldung wie standard_init_linux.go:228: exec user process caused "exec format error".

Erklärung: Dieser Fehler tritt auf, wenn du versuchst, ein Docker-Image zu starten, das für eine andere Prozessorarchitektur kompiliert wurde, als dein Host-System verwendet. Ein Image, das z.B. nur für x86_64 (Standard-PC) gebaut wurde, kann nicht auf einem ARM-System (Raspberry Pi) ausgeführt werden.

Lösung: Das Gute ist, dass das offizielle stirlingpdf/stirling-pdf Image Multi-Architektur-fähig ist. Das bedeutet, es enthält Binaries für verschiedene Architekturen (wie x86_64 und ARM). Docker sollte automatisch die richtige Version für dein System ziehen.

Solltest du diesen Fehler dennoch sehen, prüfe Folgendes:

Architektur deines Hosts: Überprüfe die Architektur deines Systems mit uname -m. Du solltest etwas wie aarch64 oder armv7l für einen Raspberry Pi sehen, oder x86_64 für einen Standard-PC.
Image-Integrität: Manchmal kann es helfen, das Image neu zu ziehen, falls beim Download etwas schiefgelaufen ist.

docker compose pull
docker compose up -d

Wenn das Problem weiterhin besteht, könnte es an einer sehr alten Docker-Version oder einem spezifischen Problem deines Systems liegen. In diesem Fall hilft oft ein Blick in die Docker-Logs des Containers (docker logs stirling-pdf) oder eine gezielte Suche nach deinem uname -m und der Fehlermeldung.

Mein Tipp: Bei Docker-Problemen ist oft ein Blick in die Container-Logs der erste Schritt. Mit docker logs <container_name> (in unserem Fall docker logs stirling-pdf) siehst du, was im Container wirklich los ist. Das hat mir schon unzählige Stunden Fehlersuche erspart!

Fazit und nächste Schritte

Glückwunsch! Du hast jetzt dein eigenes, mächtiges PDF-Kraftpaket am Laufen, das dir die Kontrolle über deine Dokumente zurückgibt. StirlingPDF ist für mich persönlich zu einem unverzichtbaren Tool geworden, und ich bin mir sicher, dass es auch für dich im Homelab oder im Büroalltag ein echter Gewinn sein wird. Nie wieder PDFs an fragwürdige Online-Dienste senden – das ist Freiheit, wie wir sie lieben!

Aber damit ist die Reise ja noch nicht zu Ende, oder? Als echter Homelab-Enthusiast denkst du sicher schon an die nächsten Schritte. Hier sind ein paar Ideen, wie du deine StirlingPDF-Instanz noch weiter aufbohren kannst: