Stirling PDF Docker Compose: PDF-Werkzeuge ohne Cloud

Der Bescheid ist eingescannt, elf Seiten, 28 MB, und das Upload-Feld beim Steuerberater nimmt höchstens zehn. Also tippst du „pdf verkleinern“ in die Suchmaschine, klickst den ersten Treffer an und ziehst die Datei hinein. Ein paar Sekunden später ist sie klein genug. Und deine Steuer-ID, deine Adresse und dein Einkommen sind gerade über einen Server gelaufen, von dem du weder weißt, wo er steht, noch wer ihn betreibt.

Stirling PDF erledigt dasselbe auf deinem eigenen Rechner. Verkleinern, zusammenführen, Seiten drehen und sortieren, Text in Scans erkennbar machen, schwärzen, unterschreiben: Die Werkzeugliste in der Doku hat über fünfzig Einträge, und alles läuft in einem Container in deinem Heimnetz. Am Ende dieser Anleitung erreichst du Stirling PDF unter einer festen Adresse, mit eigenem Admin-Passwort, einem Ersatzschlüssel, abgeschalteter Nutzungsstatistik, fester Version und einem Plan für Backup und Updates.

Was Stirling PDF ist, und wo deine Dateien bleiben

Stirling PDF ist eine Weboberfläche, hinter der bekannte Werkzeuge arbeiten, die alle mit im Image stecken: LibreOffice für Word- und Excel-Dateien, Tesseract und OCRmyPDF für die Texterkennung, dazu Ghostscript, QPDF und ImageMagick. Texterkennung, kurz OCR, heißt: Aus dem Foto einer Seite wird Text, den du markieren, kopieren und durchsuchen kannst. Deutsch erkennt das Standard-Image laut Doku ohne Nachrüsten, ebenso Englisch, Französisch, Portugiesisch und vereinfachtes Chinesisch.

Wo die Dateien dabei liegen, beantwortet die Doku knapp: Verarbeitet wird auf dem Server, gespeichert wird dort nur, was du ausdrücklich speicherst. Alles andere bleibt in deinem Browser. Auf dem eigenen Server gehört dir ohnehin beides; der Unterschied zählt erst, wenn die Familie mitbenutzt, und dazu kommen wir unten.

Das Projekt nennt sich selbst Open Core: Der Kern ist offen, einige Firmenfunktionen kosten Geld, und es gibt Stirling PDF auch als Cloud-Dienst. Selbst gehostet läuft der Server ohne Lizenzschlüssel im Free-Plan. Der umfasst jedes PDF-Werkzeug, die Programmierschnittstelle und fünf Benutzer. Bezahlt werden Cluster-Betrieb, S3-Speicher, SAML-Anmeldung und Audit-Protokolle. Das ist Firmenkram. Einem Haushalt fehlt im Free-Plan nichts.

Was du brauchst

• Einen Linux-Rechner mit Docker und dem Compose-Plugin. Die Images gibt es für x86-Prozessoren (amd64) und 64-Bit-ARM (arm64), also auch für einen Raspberry Pi mit 64-Bit-System. Wenn Compose für dich noch neu ist: Die Grundlagen stehen in einem eigenen Beitrag.
• Arbeitsspeicher: Die Doku empfiehlt für das Standard-Image 4 GB, ausgelegt auf bis zu zehn Benutzer. Ein Raspberry Pi mit 4 GB ist damit voll belegt; ich würde Stirling erst auf einem Rechner mit 8 GB einziehen lassen.
• Ein paar Gigabyte freien Platz. Das Image ist schon komprimiert knapp 1,2 GB groß, weil LibreOffice und die OCR-Werkzeuge mit drinstecken.
• Port 8080 frei. Der ist beliebt; was du tust, wenn ihn schon ein anderer Dienst hat, steht in Schritt 1.

Sechs Prüfungen vorab, alle auf dem Docker-Rechner:

docker --version
docker compose version
uname -m
free -h
df -h /var/lib/docker
ss -tulpn | grep :8080 || echo "Port frei"

