Como fazer self-hosting do Gotenberg em 2026: HTML para PDF, timeouts e fontes

Um deploy do Gotenberg com falha nem sempre trava. Ele pode servir uma página de login enquanto as requests usam o campo multipart incorreto ou as conversões excedem os timeouts do proxy. Em vez disso, comece com uma verificação end-to-end: envie HTML e assets como dados multipart, gere um PDF, repita com um documento do Office e inspecione o health endpoint após cada conversão.

Essa verificação corresponde à finalidade catalogada do Gotenberg: um serviço HTTP que converte arquivos HTML, Markdown e Office em PDF. Ela também expõe dependências ausentes, suposições incorretas sobre o proxy e dados efêmeros mais cedo do que um uptime probe.

Portas, processos e serviços privados

Não deixe que a imagem do Gotenberg escolha acidentalmente a arquitetura de produção. A imagem fornece um processo na porta 3000; armazenamento, routing e requisitos externos ainda precisam de lifecycles definidos de forma deliberada. O requisito do runtime local é ter CPU e memória disponíveis para os workers do Chromium e do LibreOffice. Teste esse limite antes da publicação e novamente após a substituição de um container.

O deploy está pronto para testes mais profundos quando consegue enviar HTML e assets como dados multipart, gerar um PDF, repetir com um documento do Office e inspecionar o health endpoint após cada conversão. Acompanhe a transação nos logs e monitore a contagem de processos do Chromium e do LibreOffice, o disco temporário, a complexidade dos documentos e os timeouts do proxy. Essas observações mostram se a topologia atual isola o componente correto.

Torne a recuperação do Gotenberg mensurável

Não se espera nenhum estado gravável da aplicação dentro da imagem padrão do Gotenberg. Não preserve dados duráveis da aplicação; mantenha fontes, templates e a configuração do deploy, incluindo o digest fixado e a configuração de routes revisada, em vez de fazer backup de um filesystem vazio do container.

Crie o Gotenberg do zero em outro host e verifique se as fontes personalizadas, os templates e as command flags são reproduzíveis e se documentos conhecidos são renderizados com o número de páginas esperado. Se um banco de dados separado, room server ou camada de autenticação for adicionado, atribua a esse componente um responsável explícito pela recuperação. O guia de Git para produção mostra como um artefato reproduzível substitui um backup de container.

Registre o comando de rebuild e o teste de output conhecido junto à release. Um plano de recuperação stateless funciona ao reproduzir o comportamento a partir de inputs confiáveis; ele não deve depender da cópia de um container em execução e opaco.

Reduza a autoridade mantida pelo Gotenberg

O ativo valioso no Gotenberg é o code path que processa os inputs dos usuários. O risco específico da aplicação está em permitir conversões públicas irrestritas sem controles de tamanho e timeout; em produção, mantenha os endpoints de conversão privados ou imponha controles de tamanho, rate e timeout antes de permitir arquivos não confiáveis.

O container padrão não possui um secret de administrador, portanto a autenticação deve ficar na route HTTPS se o serviço for privado. Fixe o build, evite mounts amplos do filesystem e limite a contagem de processos do Chromium e do LibreOffice, o disco temporário, a complexidade dos documentos e os timeouts do proxy. Use um input de teste conhecido para confirmar que o build servido produz o output esperado após cada update.

O release gate do Gotenberg

Transforme o smoke test do Gotenberg em um comando de release repetível ou em um runbook curto. O output deve demonstrar este resultado: enviar HTML e assets como dados multipart, gerar um PDF, repetir com um documento do Office e inspecionar o health endpoint após cada conversão. Registre a versão da aplicação, o digest do container, o hostname da route e o identificador dos dados de teste junto ao resultado.

Execute a mesma verificação após uma troca rotineira de container e depois de restaurar nenhum dado durável da aplicação; mantenha fontes, templates e a configuração do deploy em outro local. O restore foi bem-sucedido quando as fontes personalizadas, os templates e as command flags são reproduzíveis e os documentos conhecidos são renderizados com o número de páginas esperado. Compare o tempo e o consumo relacionados à contagem de processos do Chromium e do LibreOffice, ao disco temporário, à complexidade dos documentos e aos timeouts do proxy; uma mudança significativa merece investigação mesmo quando a ação final continua passando.

Depois, exercite uma falha segura: envie um input inofensivo próximo ao limite de recurso ou formato associado a este boundary: as requests usam o campo multipart incorreto ou as conversões excedem os timeouts do proxy. Confirme que o Gotenberg expõe a falha e retorna ao normal sem edições manuais destrutivas. Preserve apenas o trecho de log necessário e redigido. Esse gate em quatro partes cobre inicialização, persistência, recuperação e tratamento de falhas.

Torne a inicialização do Gotenberg reproduzível

