Wie man LibreOffice im Headless-Modus in einem Docker-Container ausführt

Ein häufiges serverseitiges Problem erscheint zunächst einfach: Eine Anwendung empfängt eine DOCX-, XLSX-, ODT- oder PPTX-Datei und soll eine PDF-Datei zurückgeben, der Host darf aber keine Desktop-Sitzung ausführen. Die Installation einer kompletten Office-Suite direkt auf dem Host erschwert zudem die Reproduktion von Bereitstellungen. LibreOffice kann zwar ohne grafische Oberfläche ausgeführt werden, und Docker kann die Konvertierungs-Laufzeitumgebung isolieren, doch zuverlässige Ergebnisse erfordern mehr als nur das Hinzufügen --headlesseines Befehls.

Die praktischen Ursachen der meisten Fehler sind vorhersehbar: Das Image enthält nicht die benötigte LibreOffice-Komponente, der Container kann sein Benutzerprofil nicht schreiben, eingebundene Dateien haben die falschen Berechtigungen, Schriftarten fehlen, zwei Aufträge verwenden dasselbe Profil oder das Ausgabeverzeichnis ist nicht beschreibbar. Diese Anleitung beginnt mit dem einfachsten funktionierenden Container und optimiert ihn anschließend für die reproduzierbare Dokumentkonvertierung.

Stand Oktober 2026 listet LibreOffice Version 26.8 als neuesten Feature-Branch und 26.2.6 als bewährten Vorgänger-Branch, der für den Unternehmenseinsatz empfohlen wird. Die stabilen Pakete von Debian 13 können eine andere, von der Distribution selbst verwaltete LibreOffice-Version enthalten. Daher sollten Sie das Basis-Image festlegen und die tatsächliche Version in Ihrem erstellten Container überprüfen, anstatt anzunehmen, dass sie mit der Upstream-Version übereinstimmt. Weitere Informationen finden Sie in den offiziellen LibreOffice-Versionshinweisen und auf der Debian-Paketseite für libreoffice-nogui .

Was „headless LibreOffice in Docker“ tatsächlich bedeutet

LibreOffice-Dokumente --headlesswerden in einem Modus ohne Benutzeroberfläche ausgeführt. Für die Dateikonvertierung sind die Optionen `--convert` --convert-tound ` --convert` wichtig --outdir. LibreOffice benötigt außerdem Schreibzugriff auf sein Benutzerprofilverzeichnis. Dies ist relevant, wenn Sie einen Container als Benutzer ohne Root-Rechte ausführen oder das Root-Dateisystem schreibgeschützt machen. Die maßgebliche Dokumentation zur Befehlszeilenschnittstelle finden Sie in der LibreOffice-Hilfe: Starten der LibreOffice-Software mit Parametern .

Das Ziel eines guten Containers ist daher spezifisch: Er sollte ohne X11 oder Desktop starten, ein Eingabedokument lesen, das erwartete Ausgabeformat schreiben, sauber beendet werden und eine Datei erzeugen, deren Layout für Ihre Arbeitslast akzeptabel ist.

Schritt 1: Erstellen Sie ein kleines, reproduzierbares Docker-Image

Für eine umfassende Formatabdeckung unter Debian 13 libreoffice-noguiist dies ein nützlicher Ausgangspunkt, da Debian es als das Metapaket ohne grafische Benutzeroberfläche beschreibt, das hauptsächlich für Skripte gedacht ist. Wenn Sie nur Writer-Dokumente konvertieren, können Sie die Abhängigkeiten reduzieren, indem libreoffice-writer-noguiSie nur die anderen benötigten Komponenten ohne grafische Benutzeroberfläche installieren.