Die ersten beiden antworten mit einer Versionsnummer. uname -m sagt x86_64 oder aarch64; steht dort armv7l, läuft ein 32-Bit-System, und dafür gibt es kein Image. Bei free -h zählt in der Zeile Speicher (englisch Mem) die letzte Spalte, verfügbar oder available: Steht dort weniger als 4 Gi, lies vorher den Speicher-Punkt unter „Wo es klemmt“. df -h zeigt in der Spalte Verf. oder Avail, wie viel Platz Docker für Images hat. Der letzte Befehl meldet „Port frei“ oder zeigt die Zeile des Dienstes, der 8080 schon belegt.

Alle Beispielwerte stehen hier einmal gesammelt. Du ersetzt sie durch deine und musst danach nichts mehr nachschlagen.

Schritt 1: Ordner und Bauplan anlegen

Stirling PDF bekommt einen eigenen Ordner im Home-Verzeichnis, darin die Compose-Datei. nano öffnet eine leere Datei; Inhalt einfügen, mit Strg+O und Enter speichern, mit Strg+X schließen.

mkdir ~/stirling-pdf
cd ~/stirling-pdf
nano compose.yaml

Der Inhalt folgt dem Compose-Beispiel aus der Docker-Anleitung von Stirling PDF. Ich habe die Version festgenagelt, drei der sechs Ordner weggelassen, die du am Anfang nicht brauchst, und zwei Einstellungen ergänzt, beide aus der Doku.

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:3.2.2
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - SYSTEM_DEFAULTLOCALE=de-DE
      - SYSTEM_ENABLEANALYTICS=false
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/storage:/storage
    mem_limit: 4g

Was die Zeilen tun:

• image mit 3.2.2, der Version vom 24-10-2026. Die Produktions-Checkliste der Doku rät ausdrücklich, eine Versionsnummer statt latest einzutragen, damit Updates dann passieren, wenn du sie willst. Bei diesem Projekt ist das kein Formalismus: Zwischen dem 01-10 und dem 24-10-2026 erschienen fünf Versionen. Das Image kommt von Docker Hub. Die Doku nennt zuerst die projekteigene Adresse docker.stirlingpdf.com und empfiehlt Docker Hub selbst für den Fall, dass die nicht lädt.
• Vom Image gibt es drei Varianten, und die Wahl ist eine Sicherheitsfrage. Die normale, die du hier nimmst, bringt Anmeldung, Benutzerverwaltung und alle Werkzeuge mit und will 4 GB. -fat legt eine KI-Komponente obendrauf, die aus bleibt, bis man sie einschaltet, und will 6 GB. -ultra-lite kommt mit 2 GB aus, kann dafür kein OCR und keine Office-Umwandlung und hat überhaupt keine Anmeldung: Jeder, der den Port erreicht, kann es benutzen.
• "8080:8080": links der Port auf deinem Rechner, rechts der im Container. Ist 8080 bei dir belegt, änderst du nur die linke Zahl, etwa auf "8081:8080", und die Adresse im Browser endet dann auf :8081.
• SYSTEM_DEFAULTLOCALE=de-DE stellt die Oberfläche für alle auf Deutsch, die keine eigene Sprache gewählt haben. Ohne die Zeile nimmt Stirling die Sprache des Browsers und sonst Englisch.
• SYSTEM_ENABLEANALYTICS=false ist der Hauptschalter für die Nutzungsstatistik. Was sie senden würde, steht unten bei „Was am Ende eingestellt ist“.
• Die drei Ordner unter stirling-data: In configs liegen die Einstellungen, die eingebaute Datenbank mit allen Benutzern und die Schlüssel, die Stirling beim ersten Start erzeugt. Die Doku sagt dazu: immer einbinden. storage nimmt die Dateien auf, die jemand ausdrücklich auf dem Server speichert, ebenfalls Pflicht. logs sind die Protokolle. Weggelassen habe ich customFiles für eigenes Logo und Unterschriftsbilder, pipeline für überwachte Ordner und tessdata für zusätzliche OCR-Sprachen. Alle drei lassen sich später nachrüsten.
• mem_limit: 4g ist mehr als eine Obergrenze. Stirling ist ein Java-Programm, und das Image bemisst dessen Arbeitsspeicher an genau dieser Grenze. Fehlt sie, rechnet es mit dem gesamten RAM des Rechners; die Doku schreibt dazu knapp, man solle immer eine setzen.

