Stirling-PDF ist ein quelloffener PDF-Werkzeugkasten, den Sie als Web-Anwendung auf Ihrem eigenen Server betreiben: Vertrauliche Dokumente verarbeiten Sie im Browser gegen einen Container in Ihrem Netzwerk statt bei einem Online-Dienst. An Bord sind über 50 Werkzeuge, darunter Zusammenführen (Merge), Aufteilen (Split), Umwandeln (Convert), Komprimieren (Compress), OCR, elektronisches Signieren (eSign), Wasserzeichen, Reparieren (Repair) und Schwärzen (Redact). Die Anleitung zeigt, wie Sie Stirling-PDF mit Docker per Docker Compose auf einem Linux-Server aufsetzen, mit Login absichern, aktualisieren und sichern.

Voraussetzungen

Stirling-PDF ist genügsam und braucht keine spezielle Hardware. Folgendes sollten Sie 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).
Hardware: 2 CPU-Kerne, x86_64 oder ARM64, 1 bis 2 GB freier RAM, für große Dateien und parallele Jobs mehr. Das Image belegt gut 1 GB; planen Sie 5 GB freien Speicher.
Keine GPU nötig. Stirling-PDF rechnet rein auf der CPU; das nvidia-container-toolkit brauchen Sie nicht.
Optional: eine Domain und ein Reverse-Proxy (z.B. Caddy, Traefik oder Nginx) für HTTPS-Zugriff von außen.

Grundlagen zu Docker Compose und Stacks: Docker-Compose-Grundlagen und Stacks.

Schritt 1: Projektverzeichnis und Datenstruktur anlegen

Legen Sie ein eigenes Verzeichnis für compose.yaml und persistente Daten an, darin das Unterverzeichnis stirling-data für die Volumes.

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

Einstellungen liegen in configs, OCR-Sprachdateien in tessdata, Logs in logs und Automatisierungs-Pipelines in pipeline.

Verifizieren: ls ~/stirling-pdf/stirling-data zeigt die vier Ordner configs, logs, pipeline und tessdata.

Schritt 2: compose.yaml erstellen

Speichern Sie die folgende Datei als compose.yaml in ~/stirling-pdf. Sie nutzt das offizielle Image in Version 3.1.0.

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:3.1.0
    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:
      SECURITY_ENABLELOGIN: "true"
      SECURITY_INITIALLOGIN_USERNAME: "admin"
      SECURITY_INITIALLOGIN_PASSWORD: "IHR-SICHERES-PASSWORT"
      SYSTEM_DEFAULTLOCALE: "de-DE"
      UI_APPNAMENAVBAR: "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 Ihres 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 können Sie den Wert erhöhen.
SECURITY_ENABLELOGIN: true ist seit Version 3 der Standard. Mit den beiden SECURITY_INITIALLOGIN_-Variablen legt Stirling-PDF beim ersten Start ein eigenes Admin-Konto an; ohne sie entsteht das öffentlich bekannte Konto admin / stirling. Details 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 nutzen Sie das fertige Image stirlingtools/stirling-pdf wie oben – nicht die Build-Datei aus dem Repo.

Verifizieren: docker compose config gibt die Konfiguration ohne Fehlermeldung aus und zeigt das Image stirlingtools/stirling-pdf:3.1.0.

Schritt 3: Stirling-PDF starten

Jetzt ziehen Sie das Image und starten den Container im Hintergrund.

docker compose pull
docker compose up -d

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

Der erste Start dauert einen Moment. Der Health-Check-Endpunkt liefert bei Bereitschaft eine JSON-Antwort mit "status":"UP" und der Versionsnummer:

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

Anschließend rufen Sie die Oberfläche im Browser auf:

http://SERVER-IP:8080

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

Verifizieren: docker compose ps zeigt stirling-pdf nach etwa zwei Minuten als healthy, der curl-Aufruf liefert "status":"UP", und im Browser erscheint die Anmeldeseite.

Schritt 4: Web-UI kennenlernen und erste Funktion nutzen

Nach der Anmeldung sehen Sie alle Werkzeuge gruppiert. Typischer Büro-Ablauf: mehrere PDFs zu einem Dokument zusammenführen:

Wählen Sie das Werkzeug Merge (PDFs zusammenführen).
Ziehen Sie Ihre PDF-Dateien per Drag-and-drop in das Upload-Feld.
Sortieren Sie die Reihenfolge per Maus, falls nötig.
Starten Sie die Verarbeitung und laden Sie das fertige PDF herunter.

