Hoe LibreOffice zonder grafische interface in een Docker-container te draaien

Een veelvoorkomend probleem aan de serverzijde lijkt in eerste instantie eenvoudig: een applicatie ontvangt een DOCX-, XLSX-, ODT- of PPTX-bestand en moet een PDF retourneren, maar de host mag geen desktopsessie uitvoeren. Het installeren van een volledig kantoorpakket direct op de host maakt implementaties bovendien lastiger reproduceerbaar. LibreOffice kan zonder grafische interface draaien en Docker kan de conversieruntime isoleren, maar betrouwbare resultaten zijn afhankelijk van meer dan alleen het toevoegen van een parameter --headlessaan een commando.

De praktische oorzaken van de meeste mislukkingen zijn voorspelbaar: de image bevat niet de vereiste LibreOffice-component, de container kan zijn gebruikersprofiel niet schrijven, bind-mounted bestanden hebben de verkeerde machtigingen, lettertypen ontbreken, twee taken delen hetzelfde profiel of de uitvoermap is niet beschrijfbaar. Deze handleiding begint met de eenvoudigste werkende container en maakt deze vervolgens robuuster voor herhaalbare documentconversie.

Vanaf oktober 2026 vermeldt LibreOffice versie 26.8 als de nieuwste feature-branch en 26.2.6 als de volwassen, oudere branch die wordt aanbevolen voor zakelijk gebruik. Stabiele Debian 13-pakketten kunnen een andere, door de distributie onderhouden LibreOffice-versie bevatten. Controleer daarom de basisimage en verifieer de daadwerkelijke versie in uw gebouwde container in plaats van aan te nemen dat deze overeenkomt met de upstream-versie. Zie de officiële release-opmerkingen van LibreOffice en de Debian libreoffice-nogui-pakketpagina .

Wat "headless LibreOffice in Docker" nu eigenlijk betekent

LibreOffice-documenten --headlessworden uitgevoerd in een modus zonder gebruikersinterface. Voor bestandsconversie zijn de belangrijke bijbehorende opties --convert-toen --outdir. LibreOffice vereist ook schrijftoegang tot de gebruikersprofielmap, een detail dat van belang is wanneer u een container uitvoert als een niet-rootgebruiker of het rootbestandssysteem alleen-lezen maakt. De gezaghebbende CLI-referentie is LibreOffice Help: Starting LibreOffice Software With Parameters .

Het doel van een goede container is daarom specifiek: hij moet starten zonder X11 of een desktopomgeving, een invoerdocument lezen, de verwachte uitvoerindeling schrijven, netjes afsluiten en een bestand produceren waarvan de lay-out geschikt is voor uw workload.

Stap 1: Maak een kleine, reproduceerbare Docker-image aan.

Voor een brede ondersteuning van verschillende formaten op Debian 13 libreoffice-noguiis dit een handig startpunt, omdat Debian het beschrijft als een metapakket zonder grafische gebruikersinterface, voornamelijk bedoeld voor scripting. Als u alleen Writer-documenten converteert, kunt u de afhankelijkheden verminderen door libreoffice-writer-noguialleen de andere componenten zonder grafische gebruikersinterface te installeren die u nodig hebt.

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"]

De lettertypepakketten zijn niet alleen voor de sier. Office-documenten verwijzen vaak naar lettertypen die niet standaard in een minimale Linux-image zijn geïnstalleerd. LibreOffice vervangt het gevraagde lettertype door een ander lettertype wanneer dit niet beschikbaar is. Dit kan gevolgen hebben voor de regelterugloop, het aantal pagina's, de tabelbreedte en de dia-indeling. Carlito en Caladea zijn veelgebruikte, metrische alternatieven voor Calibri en Cambria, terwijl Liberation en DejaVu een breed scala aan toepassingen dekken. Als uw documenten gebruikmaken van bedrijfs- of gelicentieerde lettertypen, installeer of koppel deze lettertypen dan alleen als uw licentie dit toestaat.

Stap 2: Maak de image aan en noteer de LibreOffice-versie.

docker build -t libreoffice-headless:debian13 .

Controleer vervolgens welke versie daadwerkelijk in de afbeelding te zien is:

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

Deze controle is belangrijk wanneer een basisimage weken later opnieuw wordt opgebouwd. Als exacte weergave belangrijk is, gebruik dan een onveranderlijke image digest in productie en bouw de image bewust opnieuw op na beveiligings- of LibreOffice-updates. "Latest"-tags zijn handig tijdens experimenten, maar maken het lastiger om verschillen in de uitvoer te onderzoeken.

Stap 3: Maak aparte invoer- en uitvoermappen aan.

