Stirling-PDF ist ein quelloffener, lokal laufender PDF-Werkzeugkasten, den du als Web-Anwendung auf deinem eigenen Server betreibst. Statt vertrauliche Dokumente bei einem Online-Dienst hochzuladen, verarbeitest du sie direkt im Browser gegen einen Container in deinem Netzwerk. An Bord sind über 50 Werkzeuge: PDFs zusammenführen (Merge), aufteilen (Split), umwandeln (Convert), komprimieren (Compress), per OCR durchsuchbar machen, elektronisch signieren (eSign), mit Wasserzeichen versehen, reparieren (Repair) und schwärzen (Redact). Diese Anleitung zeigt dir Schritt für Schritt, wie du Stirling-PDF mit Docker per Docker Compose auf einem Linux-Server aufsetzt, optional mit Login absicherst und sauber aktualisierst und sicherst. Gedacht ist das Ganze für den Büroalltag im Mittelstand und für ambitionierte Heimserver-Nutzer.

Voraussetzungen

Stirling-PDF ist genügsam und braucht keine spezielle Hardware. Folgendes solltest du bereithalten:

Linux-Server mit Debian 12 oder Ubuntu 24.04 (ein kleiner VPS oder ein Mini-PC reicht völlig).
Docker und Docker Compose (Plugin docker compose, nicht das alte docker-compose).
RAM: 1-2 GB sind in der Praxis ausreichend, für große Dateien und parallele Jobs darf es mehr sein.
Keine GPU nötig. Stirling-PDF rechnet rein auf der CPU – es gibt hier keinen LLM- oder Bildgenerierungs-Workload. Das nvidia-container-toolkit brauchst du für diesen Dienst nicht.
Optional: eine Domain und ein Reverse-Proxy (z.B. Caddy, Traefik oder Nginx) für HTTPS-Zugriff von außen.

Wie du Docker und Docker Compose grundsätzlich aufsetzt und einen Stack strukturierst, findest du in unserer Anleitung zu den Docker-Compose-Grundlagen und Stacks.

Schritt 1: Projektverzeichnis und Datenstruktur anlegen

Lege zuerst ein eigenes Verzeichnis für den Stack an. Hier landen später die compose.yaml und alle persistenten Daten. Wir verwenden ein Unterverzeichnis stirling-data, das wir gleich in mehrere Volumes aufteilen.

mkdir -p ~/stirling-pdf
cd ~/stirling-pdf

# Unterverzeichnisse fuer die Volumes vorbereiten
mkdir -p stirling-data/configs
mkdir -p stirling-data/tessdata
mkdir -p stirling-data/logs
mkdir -p stirling-data/pipeline

Damit ist die Datenstruktur klar getrennt: Einstellungen liegen in configs, die OCR-Sprachdateien in tessdata, Logs in logs und Automatisierungs-Pipelines in pipeline.

Schritt 2: compose.yaml erstellen

Das ist das Herzstück. Speichere die folgende Datei als compose.yaml im Verzeichnis ~/stirling-pdf. Sie ist copy-paste-fertig und nutzt das offizielle, fertige Image stirlingtools/stirling-pdf:latest.

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/tessdata:/usr/share/tessdata
      - ./stirling-data/logs:/logs
      - ./stirling-data/pipeline:/pipeline
    environment:
      DISABLE_ADDITIONAL_FEATURES: "true"
      SECURITY_ENABLELOGIN: "false"
      SYSTEM_DEFAULTLOCALE: "de-DE"
      UI_APPNAME: "Stirling-PDF"
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"
    restart: unless-stopped

Ein paar Anmerkungen zu den Werten:

8080:8080 mappt den internen Web-Port auf den gleichen Port deines Hosts.
SYSTEM_DEFAULTLOCALE: de-DE stellt die Oberfläche auf Deutsch.
SYSTEM_MAXFILESIZE: 100 erlaubt Uploads bis 100 MB. Für große Scan-Stapel kannst du den Wert erhöhen.
DISABLE_ADDITIONAL_FEATURES: true und SECURITY_ENABLELOGIN: false bedeuten: erst einmal ohne Login starten. Wie du den Login aktivierst, zeigt Schritt 6.