Die Datei verlässt dabei nie Ihren Server; die Verarbeitung läuft lokal im Container ohne Cloud-Upload. Split, Convert, Compress, Wasserzeichen, eSign und Reparatur funktionieren genauso: Werkzeug wählen, Datei laden, Ergebnis herunterladen.

Verifizieren: Das zusammengeführte PDF lässt sich öffnen und enthält die Seiten aller Ausgangsdateien in der gewählten Reihenfolge.

Schritt 5: OCR mit deutschem Sprachpaket nachrüsten

Für OCR via Tesseract brauchen Sie das passende Sprachpaket. Englisch, Deutsch, Französisch, Portugiesisch und vereinfachtes Chinesisch sind enthalten. Weitere Sprachen, etwa Italienisch, legen Sie als .traineddata-Datei in das gemountete /usr/share/tessdata; der Container kopiert sie beim Start in sein Tesseract-Verzeichnis, sodass sie Neustart und Update überstehen.

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

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

Für deutsche Dokumente ist kein Download nötig: Wählen Sie im OCR-Werkzeug einfach die Sprache Deutsch.

Verifizieren: docker compose logs stirling-pdf | grep -i tessdata meldet beim Start das Kopieren der eigenen Dateien, und ein gescanntes deutsches PDF ist nach dem OCR-Lauf im PDF-Betrachter durchsuchbar.

Seit Version 3 ist der Login ab Werk aktiv, die compose.yaml aus Schritt 2 setzt ihn zusätzlich ausdrücklich. Entscheidend sind eigene Startzugangsdaten im environment-Block:

    environment:
      SECURITY_ENABLELOGIN: "true"
      SECURITY_INITIALLOGIN_USERNAME: "admin"
      SECURITY_INITIALLOGIN_PASSWORD: "IHR-SICHERES-PASSWORT"
      SYSTEM_DEFAULTLOCALE: "de-DE"
      UI_APPNAMENAVBAR: "Stirling-PDF"
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"

Nach Änderungen den Stack neu hochziehen, damit die Variablen wirken:

docker compose up -d

Der erste Login erfolgt mit Ihren Initial-Zugangsdaten. Die Variablen wirken nur beim ersten Start, solange das Konto nicht existiert; ändern Sie danach das Passwort in der Kontoverwaltung und entfernen Sie SECURITY_INITIALLOGIN_PASSWORD aus der compose.yaml. Fehlen die Variablen, entsteht das öffentlich bekannte Konto admin / stirling, das nur beim ersten Anmelden einen Passwortwechsel erzwingt. SSO über OAuth2 ist seit Version 3 in allen Varianten enthalten, SAML nur in der Enterprise-Lizenz (siehe FAQ).

Verifizieren: Ein privates Browserfenster auf http://SERVER-IP:8080 zeigt die Anmeldeseite; die Anmeldung mit Ihren eigenen Zugangsdaten gelingt, admin / stirling wird abgewiesen.

Schritt 7: Reverse-Proxy und HTTPS

Von außen gehört Stirling-PDF hinter einen Reverse-Proxy, der TLS terminiert. Schlankes Nginx-Beispiel mit Weiterleitung auf Port 8080:

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

    ssl_certificate     /etc/letsencrypt/live/pdf.IHRE-DOMAIN.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.IHRE-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;
    }
}

Wählen Sie client_max_body_size mindestens so groß wie SYSTEM_MAXFILESIZE, sonst blockt der Proxy große Uploads. Unter einem Unterpfad (z. B. /pdf) setzen Sie zusätzlich SYSTEM_ROOTURIPATH, sonst stimmen Health-Check und interne Links nicht. Die externe Adresse für Einladungs- und Freigabelinks hinterlegen Sie mit SYSTEM_FRONTENDURL. Liegt der Proxy auf demselben Host, binden Sie den Port an 127.0.0.1:8080:8080, damit Stirling-PDF nur über HTTPS erreichbar ist.

Verifizieren: sudo nginx -t meldet syntax is ok, und curl -I https://pdf.IHRE-DOMAIN.de liefert HTTP/2 200 oder eine Weiterleitung auf die Anmeldeseite.

Schritt 8: Update-Workflow

Für ein Update tragen Sie den neuen Versions-Tag in die compose.yaml ein, ziehen das Image und ersetzen den Container; die Volumes bleiben unberührt.

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

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

