Cómo alojar Gotenberg por tu cuenta en 2026: HTML a PDF, timeouts y fuentes

Un despliegue de Gotenberg con errores no siempre se cae. Puede servir una página de inicio de sesión mientras las solicitudes usan el campo multipart incorrecto o las conversiones superan los timeouts del proxy. Empieza mejor con una comprobación de extremo a extremo: envía HTML y recursos como datos multipart, genera un PDF, repite la prueba con un documento de Office e inspecciona el health endpoint después de cada conversión.

Esta comprobación coincide con la finalidad catalogada de Gotenberg: un servicio HTTP que convierte HTML, Markdown y archivos de Office a PDF. También revela antes que una comprobación de disponibilidad la falta de dependencias, las suposiciones incorrectas sobre el proxy y los datos efímeros.

Puertos, procesos y servicios privados

No dejes que la imagen de Gotenberg determine por accidente la arquitectura de producción. La imagen proporciona un proceso en el puerto 3000; el almacenamiento, el enrutamiento y los requisitos externos siguen necesitando ciclos de vida definidos de forma explícita. El requisito del runtime local es contar con margen suficiente de CPU y memoria para los workers de Chromium y LibreOffice. Comprueba ese límite antes de publicar el servicio y de nuevo después de sustituir un contenedor.

El despliegue está listo para pruebas más profundas cuando puede enviar HTML y recursos como datos multipart, generar un PDF, repetir la prueba con un documento de Office e inspeccionar el health endpoint después de cada conversión. Sigue la transacción en los logs y supervisa el número de procesos de Chromium y LibreOffice, el disco temporal, la complejidad de los documentos y los timeouts del proxy. Estas observaciones muestran si la topología actual aísla el componente adecuado.

Haz medible la recuperación de Gotenberg

No se espera que haya estado de aplicación escribible dentro de la imagen estándar de Gotenberg. No conserves datos de aplicación persistentes; conserva las fuentes, las plantillas y la configuración del despliegue, incluido el digest fijado y la configuración de rutas revisada, en lugar de hacer copias de seguridad de un sistema de archivos de contenedor vacío.

Crea Gotenberg desde cero en otro host y verifica que las fuentes personalizadas, las plantillas y los flags de los comandos se pueden reproducir, y que los documentos conocidos se generan con el número de páginas esperado. Si añades una base de datos independiente, un room server o una capa de autenticación, asigna a cada componente un responsable de recuperación explícito. La guía de Git a producción muestra cómo un artefacto reproducible sustituye a una copia de seguridad del contenedor.

Registra el comando de reconstrucción y la prueba de salida conocida junto con la release. Un plan de recuperación sin estado funciona al reproducir el comportamiento a partir de entradas fiables; no debe depender de copiar un contenedor opaco en ejecución.

Reduce la autoridad de Gotenberg

El activo valioso de Gotenberg es la ruta de código que gestiona las entradas de usuario. Su riesgo específico de aplicación consiste en permitir conversiones públicas sin restricciones de tamaño ni de tiempo; en producción, los endpoints de conversión deben mantenerse privados o aplicar controles de tamaño, tasa y timeout antes de aceptar archivos que no sean de confianza.

El contenedor estándar no tiene ningún secreto de administrador, por lo que la autenticación debe configurarse en la ruta HTTPS si el servicio es privado. Fija el build, evita montajes amplios del sistema de archivos y limita el número de procesos de Chromium y LibreOffice, el disco temporal, la complejidad de los documentos y los timeouts del proxy. Usa una entrada de prueba conocida para confirmar que el build servido genera el resultado esperado después de cada actualización.

El gate de release de Gotenberg

Convierte la prueba smoke de Gotenberg en un comando de release repetible o en un runbook breve. Su salida debe demostrar este resultado: enviar HTML y recursos como datos multipart, generar un PDF, repetir la prueba con un documento de Office e inspeccionar el health endpoint después de cada conversión. Registra con el resultado la versión de la aplicación, el digest del contenedor, el hostname de la ruta y el identificador de los datos de prueba.

Ejecuta la misma comprobación después de sustituir un contenedor como parte del mantenimiento habitual y después de restaurar sin datos de aplicación persistentes; conserva las fuentes, las plantillas y la configuración del despliegue en otro lugar. La restauración se ha completado correctamente cuando las fuentes personalizadas, las plantillas y los flags de los comandos se pueden reproducir, y los documentos conocidos se generan con el número de páginas esperado. Compara los tiempos y el consumo relacionados con el número de procesos de Chromium y LibreOffice, el disco temporal, la complejidad de los documentos y los timeouts del proxy; un cambio importante merece investigación aunque la acción final siga superándose.

Después, ejecuta un fallo controlado: envía una entrada inocua cercana al límite de recursos o de formato asociado a este límite: las solicitudes usan el campo multipart incorrecto o las conversiones superan los timeouts del proxy. Confirma que Gotenberg muestra el error y vuelve a la normalidad sin cambios manuales destructivos. Conserva únicamente el fragmento de log necesario y con los datos sensibles ocultos. Este gate de cuatro partes cubre el arranque, la persistencia, la recuperación y la gestión de fallos.

Haz reproducible el arranque de Gotenberg

