Come eseguire LibreOffice in modalità headless all'interno di un container Docker

Un problema comune lato server può sembrare semplice a prima vista: un'applicazione riceve un file DOCX, XLSX, ODT o PPTX e deve restituirne un PDF, ma l'host non deve eseguire una sessione desktop. Installare una suite Office completa direttamente sull'host rende inoltre più difficile riprodurre le implementazioni. LibreOffice può funzionare senza interfaccia grafica e Docker può isolare l'esecuzione della conversione, ma per ottenere risultati affidabili è necessario qualcosa di più che aggiungere un --headlessparametro a un comando.

Le cause pratiche della maggior parte degli errori sono prevedibili: l'immagine non contiene il componente LibreOffice necessario, il contenitore non può scrivere il proprio profilo utente, i file montati tramite bind mount hanno autorizzazioni errate, mancano i font, due processi condividono lo stesso profilo oppure la directory di output non è scrivibile. Questa guida parte dal contenitore funzionante più semplice e lo configura in modo più robusto per garantire conversioni di documenti ripetibili.

A ottobre 2026, LibreOffice indicava la versione 26.8 come l'ultima versione con nuove funzionalità e la 26.2.6 come la versione precedente più matura e consigliata per l'uso aziendale. I pacchetti stabili di Debian 13 potrebbero includere una versione di LibreOffice diversa, gestita dalla distribuzione stessa; pertanto, è consigliabile bloccare l'immagine di base e verificare la versione effettiva nel container creato, anziché dare per scontato che corrisponda a quella upstream. Consultare le note di rilascio ufficiali di LibreOffice e la pagina del pacchetto libreoffice-nogui di Debian .

Cosa significa realmente "LibreOffice senza interfaccia grafica in Docker"?

LibreOffice documenta --headlesscome una modalità che viene eseguita senza interfaccia utente. Per la conversione dei file, le opzioni complementari importanti sono --convert-toe --outdir. LibreOffice richiede anche l'accesso in scrittura alla directory del profilo utente, un dettaglio importante quando si esegue un container come utente non root o si rende il filesystem root di sola lettura. Il riferimento autorevole per la CLI è LibreOffice Help: Starting LibreOffice Software With Parameters .

L'obiettivo di un buon contenitore è quindi specifico: deve avviarsi senza X11 o un ambiente desktop, leggere un documento di input, scrivere nel formato di output previsto, terminare correttamente e produrre un file il cui layout sia accettabile per il carico di lavoro.

Passaggio 1: Creare un'immagine Docker piccola e riproducibile

Per una copertura ampia dei formati su Debian 13, libreoffice-noguiè un utile punto di partenza perché Debian lo descrive come il metapackage senza interfaccia grafica destinato principalmente allo scripting. Se converti solo documenti Writer, puoi ridurre le dipendenze installando libreoffice-writer-noguie solo gli altri componenti senza interfaccia grafica di cui hai bisogno.

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

I pacchetti di font non sono solo un elemento estetico. I documenti di Office spesso fanno riferimento a font non installati in un'immagine Linux minimale. LibreOffice sostituirà il font richiesto con un altro quando questo non è disponibile, il che può modificare l'a capo automatico, il numero di pagine, la larghezza delle tabelle e il layout delle diapositive. Carlito e Caladea sono alternative comunemente utilizzate e compatibili con il sistema metrico per Calibri e Cambria, mentre Liberation e DejaVu coprono molti casi generici. Se i vostri documenti utilizzano font aziendali o con licenza, installateli o montateli solo se la vostra licenza lo consente.

Passaggio 2: crea l'immagine e registra la versione di LibreOffice

docker build -t libreoffice-headless:debian13 .

Quindi controlla la versione effettivamente presente nell'immagine:

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

Questo controllo è importante quando un'immagine di base viene ricostruita settimane dopo. Se la resa esatta è fondamentale, in produzione è consigliabile utilizzare un digest dell'immagine immutabile e ricostruirla deliberatamente dopo gli aggiornamenti di sicurezza o di LibreOffice. I tag "Ultimo" sono utili durante la fase di sperimentazione, ma rendono più difficile analizzare le differenze di output.

Passaggio 3: Preparare directory di input e output separate