Der Tag latest kann beim nächsten Pull eine neue Major-Version ziehen (v3.0.0 brachte im September 2026 u. a. den Login als Standard und neue Automatisierungsfunktionen, v3.1.0 im Oktober 2026 die Gruppensignatur Stirling Sign als Standard für neue Installationen und den optionalen Konverter Stirling Office Convert als Beta). Pinnen Sie wie in Schritt 2 einen Versions-Tag, etwa stirlingtools/stirling-pdf:3.1.0, und aktualisieren Sie nach Blick in die Release Notes. Das Update von 3.0.0 auf 3.1.0 lief im Test mit der compose.yaml aus Schritt 2 ohne Anpassung durch: Der Statusendpunkt meldete danach 3.1.0, und API-Aufrufe ohne Anmeldung wurden weiter mit 401 abgewiesen. Daneben gibt es latest-fat (zusätzliche Schriften und Tools) und latest-ultra-lite (Minimal-Build ohne Login-Funktion).

Verifizieren: curl http://localhost:8080/api/v1/info/status meldet nach dem Update die neue Versionsnummer, und Ihre Einstellungen und Benutzer sind unverändert vorhanden.

Schritt 9: Backup der Daten

Alles Wichtige steckt in den Volume-Verzeichnissen, allen voran configs (settings.yml, Benutzer-Datenbank). Ein Tar-Archiv des Datenverzeichnisses genügt:

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

Stoppen Sie für ein konsistentes Archiv vorher kurz den Container (docker compose stop) und starten Sie ihn danach wieder. Legen Sie das Archiv außerhalb des Servers ab (zweite Maschine, NAS, Offsite). Zum Wiederherstellen entpacken Sie es nach ~/stirling-pdf und starten mit docker compose up -d.

Verifizieren: tar tzf stirling-backup-$(date +%F).tar.gz | head listet Dateien aus stirling-data/configs, darunter settings.yml.

Troubleshooting

Eigene Startzugangsdaten funktionieren nicht: SECURITY_INITIALLOGIN_USERNAME und SECURITY_INITIALLOGIN_PASSWORD wirken nur, solange es das Konto noch nicht gibt. Existiert bereits eine Benutzerdatenbank in configs, gilt deren Passwort. Kein Login trotz SECURITY_ENABLELOGIN=true: Prüfen Sie, ob versehentlich das Image latest-ultra-lite läuft, das keine Login-Funktion enthält.
OCR-Sprachpaket nach Update weg: Das Volume auf /usr/share/tessdata fehlt; mit dem Mount aus Schritt 2 bleiben nachgeladene .traineddata-Dateien erhalten.
Großer Upload schlägt fehl: Erhöhen Sie SYSTEM_MAXFILESIZE (Angabe in MB, im Beispiel 100) und – falls vorhanden – die client_max_body_size Ihres 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: docker compose logs -f stirling-pdf zeigt den Startablauf, erster Anlaufpunkt bei Problemen.

Häufige Fragen

Werden meine Dokumente in die Cloud hochgeladen?

Nein. Alles läuft lokal im Container; die mit Version 3 eingeführten KI-Funktionen sind optional und ab Werk aus. Es gibt keinen Upload zu externen Diensten.

Brauche ich eine GPU?

Nein. Stirling-PDF läuft rein auf der CPU mit wenig Ressourcen; ein kleiner VPS oder Mini-PC genügt.

Welches Image-Tag soll ich nehmen?

Meist ein gepinnter Tag wie 3.1.0, alternativ latest; zu latest-fat und latest-ultra-lite siehe Schritt 8.

Wie aktiviere ich SSO?

OAuth2 ohne Lizenz, SAML nur mit Enterprise-Lizenz, jeweils mit aktivem Login (SECURITY_ENABLELOGIN=true). Die Provider-Anbindung beschreibt die offizielle 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_APPNAMENAVBAR setzen Sie einen eigenen Namen; seit Version 3 erscheint er im Browser-Tab und als Aussteller in Authenticator-Apps, nicht mehr in der Navigationsleiste. Die Sprache stellen Sie über SYSTEM_DEFAULTLOCALE (z.B. de-DE) ein.

Fazit

Mit compose.yaml und docker compose up -d steht ein datenschutzfreundlicher PDF-Werkzeugkasten im eigenen Netz. Volumes erhalten Einstellungen, OCR-Sprachpakete und Logs, Updates sind ein Zweizeiler, das Backup ein Tar-Archiv. Über das Heimnetz hinaus gehören eigene Zugangsdaten und ein Reverse-Proxy mit HTTPS dazu.

Weiterführende Anleitungen und Quellen

Passende Anleitungen aus unserem Wissensbereich:

Docker Compose: Grundlagen und Stacks aufbauen – ideal, falls Sie den Umgang mit compose.yaml vertiefen wollen.
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 Ihrem PDF-Werkzeugkasten.
Weitere Anleitungen der Kategorie Cloud

Offizielle Quellen: