Gotenberg — Wiki Interna

Gotenberg é uma API HTTP self-hosted que converte documentos para PDF usando, internamente, Chromium (renderização web) e LibreOffice (formatos Office). É stateless: não armazena arquivos, não persiste estado, e pode ser escalado horizontalmente sem coordenação.

Casos de uso típicos no escritório:

• Gerar PDFs de petições, pareceres e relatórios a partir de HTML ou DOCX renderizado por templates;
• Converter páginas web em PDF para anexar a processos (preservar prova digital);
• Mesclar PDFs (juntada de documentos);
• Carimbar/converter PDFs vindos de fluxos do N8N, Chatwoot ou da plataforma de custódia de áudios.

Documentação oficial completa: gotenberg.dev/docs — esta wiki cobre apenas o nosso uso interno.

O Traefik aplica um middleware IPAllowList em todos os endpoints da API (/forms/*, /health, /version, /metrics). Apenas o IP público da VPS está na lista.

Origem	Resultado
Requisição da própria VPS (curl, scripts cron, etc.)	✓ Permitido
Outro container do Swarm via dfanet	✓ Permitido (não passa pelo Traefik)
Qualquer outro IP externo	✗ 403 Forbidden

Esta página de wiki (rota /) é pública. Não documente segredos, IPs internos sensíveis, credenciais ou caminhos de processos aqui.

Para liberar um novo IP, editar o middleware gotenberg-ipallow no arquivo /root/gotenberg.yaml e fazer docker stack deploy -c gotenberg.yaml gotenberg.

Método	Caminho	Função
GET	/health	Healthcheck (status do Chromium e LibreOffice)
GET	/version	Versão do Gotenberg em execução
GET	/metrics	Métricas Prometheus
POST	/forms/chromium/convert/html	Converte HTML enviado (multipart) em PDF
POST	/forms/chromium/convert/url	Renderiza uma URL e devolve PDF
POST	/forms/chromium/convert/markdown	Converte Markdown em PDF (via template HTML)
POST	/forms/chromium/screenshot/url	Screenshot PNG/JPEG de uma URL
POST	/forms/libreoffice/convert	Converte DOCX/XLSX/ODT/PPT em PDF
POST	/forms/pdfengines/merge	Mescla múltiplos PDFs em um só
POST	/forms/pdfengines/convert	Converte PDF para PDF/A (arquivamento)

5.1 — HTML → PDF (a partir de arquivo local)

# index.html é o documento principal; arquivos extras (CSS, imagens) também
# podem ser anexados na mesma chamada multipart.
curl -X POST \
  -F "files=@index.html" \
  -F "files=@style.css" \
  -F "marginTop=0.4" -F "marginBottom=0.4" \
  -F "paperWidth=8.27" -F "paperHeight=11.69"   # A4 em polegadas \
  -o saida.pdf \
  https://gotenberg.dfasys.com/forms/chromium/convert/html

5.2 — URL → PDF

curl -X POST \
  -F "url=https://example.com" \
  -F "waitDelay=1s" \
  -o pagina.pdf \
  https://gotenberg.dfasys.com/forms/chromium/convert/url

5.3 — DOCX → PDF

curl -X POST \
  -F "files=@peticao.docx" \
  -o peticao.pdf \
  https://gotenberg.dfasys.com/forms/libreoffice/convert

5.4 — Mesclar PDFs

curl -X POST \
  -F "files=@parte1.pdf" \
  -F "files=@parte2.pdf" \
  -F "files=@parte3.pdf" \
  -o juntada.pdf \
  https://gotenberg.dfasys.com/forms/pdfengines/merge

5.5 — Converter para PDF/A (arquivamento de longo prazo)

curl -X POST \
  -F "files=@original.pdf" \
  -F "pdfa=PDF/A-2b" \
  -o arquivo.pdf \
  https://gotenberg.dfasys.com/forms/pdfengines/convert

PDF/A é o padrão recomendado para arquivamento legal de documentos. Combina bem com a plataforma de custódia de áudios para garantir integridade dos anexos.

Para serviços rodando no Swarm, usar o hostname interno evita o Traefik e o IPAllowList:

# Dentro do N8N (HTTP Request node), Chatwoot, Evolution, etc.
POST http://gotenberg_gotenberg:3000/forms/libreoffice/convert

Configurações recomendadas:

• N8N: usar nó HTTP Request com Send Binary File habilitado.
• Scripts Bash/cron na própria VPS: a URL pública também funciona; serão liberados pelo allowlist.
• Paperclip AI (paperclip.dfasys.com): chamar via DNS interno se for adicionado à dfanet.

Ação	Comando
Status	docker service ls | grep gotenberg
Logs em tempo real	docker service logs gotenberg_gotenberg -f
Re-deploy	docker stack deploy -c /root/gotenberg.yaml gotenberg
Atualizar imagem	docker service update --image gotenberg/gotenberg:8 gotenberg_gotenberg
Reiniciar	docker service update --force gotenberg_gotenberg
Parar	docker stack rm gotenberg

Parâmetro	Valor atual	Onde alterar
Timeout por requisição	300s	--api-timeout em gotenberg.yaml
Tamanho máximo do corpo	512 MB	--api-body-limit em gotenberg.yaml
Limite de CPU	2 vCPU	deploy.resources.limits.cpus
Limite de RAM	2048 MB	deploy.resources.limits.memory
Réplicas	1	deploy.replicas

Conversões com muitas imagens ou planilhas Excel grandes podem encostar no limite de RAM. Aumentar para 4 GB se aparecer OOM nos logs.

403 Forbidden

O IP de origem não está no allowlist. Verifique se a chamada está sendo feita da própria VPS ou ajuste o middleware no gotenberg.yaml.

504 Gateway Timeout

A conversão ultrapassou os 300s. Reduzir tamanho do documento, simplificar CSS pesado ou aumentar --api-timeout.

Falha em DOCX com fontes específicas

LibreOffice usa as fontes embarcadas no container. Para usar fontes corporativas, montar um volume em /usr/share/fonts/truetype/dfa e rodar fc-cache -f. Coordenar com a equipe de TI antes.

PDFs sem acentos ou caracteres especiais

Garantir que o HTML declare <meta charset="utf-8"> e que os arquivos sejam enviados em UTF-8 (não Latin-1).