Comment exécuter LibreOffice en mode sans interface graphique dans un conteneur Docker

Un problème courant côté serveur paraît simple au premier abord : une application reçoit un fichier DOCX, XLSX, ODT ou PPTX et doit renvoyer un PDF, mais l’hôte ne doit pas exécuter de session de bureau. L’installation d’une suite bureautique complète directement sur l’hôte complique également la reproduction des déploiements. LibreOffice peut fonctionner sans interface graphique et Docker peut isoler l’environnement d’exécution de la conversion, mais la fiabilité des résultats dépend de bien plus que la simple modification --headlessd’une commande.

Les causes pratiques de la plupart des échecs sont prévisibles : l’image ne contient pas le composant LibreOffice requis, le conteneur ne peut pas écrire son profil utilisateur, les fichiers montés ont des permissions incorrectes, des polices sont manquantes, deux tâches partagent le même profil ou le répertoire de sortie n’est pas accessible en écriture. Ce guide part d’un conteneur fonctionnel simple et le renforce progressivement pour une conversion de documents reproductible.

En octobre 2026, LibreOffice indique que la version 26.8 est sa branche principale la plus récente et la version 26.2.6 la branche précédente, stable et recommandée pour une utilisation en entreprise. Les paquets stables de Debian 13 peuvent contenir une version différente de LibreOffice, maintenue par la distribution. Il est donc conseillé de vérifier la version réelle dans votre conteneur plutôt que de supposer qu'elle corresponde à celle du dépôt principal. Consultez les notes de version officielles de LibreOffice et la page du paquet Debian libreoffice-nogui .

Que signifie concrètement « LibreOffice sans interface graphique dans Docker » ?

LibreOffice --headlesspropose un mode de fonctionnement sans interface utilisateur pour la documentation. Pour la conversion de fichiers, les options importantes sont `--conversion` --convert-toet ` --outdir--conversion`. LibreOffice requiert également un accès en écriture à son répertoire de profil utilisateur, un détail important si vous exécutez un conteneur en tant qu'utilisateur non root ou si vous configurez son système de fichiers racine en lecture seule. La documentation de référence pour l'interface de ligne de commande est : Aide de LibreOffice : Démarrage du logiciel LibreOffice avec des paramètres .

L'objectif d'un bon conteneur est donc précis : il doit démarrer sans X11 ni environnement de bureau, lire un document d'entrée, écrire au format de sortie attendu, se terminer proprement et produire un fichier dont la mise en page est acceptable pour votre charge de travail.

Étape 1 : Créer une petite image Docker reproductible

Pour une prise en charge étendue des formats sous Debian 13, ce métapaquet libreoffice-noguiest un point de départ utile, car Debian le décrit comme un métapaquet sans interface graphique destiné principalement aux scripts. Si vous ne convertissez que des documents Writer, vous pouvez réduire les dépendances en installant libreoffice-writer-noguiuniquement ce métapaquet et les autres composants sans interface graphique dont vous avez besoin.

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

Les paquets de polices ne sont pas purement esthétiques. Les documents bureautiques font souvent référence à des polices qui ne sont pas installées dans une image Linux minimale. LibreOffice utilisera une autre police si celle demandée est indisponible, ce qui peut modifier le retour à la ligne, le nombre de pages, la largeur des tableaux et la mise en page des diapositives. Carlito et Caladea sont des alternatives métriques courantes et compatibles avec Calibri et Cambria, tandis que Liberation et DejaVu couvrent de nombreux cas d'utilisation. Si vos documents utilisent des polices d'entreprise ou sous licence, installez-les uniquement si votre licence le permet.

Étape 2 : Créer l’image et enregistrer la version de LibreOffice

docker build -t libreoffice-headless:debian13 .

Vérifiez ensuite la version qui figure réellement dans l'image :

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

Cette vérification est importante lorsqu'une image de base est reconstruite plusieurs semaines plus tard. Si un rendu précis est essentiel, utilisez un condensé d'image immuable en production et reconstruisez-la systématiquement après les mises à jour de sécurité ou de LibreOffice. Les étiquettes « Dernière version » sont pratiques lors des tests, mais compliquent l'analyse des différences de rendu.

Étape 3 : Préparer des répertoires d’entrée et de sortie distincts

Créez deux répertoires hôtes. Le répertoire d'entrée peut être en lecture seule ; le répertoire de sortie doit être accessible en écriture par l'utilisateur du conteneur.

