Como executar o LibreOffice em modo headless dentro de um contêiner Docker

Um problema comum no lado do servidor parece simples à primeira vista: um aplicativo recebe um arquivo DOCX, XLSX, ODT ou PPTX e precisa retornar um PDF, mas o host não deve executar uma sessão de desktop. Instalar um pacote Office completo diretamente no host também dificulta a reprodução das implantações. O LibreOffice pode ser executado sem uma interface gráfica e o Docker pode isolar o ambiente de conversão, mas resultados confiáveis ​​dependem de mais do que simplesmente adicionar --headlessum comando.

As causas práticas da maioria das falhas são previsíveis: a imagem não contém o componente LibreOffice necessário, o contêiner não consegue gravar seu perfil de usuário, os arquivos montados via bind têm permissões incorretas, faltam fontes, duas tarefas compartilham o mesmo perfil ou o diretório de saída não é gravável. Este guia começa com o contêiner funcional mais simples e, em seguida, o reforça para conversão repetível de documentos.

Em outubro de 2026, o LibreOffice listava a versão 26.8 como a versão mais recente com novos recursos e a versão 26.2.6 como a versão anterior, mais estável e recomendada para uso corporativo. Os pacotes estáveis ​​do Debian 13 podem conter uma versão diferente do LibreOffice, mantida pela distribuição. Portanto, fixe a imagem base e verifique a versão real no seu contêiner compilado, em vez de presumir que ela corresponde à versão original. Consulte as notas de lançamento oficiais do LibreOffice e a página do pacote libreoffice-nogui no Debian .

O que significa, na prática, “LibreOffice sem interface gráfica em Docker”?

O LibreOffice possui --headlessum modo de execução que não utiliza interface gráfica. Para conversão de arquivos, as opções complementares importantes são ` --convert` --convert-toe ` --outdir--write`. O LibreOffice também requer permissão de escrita no diretório do perfil do usuário, um detalhe importante quando você executa um contêiner como um usuário não root ou torna o sistema de arquivos raiz somente leitura. A referência oficial para a linha de comando é a Ajuda do LibreOffice: Iniciando o Software LibreOffice com Parâmetros .

O objetivo de um bom contêiner é, portanto, específico: ele deve iniciar sem X11 ou área de trabalho, ler um documento de entrada, gravar a saída no formato esperado, encerrar corretamente e produzir um arquivo cujo layout seja aceitável para sua carga de trabalho.

Passo 1: Crie uma imagem Docker pequena e reproduzível.

Para ampla cobertura de formatos no Debian 13, libreoffice-noguio `wp` é um ponto de partida útil, pois o Debian o descreve como o metapacote sem interface gráfica destinado principalmente à criação de scripts. Se você converter apenas documentos do Writer, poderá reduzir as dependências instalando o `wp` libreoffice-writer-noguie somente os outros componentes sem interface gráfica de que precisa.

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

Os pacotes de fontes não são meramente cosméticos. Documentos do Office frequentemente fazem referência a fontes que não estão instaladas em uma imagem Linux mínima. O LibreOffice substituirá a fonte solicitada por outra quando esta não estiver disponível, o que pode alterar a quebra de linha, a contagem de páginas, a largura da tabela e o layout do slide. Carlito e Caladea são substitutos métricos compatíveis e úteis para Calibri e Cambria, enquanto Liberation e DejaVu abrangem muitos casos gerais. Se seus documentos usam fontes corporativas ou licenciadas, instale ou monte essas fontes somente quando sua licença permitir.

Etapa 2: Crie a imagem e registre a versão do LibreOffice.

docker build -t libreoffice-headless:debian13 .

Em seguida, verifique a versão que está efetivamente na imagem:

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

Essa verificação é importante quando uma imagem base é reconstruída semanas depois. Se a renderização exata for importante, use um resumo de imagem imutável em produção e reconstrua-a deliberadamente após atualizações de segurança ou do LibreOffice. As tags "Mais recente" são convenientes durante a experimentação, mas dificultam a investigação das diferenças de saída.

Etapa 3: Prepare diretórios de entrada e saída separados.

Crie dois diretórios no host. O diretório de entrada pode ser somente leitura; o diretório de saída deve ser gravável pelo usuário do contêiner.

mkdir -p input output
cp sample.docx input/

O Docker recomenda a --mountsintaxe para montagens de diretórios (bind mounts). Sua documentação também observa que as montagens de diretórios são graváveis ​​por padrão, portanto, definir explicitamente o diretório de origem como somente leitura é uma medida de segurança útil. Consulte a documentação de montagens de diretórios do Docker .

Passo 4: Converter um documento para PDF

Execute um contêiner descartável e monte o diretório de origem como somente leitura:

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

O LibreOffice oferece suporte oficial ao --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]formato. Para uma conversão simples de Writer para PDF, --convert-to pdfdeixe o LibreOffice selecionar o filtro de exportação de PDF apropriado. Quando você precisar de um comportamento específico do PDF, o LibreOffice também documenta os parâmetros de filtro; consulte a referência oficial de parâmetros da CLI de PDF .

Etapa 5: Atribua um perfil do LibreOffice a cada tarefa simultânea.

Uma única conversão geralmente funciona sem configuração adicional de perfil, o que pode mascarar um problema de escalabilidade. O LibreOffice mantém o estado em um perfil de usuário e requer permissão de gravação para acessá-lo. Processos paralelos não devem competir pelo mesmo diretório de perfil.

Utilize a -env:UserInstallation=...variável de inicialização documentada para atribuir um perfil privado a uma tarefa:

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

Um perfil temporário privado é particularmente útil para contêineres e pools de workers de curta duração. O Docker documenta tmpfsmontagens para arquivos temporários em memória. Se, em vez disso, você executar um serviço UNO de longa duração, use uma estratégia deliberada de perfil persistente e serialize ou isole o acesso de acordo com o design do seu aplicativo.

Etapa 6: Verifique se o arquivo de saída realmente existe.

Após o contêiner ser encerrado, inspecione o diretório de saída do host:

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

Um código de saída zero, além de um PDF não vazio, é um critério razoável para automação, mas não constitui um teste de fidelidade completo. Para uma API de conversão, defina também um tempo limite e rejeite arquivos de saída ausentes ou inesperadamente pequenos. O limite de tamanho ideal depende dos seus documentos, portanto, evite um valor fixo universal, a menos que você tenha medido seu conjunto de dados.

Etapa 7: Manuseie os lotes com cuidado em vez de compartilhar um único processo cegamente.

O LibreOffice aceita vários arquivos de entrada com --convert-to, e um loop de shell também é simples. Por exemplo:

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 volumes de dados mais altos, iniciar o LibreOffice repetidamente pode se tornar dispendioso. É nesse ponto que você pode considerar um processo persistente do LibreOffice controlado por meio do UNO usando o `acceptor` --accept=..., que o LibreOffice documenta como a interface para criar um `acceptor`. No entanto, isso altera o modelo operacional: agora você precisa de supervisão de processos, isolamento de requisições, timeouts, verificações de integridade e uma estratégia para reciclar um processo após documentos problemáticos. Um contêiner de uso único continua sendo mais fácil de usar para volumes baixos ou moderados.

Etapa 8: Verifique a fidelidade visual, não apenas o sucesso do comando.

Abra os PDFs gerados e compare-os com o resultado esperado. Preste atenção especial às quebras de página, fontes substituídas, imagens incorporadas, equações, cabeçalhos e rodapés, gráficos, áreas de impressão de planilhas e caixas de texto de apresentações. O modo sem interface gráfica elimina a necessidade de um ambiente gráfico; no entanto, isso não garante que todos os recursos proprietários do Office serão renderizados de forma idêntica ao Microsoft Office.

Para testes de regressão automatizados, mantenha um conjunto selecionado de documentos representativos e compare propriedades mensuráveis, como número de páginas, texto extraído, dimensões da imagem ou similaridade da página renderizada. Analise cuidadosamente qualquer limite, pois atualizações benignas do LibreOffice podem alterar metadados de PDF ou pequenos detalhes de layout.

Quando uma conversão falhar: corrija primeiro as causas mais simples.

1. O contêiner é encerrado, mas nenhuma saída é exibida.