FROM debian:13-slim

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
    libreoffice-nogui \
    fonts-dejavu-core \
    fonts-liberation2 \
    fonts-crosextra-carlito \
    fonts-crosextra-caladea \
    ca-certificates \
 && rm -rf /var/lib/apt/lists/*

RUN useradd --create-home --uid 10001 office

WORKDIR /work
USER office

ENTRYPOINT ["soffice","--headless","--nologo","--nodefault","--norestore"]

Die Schriftartenpakete sind nicht rein kosmetischer Natur. Office-Dokumente verwenden häufig Schriftarten, die in einem minimalen Linux-Image nicht installiert sind. LibreOffice verwendet in diesem Fall eine alternative Schriftart, was Auswirkungen auf Zeilenumbruch, Seitenzahl, Tabellenbreite und Folienlayout haben kann. Carlito und Caladea sind gängige, metrisch kompatible Alternativen zu Calibri und Cambria, während Liberation und DejaVu viele Anwendungsfälle abdecken. Wenn Ihre Dokumente firmeneigene oder lizenzierte Schriftarten verwenden, installieren oder binden Sie diese nur ein, wenn Ihre Lizenz dies erlaubt.

Schritt 2: Erstellen Sie das Image und notieren Sie die LibreOffice-Version.

docker build -t libreoffice-headless:debian13 .

Überprüfen Sie anschließend die Version, die tatsächlich im Bild enthalten ist:

docker run --rm --entrypoint soffice   libreoffice-headless:debian13 --version

Diese Prüfung ist wichtig, wenn ein Basisimage Wochen später neu erstellt wird. Wenn eine exakte Darstellung entscheidend ist, verwenden Sie in der Produktion einen unveränderlichen Image-Digest und erstellen Sie das Image nach Sicherheitsupdates oder LibreOffice-Aktualisierungen gezielt neu. „Neueste“-Tags sind zwar während Experimenten praktisch, erschweren aber die Untersuchung von Ausgabeunterschieden.

Schritt 3: Separate Eingabe- und Ausgabeverzeichnisse vorbereiten

Erstellen Sie zwei Hostverzeichnisse. Das Eingabeverzeichnis kann schreibgeschützt sein; das Ausgabeverzeichnis muss für den Containerbenutzer beschreibbar sein.

mkdir -p input output
cp sample.docx input/

Docker empfiehlt die --mountSyntax für Bind-Mounts. In der Dokumentation wird außerdem darauf hingewiesen, dass Bind-Mounts standardmäßig beschreibbar sind. Daher ist es eine sinnvolle Sicherheitsmaßnahme, das Quellverzeichnis explizit auf schreibgeschützt zu setzen. Siehe Docker-Dokumentation zu Bind-Mounts .

Schritt 4: Ein Dokument in PDF konvertieren

Starten Sie einen temporären Container und binden Sie das Quellverzeichnis schreibgeschützt ein:

docker run --rm   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   libreoffice-headless:debian13   --convert-to pdf   --outdir /output   /input/sample.docx

LibreOffice unterstützt dieses --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]Format offiziell. Für eine einfache Konvertierung von Writer-Dateien in PDF-Dateien --convert-to pdfwählt LibreOffice automatisch den passenden PDF-Exportfilter aus. Benötigen Sie ein bestimmtes PDF-Verhalten, dokumentiert LibreOffice auch die Filterparameter; siehe die offizielle PDF-CLI-Parameterreferenz .

Schritt 5: Weisen Sie jedem gleichzeitig laufenden Auftrag ein eigenes LibreOffice-Profil zu.

Eine einzelne Konvertierung funktioniert oft ohne zusätzliche Profilkonfiguration, wodurch ein Skalierungsproblem verschleiert werden kann. LibreOffice speichert den Status in einem Benutzerprofil und benötigt Schreibzugriff darauf. Parallele Prozesse sollten nicht um dasselbe Profilverzeichnis konkurrieren.

Verwenden Sie die dokumentierte -env:UserInstallation=...Bootstrap-Variable, um einem Job ein privates Profil zuzuweisen:

docker run --rm   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   --tmpfs /tmp   libreoffice-headless:debian13   -env:UserInstallation=file:///tmp/lo-profile   --convert-to pdf   --outdir /output   /input/sample.docx

Ein privates temporäres Profil ist besonders nützlich für kurzlebige Container und Worker-Pools. Docker dokumentiert tmpfsMounts für temporäre Dateien im Arbeitsspeicher. Wenn Sie hingegen einen langlebigen UNO-Dienst betreiben, sollten Sie eine Strategie für ein persistentes Profil verwenden und den Zugriff entsprechend Ihrem Anwendungsdesign serialisieren oder isolieren.

Schritt 6: Überprüfen Sie, ob die Ausgabedatei tatsächlich existiert.

Nachdem der Container beendet wurde, überprüfen Sie das Ausgabeverzeichnis des Hosts:

ls -lh output/sample.pdf
file output/sample.pdf

Ein Exit-Status von Null und ein nicht leeres PDF sind ein sinnvolles Automatisierungskriterium, aber kein vollständiger Qualitätstest. Für eine Konvertierungs-API sollten Sie zusätzlich ein Timeout festlegen und fehlende oder unerwartet kleine Ausgaben ablehnen. Die optimale Größenschwelle hängt von Ihren Dokumenten ab. Vermeiden Sie daher einen festen, universellen Wert, es sei denn, Sie haben Ihren Dokumentenkorpus analysiert.

Schritt 7: Chargen sorgfältig bearbeiten, anstatt einen Prozess blindlings zu teilen

LibreOffice kann mehrere Eingabedateien verarbeiten --convert-to, und auch eine Shell-Schleife ist einfach. Zum Beispiel:

for f in input/*.docx; do
  docker run --rm     --mount type=bind,src="$(pwd)/input",dst=/input,readonly     --mount type=bind,src="$(pwd)/output",dst=/output     --tmpfs /tmp     libreoffice-headless:debian13     -env:UserInstallation=file:///tmp/lo-profile     --convert-to pdf     --outdir /output     "/input/$(basename "$f")"
done

Bei hohem Durchsatz kann das wiederholte Starten von LibreOffice teuer werden. In diesem Fall kann ein persistenter LibreOffice-Prozess, der über UNO gesteuert wird --accept=..., mithilfe der von LibreOffice dokumentierten Schnittstelle zur Erstellung eines Akzeptors sinnvoll sein. Dies ändert jedoch das Betriebsmodell: Prozessüberwachung, Anforderungsisolierung, Timeouts, Integritätsprüfungen und eine Strategie zum Neustart des Prozesses nach problematischen Dokumenten sind nun erforderlich. Für geringe bis mittlere Datenmengen ist ein einmaliger Container weiterhin einfacher zu handhaben.

Schritt 8: Überprüfen Sie die visuelle Wiedergabetreue, nicht nur den Erfolg der Befehle.

Öffnen Sie Beispiel-PDFs und vergleichen Sie diese mit der erwarteten Ausgabe. Achten Sie besonders auf Seitenumbrüche, verwendete Schriftarten, eingebettete Bilder, Gleichungen, Kopf- und Fußzeilen, Diagramme, Druckbereiche für Tabellenkalkulationen und Textfelder in Präsentationen. Der Headless-Modus macht einen grafischen Desktop überflüssig; er garantiert jedoch nicht, dass alle Office-Funktionen identisch zu Microsoft Office dargestellt werden.

Für automatisierte Regressionstests sollten Sie eine sorgfältig ausgewählte Sammlung repräsentativer Dokumente bereithalten und messbare Eigenschaften wie Seitenzahl, extrahierten Text, Bildabmessungen oder die Ähnlichkeit der gerenderten Seiten vergleichen. Überprüfen Sie alle Schwellenwerte sorgfältig, da harmlose LibreOffice-Updates PDF-Metadaten oder kleine Layoutdetails verändern können.

Wenn eine Konvertierung fehlschlägt: Beheben Sie zuerst die einfachen Ursachen.

1. Der Container wird beendet, aber es erfolgt keine Ausgabe.

Prüfen Sie zunächst den übergebenen Pfad --outdirund vergewissern Sie sich, dass das Zielverzeichnis für UID 10001 beschreibbar ist. Docker-Bind-Mounts ordnen die Dateisystemberechtigungen des Hosts dem Container zu. Gehört Ihr Host-Verzeichnis einer anderen UID und ist es nicht für die Gruppe beschreibbar, kann der LibreOffice-Prozess (außerhalb der Root-Rechte) die Ausgabedatei möglicherweise nicht erstellen.

2. LibreOffice meldet ein Profil- oder Sperrproblem

Verwenden Sie für jeden gleichzeitig laufenden Prozess einen separaten -env:UserInstallation=file:///...Pfad. Weisen Sie nicht mehrere Worker auf dasselbe beschreibbare Profilverzeichnis zu. LibreOffice dokumentiert sowohl die Profilanforderungen als auch die Möglichkeit, UserInstallationdiese zu überschreiben.

3. Die PDF-Datei wurde erstellt, aber das Layout ist fehlerhaft.

Überprüfen Sie die Schriftarten, bevor Sie die Exportoptionen ändern. Verwenden Sie die Funktion fc-listinnerhalb des Bildes, um sicherzustellen, dass die benötigten Schriftarten sichtbar sind. Wenn die Quelldatei Makros, externe Daten, ungewöhnliche eingebettete Objekte oder proprietäre Funktionen verwendet, kann die Headless-Konvertierung die Originalanwendung möglicherweise nicht exakt reproduzieren. Verwenden Sie stattdessen einen korpusbasierten Kompatibilitätstest, anstatt willkürliche Befehlszeilenparameter hinzuzufügen.

4. Tabellenkalkulationen oder Präsentationen werden nicht konvertiert

Stellen Sie sicher, dass die entsprechenden LibreOffice-Komponenten installiert sind. Das libreoffice-noguiDebian-Metapaket enthält Writer, Calc, Impress, Draw, Base und Math ohne grafische Benutzeroberfläche. Wenn Sie absichtlich ein kleineres Image mit nur Writer erstellt haben, fehlt bei der Konvertierung von XLSX- oder PPTX-Dateien möglicherweise die benötigte Komponente.

5. Ein schreibgeschütztes Root-Dateisystem verhindert den Systemstart.

Die Härtung mit Docker --read-onlykann zwar hilfreich sein, LibreOffice benötigt jedoch weiterhin beschreibbare Speicherorte für seine Profil- und temporären Dateien. Stellen Sie daher explizit beschreibbare Verzeichnisse tmpfsoder Volume-Mounts für diese Pfade bereit. Die Dokumentation zum Ausführen von Docker- Containern erklärt, wie schreibgeschützte Root-Dateisysteme mit beschreibbaren Mounts kombiniert werden können.

Ein eher produktionsorientierter Ausführungsbefehl

Nachdem der grundlegende Ablauf funktioniert, kann ein strengerer Aufruf die Eingabe schreibgeschützt halten, temporäre Zustände isolieren und den Container nach jedem Job entfernen:

docker run --rm   --read-only   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   --tmpfs /tmp:rw,nosuid,nodev   --tmpfs /home/office:rw,nosuid,nodev   libreoffice-headless:debian13   -env:UserInstallation=file:///tmp/lo-profile   --convert-to pdf   --outdir /output   /input/sample.docx

Ob diese spezielle Härtungsmaßnahme für jeden Dokumenttyp funktioniert, hängt von Erweiterungen, Java-abhängigen Funktionen, Vorlagen, Wörterbüchern und anderen Laufzeitanforderungen ab. Beschreibbare Pfade sollten nur dann hinzugefügt werden, wenn eine verifizierte Arbeitslast dies erfordert, anstatt den gesamten Container beschreibbar zu machen.

Selbsttest: So erkennen Sie, ob die Einrichtung bereit ist

Bevor Sie den Container als produktionsbereit bezeichnen, überprüfen Sie bitte Folgendes:

• soffice --versionmeldet die LibreOffice-Version, die Sie bereitstellen wollten.
• Eine bekannte DOCX-Datei wird mit sauberem Containerausgang in eine PDF-Datei konvertiert.
• Die PDF-Datei erscheint auf dem Host mit einer Größe ungleich Null und kann analysiert oder geöffnet werden.
• Das Quellverzeichnis wird schreibgeschützt eingebunden und bleibt unverändert.
• Der Prozess wird als normaler Benutzer (kein Root-Benutzer) ausgeführt, es sei denn, es gibt einen dokumentierten Grund, dies nicht zu tun.
• Die repräsentativen Dokumente verwenden die erwarteten Schriftarten und weisen ein akzeptables Seitenlayout auf.
• Zwei gleichzeitig durchgeführte Konvertierungen verwenden separate Benutzerprofile und beeinträchtigen sich nicht gegenseitig.
• Ihre Anwendung behandelt Timeouts, Konvertierungsfehler und fehlende Ausgaben als Fehler, anstatt eine leere oder veraltete Datei zurückzugeben.

Wenn diese Prüfungen erfolgreich sind, eignet sich ein einmaliger, headless LibreOffice-Container hervorragend für Dokumentenkonvertierungsaufgaben, bei denen Isolation und Reproduzierbarkeit wichtig sind. Falls die Startzeit den größten Kostenfaktor darstellt oder Sie Dokumente auf API-Ebene bearbeiten müssen, anstatt Formate zu konvertieren, sollten Sie auf einen überwachten, persistenten LibreOffice/UNO-Dienst umsteigen und diese Architektur separat testen. Docker löst zwar das Problem der Paketierung und Isolation, ersetzt aber nicht die Notwendigkeit, die Dokumentqualität anhand der tatsächlich von Ihrer Anwendung verarbeiteten Dateien zu überprüfen.