Ob Compose die Datei versteht, prüfst du ohne Start. Kommt OK, stimmt die Einrückung; kommt eine Fehlermeldung mit Zeilennummer, ist meist ein Leerzeichen verrutscht.

docker compose config --quiet && echo OK

Schritt 2: Starten und prüfen

docker compose up -d
docker compose ps

Docker lädt jetzt gut ein Gigabyte, und je nach Leitung dauert das ein paar Minuten. Danach steht bei STATUS ein Up. Das heißt nur, dass der Container läuft. Das Java-Programm darin braucht nach dem Start noch eine Weile, bis es antwortet. Wann es so weit ist, verrät eine Status-Adresse, die die Doku genau für solche Prüfungen nennt und die ohne Anmeldung antwortet:

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/api/v1/info/status

200

Die 200 ist der erste Beweis, dass Stirling lebt. Kommt 000, fährt es noch hoch: eine halbe Minute warten, Befehl wiederholen. Meldet das Terminal stattdessen, dass es curl nicht kennt, holst du es nach:

sudo apt install curl

Bleibt es auch nach ein paar Minuten bei 000, steht der Grund im Protokoll. Die Doku hat dafür einen Satz, den ich mir für jede Fehlersuche merken würde: Der erste Fehler nennt meist die Ursache.

docker compose logs --tail 50

Beim Start hat Docker auch die drei Datenordner angelegt. Ein Blick hinein bestätigt, dass die Pfade aus der Compose-Datei angekommen sind:

ls stirling-data

configs  logs  storage

Schritt 3: Die erste Anmeldung

Beim allerersten Start, solange die Benutzerdatenbank leer ist, legt Stirling ein Konto admin mit dem Passwort stirling an. Das steht in der Doku und damit in jeder Suchmaschine. Deshalb verlangt Stirling bei dieser ersten Anmeldung sofort ein neues.

Danach siehst du die Arbeitsfläche mit der Werkzeugliste, auf Deutsch. Was du nicht siehst, ist ebenfalls ein Ergebnis: keine Frage, ob du helfen möchtest, Stirling PDF besser zu machen. Ohne SYSTEM_ENABLEANALYTICS=false hätte Stirling dich als ersten Admin genau das gefragt, und nach einem Ja bekäme jeder Benutzer beim ersten Besuch ein Cookie-Banner.

Das neue Passwort gehört sofort in den Passwort-Manager. Nach fünf falschen Versuchen sperrt Stirling ein Konto für 120 Minuten, so steht es in der Produktions-Checkliste. Gegen Leute, die Passwörter durchprobieren, ist das gut. Für dich heißt es: zwei Stunden Pause, wenn du dich fünfmal vertippst.

Schritt 4: Die Probe, zwei PDFs und ein Scan

Ein Dienst ist erst eingerichtet, wenn er einmal gearbeitet hat. Für die Probe brauchst du zwei beliebige PDF-Dateien und, für den zweiten Teil, einen Scan oder ein abfotografiertes Dokument als PDF, gern etwas Unwichtiges.

Die Seitenzahl der neuen Datei ist die Summe der beiden Originale, in der Reihenfolge, die das Werkzeug angezeigt hat. Zwei Optionen im Werkzeug lohnen einen Blick: ein Inhaltsverzeichnis mit Sprungmarken, benannt nach den Originaldateien, und das Entfernen digitaler Signaturen, die das Zusammenführen ohnehin ungültig machen würde.

Jetzt das Werkzeug, für das ich Stirling eigentlich installieren würde: die Texterkennung.

Findet dein PDF-Programm das Wort, liegt jetzt unter dem Bild der Seite eine Textebene. Das ist der Moment, in dem aus einem Foto ein Dokument wird. Der Modus Auto lässt Seiten aus, die schon Text haben; Erzwingen erkennt alles neu und ersetzt vorhandenen Text, Strikt bricht ab, sobald eine Seite Text enthält. Für gemischte Stapel aus Scans und echten PDFs ist Auto richtig.