Primeiro, verifique o caminho passado --outdire confirme se o ponto de montagem de destino tem permissão de escrita para o UID 10001. Os bind mounts do Docker mapeiam as permissões do sistema de arquivos do host para o contêiner. Se o diretório do seu host pertencer a um UID diferente e não tiver permissão de escrita para o grupo, o processo do LibreOffice (sem privilégios de root) pode não conseguir criar a saída.

2. O LibreOffice reporta um problema de perfil ou bloqueio.

Utilize um -env:UserInstallation=file:///...caminho distinto para cada tarefa simultânea. Não direcione vários processos para um mesmo diretório de perfil gravável. O LibreOffice documenta tanto os requisitos de perfil quanto as opções UserInstallationpara sobrescrevê-los.

3. O PDF foi criado, mas o layout está incorreto.

Verifique as fontes antes de alterar as opções de exportação. Use fc-lista ferramenta de visualização dentro da imagem para confirmar se as fontes necessárias estão visíveis. Se o arquivo de origem depender de macros, dados externos, objetos incorporados incomuns ou recursos proprietários, a conversão sem interface gráfica pode não reproduzir o aplicativo original com exatidão. Opte por um teste de compatibilidade baseado em corpus em vez de adicionar parâmetros aleatórios à linha de comando.

4. Planilhas ou apresentações não são convertidas

Certifique-se de que os componentes correspondentes do LibreOffice estejam instalados. O libreoffice-noguimetapacote Debian inclui Writer, Calc, Impress, Draw, Base e Math, sem suporte a interface gráfica. Se você criou intencionalmente uma imagem menor contendo apenas o Writer, a conversão para XLSX ou PPTX pode não incluir o componente necessário.

5. Um sistema de arquivos raiz somente leitura impede a inicialização.

O reforço da segurança com o Docker --read-onlypode ser útil, mas o LibreOffice ainda precisa de locais graváveis ​​para seus arquivos de perfil e temporários. Forneça montagens de volume ou de gravação explícitas para esses caminhos. A documentação de execução de contêinerestmpfs do Docker explica como sistemas de arquivos raiz somente leitura podem ser combinados com montagens graváveis.

Um comando de execução mais voltado para a produção

Após o funcionamento do fluxo básico, uma invocação mais restritiva pode manter a entrada somente leitura, isolar o estado temporário e remover o contêiner após cada tarefa:

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

A eficácia dessa medida de segurança para todos os tipos de documento depende de extensões, recursos específicos do Java, modelos, dicionários e outras necessidades de tempo de execução. Adicione caminhos graváveis ​​somente quando uma carga de trabalho comprovada os exigir, em vez de tornar todo o contêiner gravável.

Autoverificação: como saber se a configuração está pronta

Antes de considerar o contêiner pronto para produção, verifique todos os seguintes itens:

• soffice --versionRelata a versão do LibreOffice que você pretendia implantar.
• Um arquivo DOCX conhecido é convertido para PDF com uma saída de contêiner limpa.
• O PDF aparece no servidor com tamanho diferente de zero e pode ser analisado ou aberto.
• O diretório de origem é montado em modo somente leitura e permanece inalterado.
• O processo é executado como um usuário sem privilégios de root, a menos que você tenha um motivo documentado para não fazê-lo.
• Os documentos representativos utilizam as fontes esperadas e mantêm um layout de página aceitável.
• Duas conversões simultâneas utilizam perfis de usuário separados e não interferem uma na outra.
• Seu aplicativo trata timeouts, erros de conversão e ausência de saída como falhas, em vez de retornar um arquivo vazio ou obsoleto.

Se essas verificações forem aprovadas, um contêiner LibreOffice headless de execução única é uma ótima opção para tarefas de conversão de documentos que priorizam isolamento e reprodutibilidade. Se a latência de inicialização se tornar o custo dominante, ou se você precisar de manipulação de documentos em nível de API em vez de conversão de formato, mude para um serviço LibreOffice/UNO persistente e supervisionado e teste essa arquitetura separadamente. O Docker resolve o empacotamento e o isolamento; ele não elimina a necessidade de validar a fidelidade do documento em relação aos arquivos que seu aplicativo realmente processa.