mkdir -p input output
cp sample.docx input/

Docker recommande la --mountsyntaxe suivante pour les montages de type « bind ». Sa documentation précise également que les montages de type « bind » sont accessibles en écriture par défaut ; il est donc utile de définir explicitement le répertoire source en lecture seule. Consultez la documentation Docker sur les montages de type « bind » .

Étape 4 : Convertir un document en PDF

Lancez un conteneur jetable et montez le répertoire source en lecture seule :

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 prend officiellement en charge ce --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]format. Pour une conversion simple de Writer vers PDF, --convert-to pdflaissez LibreOffice sélectionner le filtre d'exportation PDF approprié. Si vous avez besoin d'un comportement PDF spécifique, LibreOffice documente également les paramètres de filtre ; consultez la référence officielle des paramètres de l'interface de ligne de commande PDF .

Étape 5 : Attribuer à chaque tâche simultanée son propre profil LibreOffice

Une simple conversion fonctionne souvent sans configuration de profil supplémentaire, ce qui peut masquer un problème de mise à l'échelle. LibreOffice conserve l'état dans un profil utilisateur et nécessite un accès en écriture à ce dernier. Les processus parallèles ne doivent pas se disputer le même répertoire de profil.

Utilisez la -env:UserInstallation=...variable d'amorçage documentée pour attribuer un profil privé à une tâche :

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

Un profil temporaire privé est particulièrement utile pour les conteneurs et les pools de workers de courte durée. Docker documente tmpfsles points de montage pour les fichiers temporaires en mémoire. Si vous exécutez un service UNO de longue durée, utilisez une stratégie de profil persistant adaptée et sérialisez ou isolez l'accès en fonction de la conception de votre application.

Étape 6 : Vérifier que le fichier de sortie existe réellement

Une fois le conteneur arrêté, examinez le répertoire de sortie de l'hôte :

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

Un code de sortie nul et un PDF non vide constituent un contrôle d'automatisation acceptable, mais ne représentent pas un test de fidélité complet. Pour une API de conversion, définissez également un délai d'attente et rejetez les fichiers manquants ou anormalement petits. Le seuil de taille approprié dépend de vos documents ; évitez donc d'utiliser une valeur fixe universelle, sauf si vous avez mesuré votre corpus.

Étape 7 : Traitez les lots avec soin au lieu de partager un seul processus aveuglément.

LibreOffice peut accepter plusieurs fichiers d'entrée --convert-to, et une boucle shell est également simple. Par exemple :

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

Pour un débit plus élevé, le redémarrage fréquent de LibreOffice peut s'avérer coûteux. C'est là qu'il est judicieux d'envisager un processus LibreOffice persistant, contrôlé par UNO --accept=...et utilisant l'interface décrite par LibreOffice pour la création d'un accepteur. Cependant, cela modifie le modèle opérationnel : il faut désormais superviser les processus, isoler les requêtes, gérer les délais d'attente, effectuer des contrôles d'intégrité et mettre en place une stratégie de recyclage des processus après la résolution de problèmes. Un conteneur à usage unique reste plus simple à appréhender pour des volumes faibles ou moyens.

Étape 8 : Vérifiez la fidélité visuelle, et pas seulement la réussite de la commande

Ouvrez les PDF générés et comparez-les au résultat attendu. Portez une attention particulière aux sauts de page, aux polices de caractères modifiées, aux images intégrées, aux équations, aux en-têtes et pieds de page, aux graphiques, aux zones d'impression des feuilles de calcul et aux zones de texte des présentations. Le mode sans interface graphique supprime l'exigence d'un bureau graphique ; il ne garantit pas que toutes les fonctionnalités propriétaires d'Office s'afficheront de manière identique à Microsoft Office.

Pour les tests de régression automatisés, conservez un ensemble de documents représentatifs et comparez des propriétés mesurables telles que le nombre de pages, le texte extrait, les dimensions des images ou la similarité des pages rendues. Examinez attentivement tout seuil, car des mises à jour mineures de LibreOffice peuvent modifier les métadonnées des PDF ou de petits détails de mise en page.

En cas d'échec d'une conversion : commencez par corriger les causes les plus simples.

1. Le conteneur s'arrête, mais aucun résultat n'apparaît.