Usa un comando que exponga cada decisión importante. Esta configuración base vincula Gotenberg al loopback del host, añade los montajes de datos conocidos y proporciona el primer ajuste necesario. Confirma el requisito local antes de exponerlo: margen suficiente de CPU y memoria para los workers de Chromium y LibreOffice.

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

Sustituye los tags flotantes por una versión o un digest probados. Después del arranque, inspecciona docker logs --tail 200 gotenberg y confirma que el proceso escucha en el puerto 3000. A continuación, ejecuta la acción de aceptación de Gotenberg; una respuesta de la página raíz no puede demostrar que el escenario completo funciona: envía HTML y recursos como datos multipart, genera un PDF, repite la prueba con un documento de Office e inspecciona el health endpoint después de cada conversión.

Evita que el éxito del proxy oculte un fallo de la aplicación

Elige el hostname definitivo de Gotenberg antes de que los usuarios guarden callbacks o ajustes del cliente y, después, expón la API de conversión mediante HTTPS o un dominio interno privado. La ruta de la plataforma debe terminar TLS una sola vez y apuntar al puerto privado 3000.

Ejecuta la transacción de aceptación desde el exterior. Si el cliente nunca llega a Gotenberg, usa la lista de comprobación de validación de SSL para revisar el DNS y el certificado. Si la solicitud llega a Gotenberg, pero usa el campo multipart incorrecto o las conversiones superan los timeouts del proxy, deja de cambiar las redirecciones del proxy e inspecciona el límite específico de la aplicación.

Comprobaciones de capacidad y actualización

El indicador de servicio útil para Gotenberg es completar correctamente «enviar HTML y recursos como datos multipart, generar un PDF, repetir la prueba con un documento de Office e inspeccionar el health endpoint después de cada conversión». Combina ese resultado con el número de procesos de Chromium y LibreOffice, el disco temporal, la complejidad de los documentos y los timeouts del proxy; una página raíz en verde no dice nada sobre la compatibilidad de la salida ni sobre el agotamiento de recursos.

Antes de sustituir la imagen, ten en cuenta este riesgo: las rutas de la API, los flags de Chromium y el comportamiento de LibreOffice pueden cambiar entre versiones principales de Gotenberg. Prueba entradas representativas y de límite con ambas versiones, y conserva el digest anterior hasta que la candidata supere las pruebas. Si las solicitudes usan el campo multipart incorrecto o las conversiones superan los timeouts del proxy, inspecciona el formato de la solicitud, el comportamiento del cliente y los logs del runtime antes de cambiar la configuración de la ruta o del almacenamiento.

Cómo Dockup reduce el trabajo con Gotenberg

Una plantilla de Gotenberg de un solo clic debería incluir el digest de la imagen, el puerto 3000, los tiempos de health check, el dominio y TLS. Como el servicio base no tiene estado, Dockup puede recrearlo directamente en la infraestructura de Dockup o en una máquina conectada, sin fingir que un volumen vacío es una copia de seguridad.

Después del lanzamiento, expón la API de conversión mediante HTTPS o un dominio interno privado. Dockup debe conservar los ajustes del runtime de Gotenberg mientras el operador confirma este requisito local: margen suficiente de CPU y memoria para los workers de Chromium y LibreOffice. Verifica este resultado: envía HTML y recursos como datos multipart, genera un PDF, repite la prueba con un documento de Office e inspecciona el health endpoint después de cada conversión. Cualquier ampliación con estado posterior debe declarar su propio montaje, secreto y prueba de restauración, en lugar de cambiar silenciosamente el significado de la plantilla base.

Preguntas frecuentes

¿Qué necesita Gotenberg para un despliegue de producción?

Enruta el contenedor de Gotenberg a través del puerto 3000 y de un único origen HTTPS. El requisito del runtime local es contar con margen suficiente de CPU y memoria para los workers de Chromium y LibreOffice. No des por listo Gotenberg hasta que puedas enviar HTML y recursos como datos multipart, generar un PDF, repetir la prueba con un documento de Office e inspeccionar el health endpoint después de cada conversión.

¿Qué datos de Gotenberg deben incluirse en una copia de seguridad?

La imagen estándar de Gotenberg no tiene ningún montaje de datos de aplicación obligatorio. Conserva su configuración de despliegue y haz copias de seguridad de cualquier estado conectado por separado; la recuperación es correcta cuando las fuentes personalizadas, las plantillas y los flags de los comandos se pueden reproducir, y los documentos conocidos se generan con el número de páginas esperado.

¿Gotenberg necesita HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de Gotenberg y mantén el puerto 3000 en la ruta interna. Aplica correctamente el ajuste de Gotenberg: expón la API de conversión mediante HTTPS o un dominio interno privado. En Gotenberg, HTTPS protege las credenciales o el contenido del usuario durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

¿Cómo debe probarse una actualización de Gotenberg?

Despliega la imagen candidata de Gotenberg junto a la actual y repite la transacción de aceptación con una entrada conocida. Presta especial atención porque las rutas de la API, los flags de Chromium y el comportamiento de LibreOffice pueden cambiar entre versiones principales de Gotenberg. El contenedor estándar no tiene migración de datos, por lo que debes conservar el digest anterior hasta que se superen las comprobaciones de salida y compatibilidad.