Maak twee hostdirectory's aan. De invoerdirectory kan alleen-lezen zijn; de uitvoerdirectory moet beschrijfbaar zijn voor de containergebruiker.

mkdir -p input output
cp sample.docx input/

Docker beveelt de --mountsyntax voor bind mounts aan. In de documentatie staat ook vermeld dat bind mounts standaard beschrijfbaar zijn, dus het expliciet instellen van de bronmap als alleen-lezen is een nuttige beveiliging. Zie de Docker-documentatie over bind mounts .

Stap 4: Converteer één document naar PDF

Start een tijdelijke container en koppel de bronmap als alleen-lezen:

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 ondersteunt dit --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]formaat officieel. Voor een eenvoudige conversie van Writer naar PDF --convert-to pdfselecteert LibreOffice het juiste PDF-exportfilter. Wanneer u specifiek PDF-gedrag nodig hebt, documenteert LibreOffice ook filterparameters; zie de officiële referentie voor PDF CLI-parameters .

Stap 5: Geef elke gelijktijdige taak een eigen LibreOffice-profiel.

Een enkele conversie werkt vaak zonder extra profielconfiguratie, wat een schaalbaarheidsprobleem kan maskeren. LibreOffice bewaart de status in een gebruikersprofiel en vereist schrijftoegang daartoe. Parallelle processen mogen niet concurreren om dezelfde profielmap.

Gebruik de gedocumenteerde -env:UserInstallation=...bootstrap-variabele om een ​​taak een privéprofiel te geven:

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

Een privé tijdelijk profiel is met name handig voor containers en workerpools die maar kort bestaan. Docker documenteert tmpfsmounts voor tijdelijke bestanden in het geheugen. Als u daarentegen een langdurige UNO-service uitvoert, gebruik dan een weloverwogen strategie voor persistente profielen en serialiseer of isoleer de toegang op basis van uw applicatieontwerp.

Stap 6: Controleer of het uitvoerbestand daadwerkelijk bestaat.

Nadat de container is afgesloten, controleer dan de uitvoermap van de host:

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

Een exitstatus van nul plus een niet-lege PDF is een redelijke automatiseringspoort, maar het is geen volledige betrouwbaarheidstest. Stel voor een conversie-API ook een time-out in en weiger uitvoer die ontbreekt of onverwacht klein is. De juiste drempelwaarde voor de grootte hangt af van uw documenten, dus vermijd een universeel, vastgelegd getal tenzij u uw corpus hebt gemeten.

Stap 7: Ga zorgvuldig om met batches in plaats van één proces blindelings te delen.

LibreOffice kan meerdere invoerbestanden accepteren met --convert-to, en een shell-loop is ook eenvoudig. Bijvoorbeeld:

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

Voor een hogere doorvoer kan het herhaaldelijk starten van LibreOffice kostbaar worden. Op dat punt kunt u overwegen een persistent LibreOffice-proces te gebruiken dat wordt aangestuurd via UNO met behulp van --accept=...de interface die LibreOffice beschrijft als de interface voor het creëren van een acceptor. Dit verandert echter het operationele model: u hebt nu procesbewaking, aanvraagisolatie, time-outs, gezondheidscontroles en een strategie nodig om een ​​proces te herstarten na problematische documenten. Een eenmalige container blijft eenvoudiger te beheren voor lage of gemiddelde volumes.

Stap 8: Controleer de visuele kwaliteit, niet alleen of de commando's succesvol zijn.

Open representatieve, gegenereerde PDF's en vergelijk ze met de verwachte uitvoer. Let vooral op pagina-einden, vervangen lettertypen, ingesloten afbeeldingen, vergelijkingen, kop- en voetteksten, grafieken, afdrukgebieden voor spreadsheets en tekstvakken in presentaties. De modus zonder grafische interface (headless mode) heft de vereiste van een grafische desktop op; dit garandeert echter niet dat elke eigen Office-functie identiek wordt weergegeven als in Microsoft Office.

Voor geautomatiseerde regressietests is het belangrijk een zorgvuldig samengestelde set representatieve documenten te bewaren en meetbare eigenschappen te vergelijken, zoals het aantal pagina's, de geëxtraheerde tekst, de afmetingen van afbeeldingen of de gelijkenis tussen de weergegeven pagina's. Controleer de drempelwaarden zorgvuldig, want ogenschijnlijk onschuldige LibreOffice-updates kunnen PDF-metadata of kleine lay-outdetails wijzigen.

Als een conversie mislukt: pak eerst de eenvoudige oorzaken aan.

1. De container wordt afgesloten, maar er verschijnt geen uitvoer.