Hinweis: Die im Repository unter docker/compose/docker-compose.yml liegende Datei ist eine Build- bzw. Demo-Datei, die das Image lokal baut. Für den produktiven Betrieb nutzt du das fertige Image stirlingtools/stirling-pdf:latest wie oben – nicht die Build-Datei aus dem Repo.

Schritt 3: Stirling-PDF starten

Jetzt ziehst du das Image und startest den Container im Hintergrund.

docker compose pull
docker compose up -d

# Status pruefen
docker compose ps
docker compose logs -f stirling-pdf

Beim ersten Start dauert es einen Moment, bis der Dienst hochgefahren ist. Ob er bereit ist, verrät dir der Health-Check-Endpunkt – er liefert ein schlichtes UP zurück:

curl http://localhost:8080/api/v1/info/status

Anschließend rufst du die Oberfläche im Browser auf:

http://SERVER-IP:8080

Ersetze SERVER-IP durch die IP-Adresse deines Servers. Läuft alles auf demselben Rechner, funktioniert auch http://localhost:8080.

Schritt 4: Web-UI kennenlernen und erste Funktion nutzen

In der Oberfläche siehst du alle Werkzeuge gruppiert. Für den Einstieg ein typischer Büro-Ablauf – mehrere Einzel-PDFs zu einem Dokument zusammenführen:

Wähle das Werkzeug Merge (PDFs zusammenführen).
Ziehe deine PDF-Dateien per Drag-and-drop in das Upload-Feld.
Sortiere die Reihenfolge per Maus, falls nötig.
Klicke auf Verarbeiten und lade das fertige PDF herunter.

Das Wichtige dabei: Die Datei verlässt nie deinen Server. Die gesamte Verarbeitung passiert lokal im Container, es gibt keinen Cloud-Upload zu einem Drittanbieter. Genauso funktionieren Split, Convert, Compress, Wasserzeichen, eSign und Reparatur – einfach das passende Werkzeug wählen, Datei laden, Ergebnis herunterladen.

Schritt 5: OCR mit deutschem Sprachpaket nachrüsten

Damit Stirling-PDF gescannte Dokumente in durchsuchbaren Text umwandeln kann (OCR via Tesseract), brauchst du das passende Sprachpaket. Standardmäßig ist Englisch dabei; für deutsche Dokumente lädst du deu.traineddata nach. Weil wir /usr/share/tessdata als Volume gemountet haben, bleibt die Datei auch nach Neustart und Update erhalten.

# Deutsches Sprachpaket in das gemountete tessdata-Verzeichnis laden
curl -L -o ./stirling-data/tessdata/deu.traineddata \
  https://github.com/tesseract-ocr/tessdata/raw/main/deu.traineddata

# Container neu starten, damit das Sprachpaket erkannt wird
docker compose restart

Wichtig: Entferne niemals die eng.traineddata – sie wird intern benötigt. Du legst das deutsche Paket einfach daneben. Anschließend kannst du im OCR-Werkzeug die Sprache Deutsch auswählen.

Sobald Stirling-PDF über das reine Heimnetz hinaus erreichbar ist oder mehrere Personen damit arbeiten, solltest du den Login einschalten. Wichtig ist die Reihenfolge: Security greift nur, wenn DISABLE_ADDITIONAL_FEATURES auf false steht und SECURITY_ENABLELOGIN auf true. Passe den environment-Block in der compose.yaml so an:

    environment:
      DISABLE_ADDITIONAL_FEATURES: "false"
      SECURITY_ENABLELOGIN: "true"
      SECURITY_INITIALLOGIN_USERNAME: "admin"
      SECURITY_INITIALLOGIN_PASSWORD: "DEIN-SICHERES-PASSWORT"
      SYSTEM_DEFAULTLOCALE: "de-DE"
      UI_APPNAME: "Stirling-PDF"
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"