Use um comando que exponha todas as escolhas importantes. Esta baseline vincula o Gotenberg ao loopback do host, adiciona os data mounts conhecidos e fornece a primeira configuração necessária. Confirme o requisito local antes da exposição: CPU e memória disponíveis para os workers do Chromium e do LibreOffice.

docker run -d \
  --name gotenberg \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  gotenberg/gotenberg:8

Substitua tags flutuantes por uma versão ou digest testado. Após a inicialização, inspecione docker logs --tail 200 gotenberg e confirme que o processo está escutando na porta 3000. Em seguida, execute a action de acceptance do Gotenberg; uma resposta da root page não comprova que o cenário completo funciona: envie HTML e assets como dados multipart, gere um PDF, repita com um documento do Office e inspecione o health endpoint após cada conversão.

Evite que o sucesso do proxy mascare uma falha da aplicação

Escolha o hostname final do Gotenberg antes que os usuários salvem callbacks ou configurações de clientes e, em seguida, exponha a API de conversão por HTTPS ou por um domínio interno privado. A route da plataforma deve terminar o TLS uma vez e apontar para a porta privada 3000.

Execute a transação de acceptance externamente. Se o cliente nunca chegar ao Gotenberg, use o checklist de validação de SSL para verificar DNS e certificados. Se a request chegar ao Gotenberg, mas as requests usarem o campo multipart incorreto ou as conversões excederem os timeouts do proxy, pare de alterar redirects do proxy e inspecione o boundary específico da aplicação.

Verificações de capacidade e upgrade

O indicador de serviço útil para o Gotenberg é a conclusão bem-sucedida de “enviar HTML e assets como dados multipart, gerar um PDF, repetir com um documento do Office e inspecionar o health endpoint após cada conversão”. Combine esse resultado com a contagem de processos do Chromium e do LibreOffice, o disco temporário, a complexidade dos documentos e os timeouts do proxy; uma root page verde não diz nada sobre compatibilidade do output ou esgotamento de recursos.

Antes de substituir a imagem, considere este risco: as API routes, as flags do Chromium e o comportamento do LibreOffice podem mudar entre versões principais do Gotenberg. Teste inputs representativos e de limite nas duas versões e mantenha o digest antigo até que o candidato passe. Se as requests usarem o campo multipart incorreto ou as conversões excederem os timeouts do proxy, inspecione o formato da request, o comportamento do cliente e os runtime logs antes de alterar as configurações de route ou storage.

Onde o Dockup reduz o trabalho com o Gotenberg

Um template do Gotenberg de um clique deve definir o digest da imagem, a porta 3000, o timing do health check, o domínio e o TLS. Como o serviço base é stateless, o Dockup pode recriá-lo diretamente no compute do Dockup ou em uma máquina conectada, sem fingir que um volume vazio é um backup.

Após o launch, exponha a API de conversão por HTTPS ou por um domínio interno privado. O Dockup deve preservar as configurações de runtime do Gotenberg enquanto o operador confirma este requisito local: CPU e memória disponíveis para os workers do Chromium e do LibreOffice. Verifique este resultado: envie HTML e assets como dados multipart, gere um PDF, repita com um documento do Office e inspecione o health endpoint após cada conversão. Qualquer extensão stateful posterior deve declarar seu próprio mount, secret e teste de restore, em vez de alterar silenciosamente o significado do template base.

Perguntas frequentes

O que o Gotenberg precisa para um deploy em produção?

Direcione o container do Gotenberg na porta 3000 por meio de uma única origem HTTPS. O requisito do runtime local é ter CPU e memória disponíveis para os workers do Chromium e do LibreOffice. Não considere o Gotenberg pronto até conseguir enviar HTML e assets como dados multipart, gerar um PDF, repetir com um documento do Office e inspecionar o health endpoint após cada conversão.

Quais dados do Gotenberg devem fazer parte de um backup?

A imagem padrão do Gotenberg não possui um mount obrigatório de dados da aplicação. Preserve a configuração do deploy e faça backup de qualquer estado conectado separadamente; a recuperação passa quando as fontes personalizadas, os templates e as command flags são reproduzíveis e os documentos conhecidos são renderizados com o número de páginas esperado.

O Gotenberg exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Gotenberg e mantenha a porta 3000 na route interna. Aplique corretamente a configuração do Gotenberg: exponha a API de conversão por HTTPS ou por um domínio interno privado. No Gotenberg, o HTTPS protege credenciais ou conteúdo de usuários em trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Gotenberg?

Faça o deploy da imagem candidata do Gotenberg ao lado da atual e repita a transação de acceptance com um input conhecido. Preste atenção especial, pois as API routes, as flags do Chromium e o comportamento do LibreOffice podem mudar entre versões principais do Gotenberg. O container padrão não possui migração de dados, portanto mantenha o digest anterior até que as verificações de output e compatibilidade sejam aprovadas.