¿Por qué autoalojar una API de generación de PDF?
Los servicios de PDF en modo SaaS (Puppeteer Cloud, PDFShift, DocRaptor) cobran por documento, por página o por volumen de llamadas a la API. En cuanto su aplicación genera facturas, informes o contratos a escala, el costo aumenta de forma lineal con su uso. Gotenberg los sustituye por un costo mensual fijo de VPS, sea cual sea el número de PDF generados. También preserva la confidencialidad de sus documentos: nada sale de su infraestructura durante la conversión.
Lo que Gotenberg puede convertir
- HTML a PDF mediante una instancia completa de Chromium — se respetan CSS, fuentes web, JavaScript y las media queries de impresión.
- Cualquier URL a PDF — archive vistas de paneles de control, genere informes semanales o capture recibos de pago.
- Documentos LibreOffice (DOCX, XLSX, PPTX, ODT, ODS, ODP y más de 20 formatos) a PDF sin Microsoft Office.
- Markdown a PDF por la ruta Chromium, con CSS configurable.
- Varios PDF fusionados en un único archivo con una sola llamada a la API.
- Imágenes (PNG, JPEG, WebP, TIFF) convertidas a PDF.
Requisitos previos
Un VPS con al menos 1 vCPU y 1 GB de RAM (2 GB recomendados para el renderizado concurrente con Chromium). Ubuntu 22.04 o 24.04 con Docker instalado. No hace falta ningún dominio: puede llamar a la API en http://127.0.0.1:3000 desde su backend en el mismo servidor, o exponerla únicamente a su red interna.
Desplegar Gotenberg paso a paso
Crear el archivo compose
Conéctese por SSH a su VPS y cree un directorio:
mkdir gotenberg && cd gotenbergCree
docker-compose.yml:services: gotenberg: image: gotenberg/gotenberg:8 restart: unless-stopped ports: - "127.0.0.1:3000:3000"La vinculación a
127.0.0.1impide el acceso directo desde Internet: la API solo es accesible desde su aplicación en el mismo servidor o a través de un reverse proxy.Arrancar el contenedor
Ejecute
docker compose up -d. Gotenberg descarga la imagen (~1,5 GB, incluye Chromium y LibreOffice) e inicia el servidor HTTP. Compruebe el endpoint de salud:curl http://127.0.0.1:3000/healthUna respuesta
{"status":"up"}confirma que el servicio está listo.Generar su primer PDF a partir de HTML
Cree un archivo HTML mínimo (
facture.html) y conviértalo:curl -s --request POST http://127.0.0.1:3000/forms/chromium/convert/html \ --form '[email protected]' \ -o facture.pdfLa respuesta es el PDF en flujo binario: rediríjalo a un archivo, a un objeto de respuesta o a una subida a S3.
Convertir un documento Word a PDF
Suba un archivo DOCX a la ruta LibreOffice:
curl -s --request POST http://127.0.0.1:3000/forms/libreoffice/convert \ --form '[email protected]' \ -o contrat.pdfGotenberg utiliza el motor LibreOffice integrado para la conversión: no se requiere ninguna licencia de Microsoft Office.
Añadir una autenticación (recomendado)
Gotenberg no trae autenticación integrada. El enfoque recomendado: instale nginx, cree un reverse proxy de
https://gotenberg.su-dominio.comhaciahttp://127.0.0.1:3000y añada una autenticación HTTP basic. Solo el backend de su aplicación debería llamar a este endpoint: no lo exponga nunca sin autenticación a la Internet pública, ya que puede utilizarse para renderizar URL arbitrarias.
Integrarlo con su aplicación
Gotenberg es independiente del lenguaje: cualquier cliente HTTP funciona. Existen bibliotecas para PHP (gotenberg-php), Node.js (chromiumly), Python (gotenberg-client), Go y otros. Para Laravel, un paquete oficial encapsula la API. En Node.js, puede llamarla con axios o con la API fetch nativa enviando un objeto FormData con el contenido HTML o el archivo.