Danach den Stack neu hochziehen, damit die geänderten Variablen wirken:

docker compose up -d

Der erste Login erfolgt mit den von dir gesetzten Initial-Zugangsdaten. Beim ersten Anmelden erzwingt Stirling-PDF einen Passwortwechsel. Die intern voreingestellten Default-Credentials admin / stirling sind öffentlich bekannt – setze daher immer ein eigenes, sicheres Passwort. Wer es größer braucht: SSO über OAuth2 oder SAML lässt sich zusätzlich konfigurieren; die Login-Aktivierung oben ist die Voraussetzung dafür.

Schritt 7: Reverse-Proxy und HTTPS

Für den Zugriff von außen gehörst du Stirling-PDF nicht direkt ins Internet, sondern hinter einen Reverse-Proxy, der TLS terminiert. Hier ein schlankes Beispiel für Nginx, das auf den Container auf Port 8080 weiterleitet:

server {
    listen 443 ssl;
    server_name pdf.DEINE-DOMAIN.de;

    ssl_certificate     /etc/letsencrypt/live/pdf.DEINE-DOMAIN.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.DEINE-DOMAIN.de/privkey.pem;

    client_max_body_size 200M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Achte darauf, client_max_body_size mindestens so groß wie SYSTEM_MAXFILESIZE zu wählen, sonst blockt der Proxy große Uploads. Betreibst du Stirling-PDF unter einem Unterpfad (z.B. /pdf), musst du zusätzlich die Variable SYSTEM_ROOTURIPATH setzen – sonst stimmen Health-Check und interne Links nicht. Die volle externe Adresse kannst du mit SYSTEM_FRONTENDURL hinterlegen.

Schritt 8: Update-Workflow

Updates sind unkompliziert. Du ziehst das neue Image und ersetzt den Container – die Daten in den Volumes bleiben dabei unberührt.

cd ~/stirling-pdf
docker compose pull
docker compose up -d

# Optional: alte, ungenutzte Images aufraeumen
docker image prune -f

Ein Wort zur Versionierung: Der Tag latest kann beim nächsten Pull eine neue Major- oder Minor-Version ziehen (so brachte etwa v2.11.0 vom 19.05.2026 eine umgestellte UI). Für eine stabile Büro-Umgebung ist es ratsam, statt latest einen konkreten Versions-Tag zu pinnen, etwa stirlingtools/stirling-pdf:2.11.0, und Updates bewusst durchzuführen. Neben latest gibt es latest-fat (alle Features plus extra Schriften und Tools) und latest-ultra-lite (minimaler Build für sehr ressourcenarme Umgebungen).

Schritt 9: Backup der Daten

Alles Wichtige steckt in den Volume-Verzeichnissen, allen voran configs (Einstellungen, settings.yml, Benutzer-Datenbank). Ein einfaches Backup ist ein Tar-Archiv des gesamten Datenverzeichnisses:

cd ~/stirling-pdf
tar czf stirling-backup-$(date +%F).tar.gz ./stirling-data

Lege das Archiv an einen sicheren Ort außerhalb des Servers (zweite Maschine, NAS, Offsite). Zum Wiederherstellen entpackst du es zurück nach ~/stirling-pdf und startest den Stack mit docker compose up -d. So sind Konfiguration, OCR-Sprachpakete und Logs in einem Rutsch gesichert.

Troubleshooting

Login funktioniert nicht oder Container startet nicht: Prüfe, ob beide Variablen gesetzt sind – DISABLE_ADDITIONAL_FEATURES=false und SECURITY_ENABLELOGIN=true. Fehlt eine, scheitert die Security (bekanntes Verhalten, Issue #1040).
OCR-Sprachpaket nach Update weg: Dann fehlt das Volume auf /usr/share/tessdata. Ohne dieses Mount gehen nachgeladene .traineddata-Dateien bei Neustart oder Update verloren. Mit dem Mount aus Schritt 2 bleiben sie erhalten.
Großer Upload schlägt fehl: Erhöhe SYSTEM_MAXFILESIZE (Default rund 100 MB) und – falls vorhanden – die client_max_body_size deines Reverse-Proxys.
Defekte Links hinter dem Proxy: Bei Betrieb unter einem Subpfad muss SYSTEM_ROOTURIPATH gesetzt sein, sonst stimmen Health-Check und interne Verweise nicht.
Container-Logs lesen: Mit docker compose logs -f stirling-pdf siehst du, was beim Start passiert – das ist der erste Anlaufpunkt bei Problemen.

Häufige Fragen

Werden meine Dokumente in die Cloud hochgeladen?

Nein. Stirling-PDF verarbeitet alles lokal im Container auf deinem Server. Es gibt keinen Upload zu einem externen Dienst – genau das macht das Tool für vertrauliche Büro-Dokumente so attraktiv.

Brauche ich eine GPU?

Nein. Stirling-PDF läuft rein auf der CPU und kommt mit wenig Ressourcen aus. Es gibt keinen LLM- oder Bildgenerierungs-Workload, daher ist auch das nvidia-container-toolkit nicht nötig. Ein kleiner VPS oder Mini-PC genügt.

Welches Image-Tag soll ich nehmen?

Für die meisten Fälle latest bzw. ein gepinnter Versions-Tag wie 2.11.0 für mehr Stabilität. latest-fat bringt zusätzliche Schriften und Tools mit, latest-ultra-lite ist ein Minimal-Build für sehr kleine Umgebungen.

Wie aktiviere ich SSO?

SSO über OAuth2 oder SAML ist separat konfigurierbar. Voraussetzung ist, dass der Login aktiv ist (DISABLE_ADDITIONAL_FEATURES=false und SECURITY_ENABLELOGIN=true). Die Details der Provider-Anbindung findest du in der offiziellen Security-Doku.

Was muss ich sichern?

Die Volume-Verzeichnisse, vor allem configs mit den Einstellungen und der Benutzer-Datenbank. Das Tar-Backup aus Schritt 9 deckt zusätzlich OCR-Sprachpakete und Logs ab.

Kann ich die Oberfläche umbenennen?

Ja, über UI_APPNAME setzt du einen eigenen Anzeigenamen. Die Sprache stellst du über SYSTEM_DEFAULTLOCALE (z.B. de-DE) ein.

Fazit

Mit wenigen Schritten hast du einen vollwertigen, datenschutzfreundlichen PDF-Werkzeugkasten im eigenen Netz: compose.yaml anlegen, docker compose up -d ausführen, im Browser öffnen – fertig. Über Volumes bleiben Einstellungen, OCR-Sprachpakete und Logs erhalten, Updates sind ein Zweizeiler und das Backup ein einzelnes Tar-Archiv. Wer den Dienst über das Heimnetz hinaus betreibt, aktiviert Login und stellt einen Reverse-Proxy mit HTTPS davor. Damit ersetzt Stirling-PDF eine ganze Reihe von Online-PDF-Tools – ohne dass ein einziges Dokument deinen Server verlässt.

Weiterführende Anleitungen und Quellen

Passende Anleitungen aus unserem Wissensbereich:

Docker Compose: Grundlagen und Stacks aufbauen – ideal, falls du den Umgang mit compose.yaml vertiefen willst.
Gitea als self-hosted Git-Server mit Docker – ein weiterer praktischer Self-Hosting-Dienst fürs Büro.
Nextcloud AIO als self-hosted Cloud mit Docker einrichten – die passende Dokumentenablage zu deinem PDF-Werkzeugkasten.
Weitere Anleitungen der Kategorie Cloud

Offizielle Quellen: