Stirling PDF selbst hosten: Die private PDF-Werkbank

PDFs zusammenfügen, komprimieren, drehen, in Office-Formate umwandeln oder per OCR durchsuchbar machen – Online-Dienste können das, aber deine Dokumente wandern dabei auf fremde Server. Stirling PDF bringt über 30 PDF-Werkzeuge in eine eigene, schlanke Weboberfläche – und verarbeitet jede Datei lokal auf deinem Server. Wir richten es mit Docker Compose ein und erklären die Konfiguration Zeile für Zeile.

Warum Stirling PDF?

• Alles bleibt lokal: Dateien verlassen deinen Server nicht – relevant für Verträge, Belege und andere sensible Dokumente.
• Über 30 Werkzeuge in einer UI: Zusammenfügen & Teilen, Drehen, Komprimieren, PDF/A-Konvertierung, Wasserzeichen, Formulare ausfüllen, Metadaten bearbeiten, Seiten als Bilder exportieren und vieles mehr.
• Konvertierung ohne Cloud: PDF ↔ Office (LibreOffice), Bilder und HTML; dazu OCR über Tesseract, damit gescannte Dokumente durchsuchbar werden.
• Anpassbar: eigener Name, Beschreibung und Navbar-Text in der Oberfläche, deutsche Lokalisierung, eigene HTML-Dateien.
• Ressourcenfreundlich: ein einzelner Container; CPU-/RAM-Limits lassen sich (wie unten) direkt setzen.

Die Konfiguration hier ist unsere Produktiv-Variante: Die Oberfläche lauscht nur auf dem Loopback hinter einem Reverse Proxy, das Login ist bewusst deaktiviert (dazu unten mehr im Sicherheits-Kasten) und Tesseract-Sprachdaten sowie Konfiguration liegen als Volumes außerhalb des Containers.

Vorbereitung: Ordner & OCR-Sprachen

sudo mkdir -p /opt/stacks/spdf/{trainingData1,extraConfigs1,customFiles1}
cd /opt/stacks/spdf

• trainingData1 – Tesseract-Sprachdaten (OCR). Der Container erwartet sie unter /usr/share/tesseract-ocr/5/tessdata; standardmäßig ist nur Englisch dabei, weitere Sprachen lädst du selbst nach (siehe § OCR).
• extraConfigs1 – der Konfigurationsordner (/configs). Beim ersten Start legt Stirling PDF dort eine settings.yml an; Umgebungsvariablen überschreiben die Datei, für fortgeschrittene Einstellungen (etwa Pipelines) editierst du sie direkt.
• customFiles1 – optionaler Ordner für eigene statische Dateien (z. B. angepasste HTML-Seiten), die Stirling in die Oberfläche einbindet – nur relevant, wenn SYSTEM_CUSTOMHTMLFILES aktiv ist.

docker-compose.yml – die Konfiguration

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    ports:
      - "127.0.0.1:50514:8080"   # Web-UI nur lokal
    volumes:
      - /opt/stacks/spdf/trainingData1:/usr/share/tesseract-ocr/5/tessdata:rw
      - /opt/stacks/spdf/extraConfigs1:/configs:rw
      - /opt/stacks/spdf/customFiles1:/customFiles/
    environment:
      # Login (aktueller Variablenname; DOCKER_ENABLE_SECURITY ist der alte Alias)
      SECURITY_ENABLELOGIN: "false"
      DISABLE_ADDITIONAL_FEATURES: "true"
      SYSTEM_DEFAULTLOCALE: de-DE
      UI_APPNAME: Online PDF Editor
      UI_HOMEDESCRIPTION: Easily rotate, convert or compress PDF files
      UI_APPNAMENAVBAR: pdf.meine.domain
      SYSTEM_MAXFILESIZE: "110"
      METRICS_ENABLED: "false"
      SYSTEM_GOOGLEVISIBILITY: "false"
      SYSTEM_CUSTOMHTMLFILES: "true"
      SHOW_SURVEY: "false"
    deploy:
      resources:
        limits:
          cpus: "4.0"
          memory: 4G
    restart: unless-stopped

Gegenüber der Vorlage sind vier Dinge bereinigt: der leere networks: {}-Block und das damit überflüssige network_mode: bridge (beides unnötig – bridge ist das Standard-Netz), die doppelte Login-Variable DOCKER_ENABLE_SECURITY (alter Name, siehe Env-Abschnitt) sowie fehlende Anführungszeichen bei den Werten.

Die Bausteine:

• ports: 127.0.0.1:50514:8080 – Stirling-PDFs Web-UI (Container-Port 8080) nur auf dem Loopback. Zugriff von außen ausschließlich über den Reverse Proxy.
• deploy.resources.limits – 4 CPUs / 4 GB RAM: PDF-Konvertierungen und OCR sind rechenintensiv, das Limit verhindert aber, dass ein einzelner Upload den Host lahmlegt.
• SYSTEM_MAXFILESIZE: "110" – maximale Upload-Größe in MB. Beachte: Auch Reverse Proxy und Webbrowser haben eigene Limits, die du bei größeren Werten mitziehen musst.

Die Umgebungsvariablen im Detail

Erster Start & die wichtigsten Werkzeuge

cd /opt/stacks/spdf
docker compose up -d
docker compose logs -f stirling-pdf   # Warten bis „Started" erscheint

Danach ist die Werkbank unter http://127.0.0.1:50514 erreichbar (bzw. per SSH-Tunnel: ssh -L 50514:127.0.0.1:50514 dein-server). Beim ersten Start erzeugt Stirling die settings.yml unter extraConfigs1 – kurz prüfen, ob sie angelegt wurde. Die Werkzeuge sind in Kategorien sortiert:

• Konvertieren: PDF → Word/PowerPoint/Excel/Bilder/HTML und zurück.
• Organisieren: Zusammenfügen, Teilen, Drehen, Seiten neu anordnen, Nummerieren.
• Komprimieren & Optimieren: Dateigröße reduzieren, PDF/A umwandeln.
• Sicherheit: Passwort setzen/entfernen, Berechtigungen einschränken, Wasserzeichen, digital signieren.
• OCR & Bearbeiten: gescannte PDFs durchsuchbar machen, Text/Bilder einfügen, Metadaten pflegen.

OCR: Weitere Sprachen installieren

Die OCR-Werkzeuge („Bild zu Text“, „Scan & OCR“) nutzen Tesseract. Im Image ist nur Englisch enthalten – für deutsche Dokumente lädst du die Sprachdaten in den trainingData1-Ordner. Es gibt die schnellen tessdata_fast-Modelle (empfohlen) und die genaueren, aber langsameren tessdata_best:

cd /opt/stacks/spdf/trainingData1

# Deutsch + Englisch (schnelle Modelle)
curl -L -O https://github.com/tesseract-ocr/tessdata_fast/raw/main/deu.traineddata
curl -L -O https://github.com/tesseract-ocr/tessdata_fast/raw/main/eng.traineddata

# Rechte nicht vergessen (Container muss lesen können)
sudo chown -R 1000:1000 /opt/stacks/spdf/trainingData1

# Sprachliste in der UI aktualisieren
cd /opt/stacks/spdf && docker compose restart stirling-pdf

Danach steht „Deutsch“ in der OCR-Sprachauswahl. Weitere Sprachen: einfach den passenden xxx.traineddata herunterladen (Kürzel wie fra, spa, …) und neu starten.

Zugriff von außen: Reverse Proxy & Login

# Caddyfile
pdf.meine.domain {
    encode zstd gzip
    reverse_proxy 127.0.0.1:50514
}

Da die UI auf dem Loopback lauscht, ist die Konfiguration simpel: Der Proxy reicht an 127.0.0.1:50514 durch. Wer die Oberfläche öffentlich erreichbar macht, sollte den Login aktivieren – und die Standard-Zugangsdaten ändern:

    environment:
      SECURITY_ENABLELOGIN: "true"
      # Nach dem ersten Login unter „Einstellungen" das Passwort ändern –
      # die Werkseinstellung ist admin / stirling!

Alternativ den Login aus lassen, dafür aber eine Authentifizierungsebene vor den Proxy setzen (etwa Authelia/Authentik) – so bleibt Stirling PDF selbst ohne Login-Logik abgeschottet.

Updates & Backups

cd /opt/stacks/spdf
docker compose pull
docker compose up -d

• Backup = extraConfigs1/: Dort liegt deine settings.yml (inkl. eventueller Login-/OAuth-Konfiguration). Diesen Ordner regelmäßig sichern.
• OCR-Sprachdaten sind wiederverwendbar – einfach mitkopieren, dann ist nach einem Neuaufbau kein erneuter Download nötig.
• Versions-Tag: :latest funktioniert, aber Stirling PDF erscheint häufig in neuen Versionen. Wer kontrolliert aktualisieren will, pinnt auf ein konkretes Tag aus der Docker-Hub-Übersicht.

Fehlerbehebung: Die häufigsten Stolperfallen

Fazit

Stirling PDF ersetzt für den Alltag zuverlässig die teure Adobe-Suite oder dubiose Online-Konverter: Die Werkzeuge sind schnell, die Bedienung erinnert an moderne Web-Apps, und sensible Dokumente verlassen nie deine Infrastruktur. Wer einmal den Stack stehen hat, bekommt mit ein paar Tesseract-Sprachdateien auch gescannte Archive durchsuchbar – ein Werkzeug, das man nicht mehr missen möchte.