Cómo ejecutar LibreOffice sin interfaz gráfica dentro de un contenedor Docker

Un problema común del lado del servidor parece sencillo a primera vista: una aplicación recibe un archivo DOCX, XLSX, ODT o PPTX y necesita devolver un PDF, pero el host no debe ejecutar una sesión de escritorio. Instalar una suite ofimática completa directamente en el host también dificulta la reproducción de las implementaciones. LibreOffice puede ejecutarse sin una interfaz gráfica, y Docker puede aislar el entorno de ejecución de la conversión, pero para obtener resultados fiables se necesita algo más que añadir parámetros --headlessa un comando.

Las causas prácticas de la mayoría de los fallos son predecibles: la imagen no contiene el componente de LibreOffice necesario, el contenedor no puede escribir su perfil de usuario, los archivos montados mediante enlace tienen permisos incorrectos, faltan fuentes, dos trabajos comparten el mismo perfil o el directorio de salida no tiene permisos de escritura. Esta guía comienza con el contenedor funcional más sencillo y, a continuación, lo optimiza para la conversión repetible de documentos.

A partir de octubre de 2026, LibreOffice indica que la versión 26.8 es su rama de características más reciente y la 26.2.6 es la rama anterior madura recomendada para uso empresarial. Los paquetes estables de Debian 13 pueden contener una versión diferente de LibreOffice mantenida por la distribución, así que fije la imagen base y verifique la versión real en su contenedor compilado en lugar de asumir que coincide con la versión original. Consulte las notas de la versión oficial de LibreOffice y la página del paquete Debian libreoffice-nogui .

Qué significa realmente “LibreOffice sin interfaz gráfica en Docker”

LibreOffice se presenta --headlesscomo un modo que se ejecuta sin interfaz de usuario. Para la conversión de archivos, las opciones complementarias importantes son --convert-toy --outdir. LibreOffice también requiere acceso de escritura a su directorio de perfil de usuario, un detalle importante cuando se ejecuta un contenedor como un usuario que no es root o cuando se configura su sistema de archivos raíz como de solo lectura. La referencia autorizada de la CLI es Ayuda de LibreOffice: Iniciar el software LibreOffice con parámetros .

Por lo tanto, el objetivo de un buen contenedor es específico: debe iniciarse sin X11 ni un entorno de escritorio, leer un documento de entrada, escribir el formato de salida esperado, finalizar correctamente y producir un archivo cuyo diseño sea aceptable para su carga de trabajo.

Paso 1: Crea una imagen Docker pequeña y reproducible.

Para una amplia cobertura de formatos en Debian 13, libreoffice-noguies un buen punto de partida porque Debian lo describe como el metapackage sin interfaz gráfica, pensado principalmente para scripts. Si solo convierte documentos de Writer, puede reducir las dependencias instalando libreoffice-writer-noguiúnicamente los demás componentes sin interfaz gráfica que necesite.

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

Los paquetes de fuentes no son meramente estéticos. Los documentos de Office suelen hacer referencia a fuentes que no están instaladas en una imagen mínima de Linux. LibreOffice sustituirá la fuente solicitada por otra si no está disponible, lo que puede afectar al ajuste de línea, el número de páginas, el ancho de las tablas y el diseño de las diapositivas. Carlito y Caladea son alternativas compatibles con el sistema métrico que suelen utilizarse para Calibri y Cambria, mientras que Liberation y DejaVu cubren muchos casos generales. Si sus documentos utilizan fuentes corporativas o con licencia, instálelas o móntelas solo si su licencia lo permite.

Paso 2: Cree la imagen y registre la versión de LibreOffice.

docker build -t libreoffice-headless:debian13 .

Luego, verifique la versión que aparece en la imagen:

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

Esta comprobación es importante cuando se reconstruye una imagen base semanas después. Si la representación exacta es crucial, utilice un resumen de imagen inmutable en producción y reconstruya la imagen deliberadamente después de las actualizaciones de seguridad o de LibreOffice. Las etiquetas "Latest" son útiles durante la experimentación, pero dificultan la investigación de las diferencias en la salida.

Paso 3: Preparar directorios de entrada y salida separados.

Cree dos directorios de host. El directorio de entrada puede ser de solo lectura; el directorio de salida debe ser editable por el usuario del contenedor.

mkdir -p input output
cp sample.docx input/

Docker recomienda la --mountsintaxis para los montajes de enlace. Su documentación también indica que los montajes de enlace son escribibles por defecto, por lo que establecer explícitamente el directorio de origen como de solo lectura es una medida de seguridad útil. Consulte la documentación de Docker sobre montajes de enlace .

Paso 4: Convertir un documento a PDF

Ejecuta un contenedor desechable y monta el directorio de origen en modo de solo lectura:

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 admite oficialmente este --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]formato. Para una conversión sencilla de Writer a PDF, --convert-to pdfdeje que LibreOffice seleccione el filtro de exportación de PDF adecuado. Si necesita un comportamiento específico para el PDF, LibreOffice también documenta los parámetros del filtro; consulte la referencia oficial de parámetros de la interfaz de línea de comandos de PDF .

Paso 5: Asigne a cada tarea simultánea su propio perfil de LibreOffice.

Una sola conversión suele funcionar sin necesidad de configuración adicional del perfil, lo que puede ocultar un problema de escalado. LibreOffice guarda el estado en un perfil de usuario y requiere permisos de escritura. Los procesos paralelos no deben competir por el mismo directorio de perfil.

Utilice la -env:UserInstallation=...variable de arranque documentada para asignar un perfil privado a un trabajo:

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 perfil temporal privado resulta especialmente útil para contenedores y grupos de trabajadores de corta duración. Docker documenta tmpfslos puntos de montaje para archivos temporales en memoria. Si, en cambio, ejecuta un servicio UNO de larga duración, utilice una estrategia de perfil persistente bien definida y serialice o aísle el acceso según el diseño de su aplicación.

Paso 6: Verificar que el archivo de salida realmente existe.

Una vez que el contenedor finalice, inspeccione el directorio de salida del host:

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

Un estado de salida cero y un PDF no vacío constituyen un criterio de automatización razonable, pero no una prueba de fidelidad completa. Para una API de conversión, también conviene establecer un tiempo de espera y rechazar los resultados que falten o sean inesperadamente pequeños. El umbral de tamaño adecuado depende de los documentos, así que evite usar un valor fijo universal a menos que haya medido el tamaño de sus documentos.

Paso 7: Maneje los lotes con cuidado en lugar de compartir un proceso a ciegas.

LibreOffice puede aceptar varios archivos de entrada con --convert-to, y un bucle de shell también es sencillo. Por ejemplo:

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

Para un mayor rendimiento, iniciar LibreOffice repetidamente puede resultar costoso. En ese caso, conviene considerar un proceso persistente de LibreOffice controlado mediante UNO --accept=..., que LibreOffice documenta como la interfaz para crear un receptor. Sin embargo, esto modifica el modelo operativo: ahora se requiere supervisión de procesos, aislamiento de solicitudes, tiempos de espera, comprobaciones de estado y una estrategia para reciclar un proceso tras documentos problemáticos. Un contenedor de un solo uso sigue siendo más sencillo de gestionar para volúmenes bajos o moderados.

Paso 8: Compruebe la fidelidad visual, no solo el éxito del comando.

Abra los archivos PDF generados como ejemplo y compárelos con el resultado esperado. Preste especial atención a los saltos de página, las fuentes sustituidas, las imágenes incrustadas, las ecuaciones, los encabezados y pies de página, los gráficos, las áreas de impresión de las hojas de cálculo y los cuadros de texto de las presentaciones. El modo sin interfaz gráfica elimina la necesidad de un escritorio gráfico; sin embargo, no garantiza que todas las funciones de Office se muestren de forma idéntica a Microsoft Office.

Para realizar pruebas de regresión automatizadas, mantenga un conjunto seleccionado de documentos representativos y compare propiedades medibles como el número de páginas, el texto extraído, las dimensiones de las imágenes o la similitud de las páginas renderizadas. Revise cuidadosamente cualquier umbral, ya que las actualizaciones inofensivas de LibreOffice pueden modificar los metadatos de los PDF o pequeños detalles del diseño.

Cuando una conversión falla: primero solucione las causas simples.

1. El contenedor finaliza pero no aparece ninguna salida.

Primero, verifique la ruta especificada --outdiry confirme que el punto de montaje de destino tenga permisos de escritura para el usuario con UID 10001. Los puntos de montaje de Docker asignan los permisos del sistema de archivos del host al contenedor. Si el directorio del host pertenece a un usuario con UID diferente y no tiene permisos de escritura para el grupo, es posible que el proceso de LibreOffice sin privilegios de administrador no pueda generar el archivo de salida.

2. LibreOffice informa de un problema de perfil o bloqueo.

Utilice una -env:UserInstallation=file:///...ruta distinta para cada tarea simultánea. No dirija varios procesos a un mismo directorio de perfil con permisos de escritura. LibreOffice documenta tanto el requisito del perfil como la UserInstallationforma de anularlo.

3. El PDF se crea, pero el diseño es incorrecto.

Verifique las fuentes antes de cambiar las opciones de exportación. Utilice fc-listla imagen para confirmar que las fuentes requeridas sean visibles. Si el archivo de origen depende de macros, datos externos, objetos incrustados inusuales o funciones propietarias, la conversión sin interfaz gráfica podría no reproducir la aplicación original con exactitud. Opte por una prueba de compatibilidad basada en corpus en lugar de agregar parámetros de línea de comandos aleatorios.

4. Las hojas de cálculo o presentaciones no se convierten

Asegúrese de que los componentes de LibreOffice correspondientes estén instalados. El libreoffice-noguimetapackage de Debian incluye Writer, Calc, Impress, Draw, Base y Math sin interfaz gráfica. Si creó intencionadamente una imagen más pequeña con solo Writer, es posible que la conversión a XLSX o PPTX carezca del componente necesario.

5. Un sistema de archivos raíz de solo lectura provoca un fallo en el inicio.

Reforzar la seguridad con Docker --read-onlypuede ser útil, pero LibreOffice aún necesita ubicaciones con permisos de escritura para sus archivos de perfil y temporales. Proporcione tmpfsmontajes de volumen o de escritura explícitos para esas rutas. La documentación de Docker sobre la ejecución de contenedores explica cómo combinar sistemas de archivos raíz de solo lectura con montajes con permisos de escritura.

Un comando de ejecución más orientado a la producción

Una vez que el flujo básico funciona, una invocación más estricta puede mantener la entrada en modo de solo lectura, aislar el estado temporal y eliminar el contenedor después de cada tarea:

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

Que este endurecimiento funcione para todos los tipos de documentos depende de las extensiones, las funciones dependientes de Java, las plantillas, los diccionarios y otras necesidades de ejecución. Añada rutas de escritura solo cuando una carga de trabajo verificada lo requiera, en lugar de hacer que todo el contenedor sea escribible.

Autocomprobación: cómo saber si la configuración está lista.

Antes de declarar que el contenedor está listo para producción, verifique lo siguiente:

• soffice --versioninforma sobre la compilación de LibreOffice que tenías intención de implementar.
• Un archivo DOCX conocido se convierte a PDF con una salida limpia del contenedor.
• El archivo PDF aparece en el servidor con un tamaño distinto de cero y puede ser analizado o abierto.
• El directorio de origen se monta en modo de solo lectura y permanece sin cambios.
• El proceso se ejecuta como un usuario que no es root, a menos que exista una razón documentada para no hacerlo.
• Los documentos representativos utilizan las fuentes tipográficas habituales y conservan un diseño de página aceptable.
• Dos conversiones simultáneas utilizan perfiles de usuario independientes y no interfieren entre sí.
• Tu aplicación trata los tiempos de espera, los errores de conversión y la falta de resultados como fallos, en lugar de devolver un archivo vacío o desactualizado.

Si superan estas comprobaciones, un contenedor de LibreOffice sin interfaz gráfica de un solo uso resulta ideal para tareas de conversión de documentos que priorizan el aislamiento y la reproducibilidad. Si la latencia de inicio se convierte en el principal problema, o si necesita manipular documentos a nivel de API en lugar de convertir el formato, cambie a un servicio persistente supervisado de LibreOffice/UNO y pruebe esa arquitectura por separado. Docker resuelve el problema del empaquetado y el aislamiento; sin embargo, no elimina la necesidad de validar la fidelidad del documento comparándola con los archivos que procesa realmente su aplicación.