Creare due directory host. La directory di input può essere di sola lettura; la directory di output deve essere scrivibile dall'utente del container.

mkdir -p input output
cp sample.docx input/

Docker raccomanda la --mountsintassi per i bind mount. La sua documentazione precisa inoltre che i bind mount sono scrivibili per impostazione predefinita, quindi impostare esplicitamente la directory di origine in sola lettura è una precauzione utile. Consultare la documentazione di Docker sui bind mount .

Passaggio 4: Convertire un documento in PDF

Avvia un container temporaneo e monta la directory di origine in sola lettura:

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 supporta ufficialmente questo --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]formato. Per una semplice conversione da Writer a PDF, --convert-to pdfconsente a LibreOffice di selezionare il filtro di esportazione PDF appropriato. Quando è necessario un comportamento PDF specifico, LibreOffice documenta anche i parametri del filtro; consultare la documentazione ufficiale dei parametri della CLI per PDF .

Passaggio 5: Assegna a ciascun processo simultaneo un profilo LibreOffice separato

Una singola conversione spesso funziona senza configurazioni aggiuntive del profilo, il che può nascondere un problema di scalabilità. LibreOffice mantiene lo stato nel profilo utente e richiede l'accesso in scrittura ad esso. I processi paralleli non dovrebbero competere per la stessa directory del profilo.

Utilizza la -env:UserInstallation=...variabile bootstrap documentata per assegnare un profilo privato a un lavoro:

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 profilo temporaneo privato è particolarmente utile per container e pool di worker di breve durata. Docker documenta tmpfsi mount per i file temporanei in memoria. Se invece si esegue un servizio UNO di lunga durata, è consigliabile utilizzare una strategia di profili persistenti e serializzare o isolare l'accesso in base alla progettazione dell'applicazione.

Passaggio 6: Verificare che il file di output esista effettivamente

Dopo l'arresto del container, ispezionare la directory di output dell'host:

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

Un codice di uscita pari a zero e un PDF non vuoto rappresentano un criterio di automazione ragionevole, ma non costituiscono un test di fedeltà completo. Per un'API di conversione, è consigliabile impostare anche un timeout e rifiutare l'output mancante o di dimensioni inaspettatamente ridotte. La soglia di dimensione corretta dipende dai documenti, quindi è meglio evitare un valore fisso universale a meno che non si siano misurate le dimensioni del corpus.

Passaggio 7: Gestisci i lotti con attenzione invece di condividere un unico processo alla cieca

LibreOffice può accettare più file di input con --convert-to, e anche un ciclo di shell è semplice. Ad esempio:

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

Per ottenere una maggiore produttività, l'avvio ripetuto di LibreOffice può diventare oneroso. A questo punto, si potrebbe considerare un processo LibreOffice persistente controllato tramite UNO --accept=..., che LibreOffice documenta come interfaccia per la creazione di un accettore. Tuttavia, ciò modifica il modello operativo: ora sono necessari la supervisione del processo, l'isolamento delle richieste, i timeout, i controlli di integrità e una strategia per il riavvio del processo dopo la gestione di documenti problematici. Un container monouso rimane più semplice da gestire per volumi bassi o moderati.

Passaggio 8: Verificare la fedeltà visiva, non solo il successo del comando.

Apri i PDF generati dai programmi di esempio e confrontali con l'output previsto. Presta particolare attenzione alle interruzioni di pagina, ai font sostituiti, alle immagini incorporate, alle equazioni, alle intestazioni e ai piè di pagina, ai grafici, alle aree di stampa dei fogli di calcolo e alle caselle di testo delle presentazioni. La modalità headless elimina la necessità di un'interfaccia grafica, ma non garantisce che tutte le funzionalità proprietarie di Office vengano visualizzate in modo identico a Microsoft Office.

Per i test di regressione automatizzati, mantieni un set selezionato di documenti rappresentativi e confronta proprietà misurabili come il numero di pagine, il testo estratto, le dimensioni delle immagini o la somiglianza delle pagine renderizzate. Esamina attentamente qualsiasi soglia, poiché gli aggiornamenti di LibreOffice, anche quelli apparentemente innocui, possono modificare i metadati dei PDF o piccoli dettagli di impaginazione.

Quando una conversione fallisce: risolvi prima le cause più semplici.