Vérifiez d'abord le chemin d'accès --outdiret assurez-vous que le point de montage de destination est accessible en écriture par l'UID 10001. Les points de montage Docker appliquent les permissions du système de fichiers hôte au conteneur. Si votre répertoire hôte appartient à un autre UID et n'est pas accessible en écriture par le groupe, le processus LibreOffice non root risque de ne pas pouvoir créer le fichier de sortie.

2. LibreOffice signale un problème de profil ou de verrouillage

Utilisez un -env:UserInstallation=file:///...chemin d'accès distinct pour chaque tâche simultanée. Ne configurez pas plusieurs processus pour qu'ils utilisent le même répertoire de profil accessible en écriture. LibreOffice documente à la fois les exigences relatives aux profils et la possibilité UserInstallationde les contourner.

3. Le PDF est créé, mais la mise en page est incorrecte.

Vérifiez les polices avant de modifier les options d'exportation. Utilisez l'outil de vérification fc-listà l'intérieur de l'image pour confirmer que les polices requises sont visibles. Si le fichier source utilise des macros, des données externes, des objets incorporés inhabituels ou des fonctionnalités propriétaires, la conversion sans interface graphique risque de ne pas reproduire exactement l'application d'origine. Privilégiez un test de compatibilité basé sur un corpus plutôt que d'ajouter des options de ligne de commande au hasard.

4. Les feuilles de calcul ou les présentations ne se convertissent pas

Assurez-vous que les composants LibreOffice correspondants sont installés. Le libreoffice-noguimétapaquet Debian inclut Writer, Calc, Impress, Draw, Base et Math, mais sans interface graphique. Si vous avez volontairement créé une image plus légère ne contenant que Writer, la conversion au format XLSX ou PPTX risque de ne pas inclure le composant nécessaire.

5. Un système de fichiers racine en lecture seule empêche le démarrage.

Le renforcement de la sécurité avec Docker --read-onlypeut s'avérer utile, mais LibreOffice nécessite toujours des emplacements accessibles en écriture pour son profil et ses fichiers temporaires. Spécifiez des tmpfspoints de montage de volume ou des accès en écriture pour ces chemins. La documentation de Docker sur l'exécution de conteneurs explique comment combiner des systèmes de fichiers racine en lecture seule avec des points de montage accessibles en écriture.

Une commande d'exécution plus orientée vers la production

Une fois le flux de base opérationnel, une invocation plus stricte permet de maintenir l'entrée en lecture seule, d'isoler l'état temporaire et de supprimer le conteneur après chaque tâche :

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

L'efficacité de cette mesure de sécurité pour tous les types de documents dépend des extensions, des fonctionnalités Java, des modèles, des dictionnaires et autres exigences d'exécution. Il est recommandé d'autoriser l'écriture uniquement lorsque la charge de travail le requiert, plutôt que de rendre l'intégralité du conteneur accessible en écriture.

Auto-vérification : comment savoir si la configuration est prête

Avant de déclarer le conteneur prêt pour la production, vérifiez les points suivants :

• soffice --versionsignale la version de LibreOffice que vous aviez l'intention de déployer.
• Un fichier DOCX connu se convertit en PDF avec une sortie de conteneur propre.
• Le fichier PDF apparaît sur le serveur avec une taille non nulle et peut être analysé ou ouvert.
• Le répertoire source est monté en lecture seule et reste inchangé.
• Le processus s'exécute en tant qu'utilisateur non root, sauf si vous avez une raison documentée de ne pas le faire.
• Les documents de référence utilisent les polices attendues et respectent une mise en page acceptable.
• Deux conversions simultanées utilisent des profils utilisateur distincts et n'interfèrent pas l'une avec l'autre.
• Votre application traite les délais d'attente, les erreurs de conversion et les sorties manquantes comme des échecs plutôt que de renvoyer un fichier vide ou obsolète.

Si ces vérifications sont concluantes, un conteneur LibreOffice sans interface graphique, exécuté une seule fois, est parfaitement adapté aux tâches de conversion de documents qui privilégient l'isolation et la reproductibilité. Si la latence au démarrage devient le principal facteur de coût, ou si vous avez besoin de manipuler les documents au niveau de l'API plutôt que de les convertir en format, optez pour un service LibreOffice/UNO persistant supervisé et testez cette architecture séparément. Docker résout les problèmes d'empaquetage et d'isolation ; il ne dispense cependant pas de vérifier la conformité des documents avec les fichiers réellement traités par votre application.