Controleer eerst het opgegeven pad --outdiren bevestig dat de bestemmingsmount beschrijfbaar is voor UID 10001. Docker bind mounts zetten de bestandsrechten van de host om naar de container. Als uw hostdirectory eigendom is van een andere UID en niet beschrijfbaar is voor de groep, kan het niet-root LibreOffice-proces de uitvoer mogelijk niet genereren.

2. LibreOffice meldt een probleem met het profiel of de vergrendeling.

Gebruik een apart -env:UserInstallation=file:///...pad voor elke gelijktijdige taak. Wijs niet meerdere workers naar dezelfde beschrijfbare profielmap. LibreOffice documenteert zowel de profielvereiste als de mogelijkheid UserInstallationom deze te overschrijven.

3. De PDF is wel aangemaakt, maar de lay-out klopt niet.

Controleer de lettertypen voordat u de exportopties wijzigt. Gebruik fc-listde afbeelding om te bevestigen dat de vereiste lettertypen zichtbaar zijn. Als het bronbestand macro's, externe gegevens, ongebruikelijke ingesloten objecten of eigen functies bevat, is het mogelijk dat conversie zonder grafische interface de originele applicatie niet exact reproduceert. Ga over op een compatibiliteitstest op basis van een corpus in plaats van willekeurige opdrachtregelparameters toe te voegen.

4. Spreadsheets of presentaties worden niet geconverteerd.

Zorg ervoor dat de bijbehorende LibreOffice-componenten zijn geïnstalleerd. Het libreoffice-noguiDebian-metapakket bevat Writer, Calc, Impress, Draw, Base en Math, maar zonder grafische gebruikersinterface (GUI). Als u bewust een kleinere image hebt gemaakt met alleen Writer, kan het zijn dat een XLSX- of PPTX-conversie de benodigde component mist.

5. Een alleen-lezen root-bestandssysteem verstoort de opstartprocedure.

Beveiliging met Docker --read-onlykan nuttig zijn, maar LibreOffice heeft nog steeds beschrijfbare locaties nodig voor profiel- en tijdelijke bestanden. Zorg voor expliciete beschrijfbare tmpfsof volume-mounts voor die paden. De documentatie van Docker over het uitvoeren van containers legt uit hoe alleen-lezen root-bestandssystemen gecombineerd kunnen worden met beschrijfbare mounts.

Een meer op productie gerichte uitvoeringsopdracht

Nadat de basisworkflow werkt, kan een striktere aanroep de invoer alleen-lezen houden, tijdelijke statussen isoleren en de container na elke taak verwijderen:

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

Of deze specifieke beveiliging voor elk documenttype werkt, hangt af van extensies, Java-afhankelijke functies, sjablonen, woordenboeken en andere runtimevereisten. Voeg alleen beschrijfbare paden toe wanneer een geverifieerde workload dit vereist, in plaats van de hele container beschrijfbaar te maken.

Zelfcontrole: hoe weet u of de installatie klaar is?

Voordat u de container productieklaar verklaart, dient u het volgende te controleren:

• soffice --versionrapporteert de LibreOffice-build die u wilde implementeren.
• Een bekend DOCX-bestand wordt geconverteerd naar PDF en de container wordt correct afgesloten.
• Het PDF-bestand verschijnt op de host met een niet-nulgrootte en kan worden geparseerd of geopend.
• De bronmap wordt alleen-lezen gekoppeld en blijft ongewijzigd.
• Het proces wordt uitgevoerd als een niet-rootgebruiker, tenzij u een gedocumenteerde reden hebt om dit niet te doen.
• Representatieve documenten gebruiken de verwachte lettertypen en behouden een acceptabele pagina-indeling.
• Twee gelijktijdige conversies maken gebruik van aparte gebruikersprofielen en beïnvloeden elkaar niet.
• Uw applicatie behandelt time-outs, conversiefouten en ontbrekende uitvoer als mislukkingen in plaats van een leeg of verouderd bestand terug te geven.

Als die controles slagen, is een eenmalige, headless LibreOffice-container een prima oplossing voor documentconversietaken waarbij isolatie en reproduceerbaarheid belangrijk zijn. Als opstartlatentie de belangrijkste kostenpost wordt, of als u documentmanipulatie op API-niveau nodig hebt in plaats van formaatconversie, schakel dan over naar een beheerde, persistente LibreOffice/UNO-service en test die architectuur afzonderlijk. Docker lost het probleem van verpakking en isolatie op; het neemt echter niet de noodzaak weg om de documentintegriteit te valideren aan de hand van de bestanden die uw applicatie daadwerkelijk verwerkt.