1. Il contenitore termina ma non viene visualizzato alcun output.

Innanzitutto, verifica il percorso passato --outdire conferma che il mount di destinazione sia scrivibile dall'UID 10001. I bind mount di Docker mappano i permessi del filesystem host nel container. Se la directory host è di proprietà di un UID diverso e non è scrivibile dal gruppo, il processo LibreOffice non root potrebbe non essere in grado di creare l'output.

2. LibreOffice segnala un problema con il profilo o con il blocco

Utilizzare un -env:UserInstallation=file:///...percorso distinto per ogni processo simultaneo. Non indirizzare più processi worker alla stessa directory del profilo scrivibile. LibreOffice documenta sia il requisito del profilo che la possibilità UserInstallationdi derogarvi.

3. Il PDF viene creato, ma il layout è errato.

Prima di modificare le opzioni di esportazione, verifica i font. Utilizza fc-listl'immagine per confermare che i font richiesti siano visibili. Se il file sorgente si basa su macro, dati esterni, oggetti incorporati insoliti o funzionalità proprietarie, la conversione headless potrebbe non riprodurre esattamente l'applicazione originale. Passa a un test di compatibilità basato su corpus anziché aggiungere opzioni casuali da riga di comando.

4. I fogli di calcolo o le presentazioni non si convertono

Assicurati che i componenti LibreOffice corrispondenti siano installati. Il libreoffice-noguimetapackage Debian include Writer, Calc, Impress, Draw, Base e Math senza supporto GUI. Se hai creato intenzionalmente un'immagine più piccola con solo Writer, la conversione in XLSX o PPTX potrebbe non includere il componente necessario.

5. Un filesystem root di sola lettura impedisce l'avvio

La protezione offerta da Docker --read-onlypuò essere utile, ma LibreOffice necessita comunque di percorsi scrivibili per i file del profilo e i file temporanei. È necessario fornire esplicitamente tmpfsmount di volumi o directory scrivibili per tali percorsi. La documentazione di Docker sull'esecuzione dei container spiega come combinare filesystem root di sola lettura con mount scrivibili.

Un comando di esecuzione più orientato alla produzione

Una volta che il flusso di base funziona, un'invocazione più rigorosa può mantenere l'input di sola lettura, isolare lo stato temporaneo e rimuovere il contenitore dopo ogni operazione:

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'efficacia di questa specifica misura di sicurezza per ogni tipo di documento dipende dalle estensioni, dalle funzionalità dipendenti da Java, dai modelli, dai dizionari e da altre esigenze di runtime. È consigliabile aggiungere percorsi scrivibili solo quando un carico di lavoro verificato lo richiede, anziché rendere scrivibile l'intero contenitore.

Autoverifica: come sapere se la configurazione è pronta

Prima di dichiarare il container pronto per la produzione, verificare tutti i seguenti punti:

• soffice --versionsegnala la build di LibreOffice che si intendeva distribuire.
• Un file DOCX noto viene convertito in PDF con un'uscita pulita dal contenitore.
• Il file PDF appare sul computer host con dimensioni diverse da zero e può essere analizzato o aperto.
• La directory di origine viene montata in sola lettura e rimane invariata.
• Il processo viene eseguito come utente non root, a meno che non si disponga di un motivo documentato per non farlo.
• I documenti rappresentativi utilizzano i caratteri tipografici previsti e mantengono un layout di pagina accettabile.
• Le due conversioni simultanee utilizzano profili utente separati e non interferiscono tra loro.
• La tua applicazione considera i timeout, gli errori di conversione e l'output mancante come errori, anziché restituire un file vuoto o obsoleto.

Se questi controlli hanno esito positivo, un container LibreOffice headless monouso è una soluzione ideale per le conversioni di documenti che privilegiano l'isolamento e la riproducibilità. Se la latenza all'avvio diventa il fattore determinante, o se è necessaria la manipolazione di documenti a livello di API anziché la conversione di formato, è consigliabile passare a un servizio LibreOffice/UNO persistente e supervisionato e testare tale architettura separatamente. Docker risolve i problemi di packaging e isolamento, ma non elimina la necessità di verificare l'integrità dei documenti rispetto ai file effettivamente elaborati dall'applicazione.