Und der Steuerbescheid vom Anfang? Das Werkzeug dafür heißt Komprimieren und bietet zwei Wege: eine Qualitätsstufe von 1 bis 9, Vorgabe 5, wobei höher kleiner und unschärfer heißt, oder eine Wunschgröße in KB oder MB, der Stirling so nahe kommt, wie es geht. Für ein Upload-Feld mit Grenze ist die Wunschgröße der direkte Weg.

Was am Ende eingestellt ist

Stirling läuft, und das Standardpasswort ist Geschichte. Fünf Dinge gehören noch dazu.

1. Ein zweites Admin-Konto als Ersatzschlüssel. Die Doku beschreibt keinen Weg, ein vergessenes Admin-Passwort von außen zurückzusetzen. Die beiden Umgebungsvariablen, mit denen man den ersten Admin vorab festlegen kann, ignoriert Stirling, sobald Benutzer in der Datenbank stehen. Ein zweiter Admin dagegen kann dein Passwort jederzeit neu setzen. Zwei Minuten Arbeit, die dir später einen Neuanfang ersparen.

In der Liste steht jetzt ersatz-admin mit der Rolle Admin, und wenn die Probeanmeldung geklappt hat, wandert auch dieses Passwort in den Manager. Familienmitglieder legst du genauso an, mit der Rolle Mitglied und dem Haken bei der Passwortänderung, den Stirling für neue Konten von selbst setzt. Zum Mitzählen: Der Free-Plan erlaubt fünf Benutzer, zwei Plätze belegen jetzt die Admins.

2. Die Statistik bleibt aus. Die Doku listet offen auf, was eingeschaltete Analysen senden würden: vom Server an den Dienst PostHog unter anderem Version, Betriebssystem, Benutzerzahl und wie oft welche PDF-Funktion lief; aus dem Browser, wenn der Benutzer zustimmt, benutzte Werkzeuge, Klicks und aufgerufene Seiten, die Seiten zusätzlich an den Dienst Scarf. Dokumentinhalte nie. Das ist harmlos, und trotzdem bleibt die Zeile bei mir drin. Wer einen PDF-Dienst ins Haus holt, damit Daten im Haus bleiben, braucht keinen, der Nutzungszahlen nach draußen meldet. Weil der Schalter als Umgebungsvariable gesetzt ist, dreht ihn auch niemand versehentlich in der Oberfläche um. Die Konfigurationsseite sagt dazu: Änderungen in der App bleiben dann wirkungslos.

3. Was auf dem Server liegen darf. Der Dateispeicher auf dem Server ist ab Werk an. Wer in der Oberfläche Auf Server hochladen wählt, legt die Datei in stirling-data/storage ab, und von dort lässt sie sich mit anderen Benutzern teilen. Freigabelinks laufen nach drei Tagen ab, und wer sie öffnet, muss sich anmelden. Ich würde den Speicher abschalten, solange ihn niemand vermisst. Stirling ist die Werkbank, für das Archiv gibt es Paperless-ngx oder Nextcloud, und eine Werkbank, auf der nichts liegen bleibt, muss man auch nicht sichern. Dafür kommt in ~/stirling-pdf/compose.yaml im Abschnitt environment des Dienstes stirling-pdf eine Zeile dazu:

cd ~/stirling-pdf
nano compose.yaml

      - STORAGE_ENABLED=false

docker compose up -d

Antwortet die Status-Adresse aus Schritt 2 danach wieder mit 200, läuft Stirling mit der neuen Einstellung.

4. Das Backup. Das Herz ist configs: Einstellungen, Schlüssel und die Datenbank mit allen Konten. Stirling sichert die Datenbank zwar jede Nacht selbst nach configs/backup/db/, aber auf dieselbe Platte, und die Doku rät, diese Sicherungen vom Server wegzukopieren. Dazu kommt storage, falls der Speicher an ist. Wer Kopia nach unserer Anleitung betreibt und das Home-Verzeichnis sichert, hat ~/stirling-pdf schon im Tresor. Für eine schnelle Kopie von Hand, etwa vor einem Update, hält die Doku den Server kurz an:

cd ~/stirling-pdf
docker compose stop
sudo cp -a stirling-data/configs configs-backup-$(date +%F)
docker compose start
ls

Das ls zeigt den neuen Ordner configs-backup- mit dem heutigen Datum neben compose.yaml. Das sudo steht dort, weil der Container laut Doku unter der Benutzernummer 1000 läuft und seine Dateien so anlegt; ist das nicht deine Nummer, darfst du ohne sudo nicht alles lesen. cp -a behält Besitzer und Rechte, damit eine Rückkopie später genau so wieder passt. Nach dem start braucht Stirling etwa 20 Sekunden, bis es wieder antwortet.

5. Updates mit Ansage. Fünf Versionen in gut drei Wochen heißt nicht, dass du jede mitnehmen musst. Ich würde einmal im Monat auf die Release-Seite schauen und sofort nur dann, wenn dort von Sicherheit die Rede ist. Ein Update sind vier Handgriffe: Release-Notes lesen, configs sichern wie eben, die Versionsnummer ersetzen, neu ziehen.

cd ~/stirling-pdf
nano compose.yaml

docker compose pull
docker compose up -d

Danach wieder die Status-Adresse aus Schritt 2 fragen: Kommt 200, ist das Update durch.

Was offen bleibt: Stirling spricht HTTP ohne Verschlüsselung. Im Heimnetz ist das vertretbar, ins Internet gehört Port 8080 so nie, auch nicht per Portfreigabe im Router. Wer unterwegs PDFs bearbeiten will, wählt sich per VPN ins Heimnetz ein oder stellt einen Reverse Proxy mit HTTPS davor. Beim Proxy wartet allerdings eine Falle, und die steht gleich als Erstes unten.

Wo es klemmt

Hinter dem Reverse Proxy scheitern große Dateien. Der Klassiker, und er sieht aus wie ein Speicherproblem. Im Issue #1215 auf GitHub wollte olivier-belleval zwei PDFs mit 33 und 29 MB zusammenführen, auf einem Server mit 4 GB RAM, bekam einen Fehler und tippte auf zu wenig Speicher. dogthor1st antwortete: nicht der RAM, sondern wahrscheinlich der Reverse Proxy, denn Nginx lässt ab Werk nur Uploads bis 1 MB durch. Mit höherem Limit lief es. Die FAQ von Stirling beschreibt die Anzeichen: Der Upload scheitert, oder der Browser lädt statt des Ergebnisses eine .htm-Datei herunter. Die passenden Zeilen stehen in der Produktions-Checkliste; die 2000M entsprechen dem Upload-Limit, das Stirling selbst ab Werk hat.

client_max_body_size 2000M;
proxy_buffering off;
proxy_read_timeout 1800s;
proxy_send_timeout 1800s;

Admin-Passwort vergessen. Naheliegend wäre: SECURITY_INITIALLOGIN_USERNAME und SECURITY_INITIALLOGIN_PASSWORD in die Compose-Datei, neu starten. Das tut nichts: Wie bei Punkt 1 erwähnt, ignoriert Stirling beide, sobald die Datenbank Benutzer hat. Hast du den Ersatz-Admin aus Punkt 1, meldest du dich damit an und setzt das Passwort in der Benutzerliste über Passwort zurücksetzen neu. Ohne zweiten Admin bleibt nur ein Neuanfang. Die Doku beschreibt diesen Weg nicht; er folgt aus dem, was sie über den ersten Start sagt: Bei leerer Benutzerdatenbank legt Stirling wieder admin mit stirling an. Den alten Ordner benennst du dafür um, statt ihn zu löschen, aber alle Konten und Einstellungen sind danach weg.

cd ~/stirling-pdf
docker compose down
sudo mv stirling-data/configs stirling-data/configs-alt
docker compose up -d

Nach dem Start braucht Stirling etwa eine halbe Minute, bis es antwortet. Danach beginnt Schritt 3 von vorn, mit admin und stirling.

Der Container startet bei großen Aufträgen neu. Texterkennung, Office-Umwandlung und Kompression stuft die Performance-Seite der Doku als speicherhungrig ein, und ein einzelnes großes PDF kann während der Verarbeitung ein Vielfaches seiner Dateigröße belegen. Stürzt Stirling dabei ab, holt restart: unless-stopped es zurück, und von außen sieht es aus, als hätte die Seite kurz gehakt. Docker zählt mit:

docker inspect stirling-pdf --format '{{.RestartCount}}'

0

Steht dort mehr als 0, ist der Container seit seinem Start abgestürzt und wieder hochgekommen. Dann hilft mehr Speicher für den Container, wenn der Rechner ihn hat, oder kleinere Häppchen: lieber zehn Scans einzeln durch die Texterkennung als einen mit 300 Seiten. Die Variante -ultra-lite wäre sparsamer, aber ohne OCR und ohne Anmeldung ist sie für das, was diese Anleitung will, die falsche.

Lohnt sich der Brocken?

Ich würde Stirling PDF jedem empfehlen, der regelmäßig Post von Ämtern, Banken und Arztpraxen bekommt und sie digital weitergeben muss. Genau diese Dokumente landen sonst auf Webseiten, die man nicht kennt. Der Preis gehört ehrlich dazu: gut ein Gigabyte Image, 4 GB Arbeitsspeicher, die ein kleiner Pi nicht übrig hat, und ein Projekt, das schneller veröffentlicht, als man Release-Notes lesen mag. Dafür ersetzt ein Container eine ganze Sammlung von PDF-Webseiten, und die Texterkennung allein ist den Platz wert.

Welches Dokument hast du schon einmal auf eine PDF-Webseite geladen und es hinterher bereut? Und fehlt dir in Stirling ein Werkzeug, das du bisher woanders erledigst? Erzähl's mir in den Kommentaren.

Stirling bearbeitet PDFs, es verwahrt sie nicht. Wer den frisch erkannten Scan nicht im Download-Ordner vergessen will, findet das Archiv dazu in der Paperless-ngx-Anleitung, mit eigener Texterkennung und Volltextsuche.

Quellen

• Stirling-PDF-Doku: Docker (Compose-Beispiel, Image-Varianten, Ordner, Standard-Login, UID 1000)
• Stirling-PDF-Doku: Production checklist (Version festnageln, Login-Sperre, Nginx-Zeilen, Upload-Limit, Backup)
• Stirling-PDF-Doku: Configuration (settings.yml, Umgebungsvariablen, defaultLocale)
• Stirling-PDF-Doku: Sign-in & security (erstes Admin-Konto, Passwortwechsel, SECURITY_INITIALLOGIN_*)
• Stirling-PDF-Doku: Analytics and telemetry (SYSTEM_ENABLEANALYTICS, gesendete Daten)
• Stirling-PDF-Doku: Plans and licences (Free-Plan, fünf Benutzer)
• Stirling-PDF-Doku: File storage (Server-Speicher, Freigabelinks, STORAGE_ENABLED)
• Stirling-PDF-Doku: OCR languages (mitgelieferte Sprachen)
• Stirling-PDF-Doku: Performance (Speicherbedarf der Werkzeuge, Speichergrenze setzen)
• Stirling-PDF-Doku: Upgrading (docker compose pull, configs sichern)
• Stirling-PDF-Doku: Server FAQ (Proxy-Upload, Java-Speicher, Docker Hub als Ausweich-Quelle, Logs)
• Stirling-PDF-Doku: Werkzeugliste und Tools-FAQ (wo Dateien verarbeitet und gespeichert werden)
• Stirling-PDF-Doku: OCR, Compress und Page operations (Merge)
• Stirling-PDF-Doku: Files and sharing (lokal im Browser oder auf dem Server)
• Stirling PDF auf GitHub (Open Core) und Releases 3.0.2 bis 3.2.2
• Deutsche Texte der Oberfläche (translation.toml)
• Docker Hub: stirlingtools/stirling-pdf, Tags und Größe
• GitHub-Issue #1215: Merge large pdf cause an error