Acelerando los desarrollos con contenedores : Gotenberg

Publicado por Víctor Madrid el 29 July 2025

Arquitectura de SolucionesAceleradores de DesarrolloDockerGotenbergPDFConvertir

En este artículo se va a mostrar cómo poder disponer de un contenedor de forma rápida para utilizarlo durante el desarrollo o bien en cualquier entorno de ejecución con vistas a disponer de un componente software capaz de generar PDFs a partir de diferentes documentos.

En resumen ... vamos a tener un conversor a PDF local. Esto que ya parece algo tan típico y tan superado a fecha de 2025, veremos que tendrá un nuevo enfoque y que no será ninguna tontería si lo empezamos a integrar con automatismos en los flujos de trabajo.

La herramienta de la que estamos hablando se llama Gotenberg.

CABECERA

¿Qué es Gotenberg?

Gotenberg es una herramienta Open Source basada en contenedores que facilita disponer de un API REST de conversión a PDF para cierta tipología de documentos:

Imágenes: PNG, JPG, etc.
Web: HTML y Markdown
Microsoft Office: Word, Excel, Powerpoint, etc.
Formato Abierto: ODT, ODS, etc.
Etc.

Por lo tanto, se estaría eliminando la necesidad de realizar estos procesos manuales de conversión a PDF que siempre son un "roba tiempo" y en los que muchas veces se hace mal. Con su correcta implementación se estarían optimizando los flujos de trabajo al poder automatizar ciertos procesos 😃

Consideraciones

Conversión desde diferentes fuentes de origen
Soporte a diferentes tipos de protocolos: HTTP/1, HTTP/2 , etc.
Proporciona una serie de endpoints bastante versátiles
- Posibilidad de trabajar con múltiples ficheros en una petición
- Configuración individual para cada petición
- Fusión de múltiples ficheros en un único fichero
- Dispone de endpoints concretos de la aplicación ver métricas, versión, etc.
Facilita su integración desde cualquier lenguaje o aplicación que pueda realizar peticiones HTTP
Dispone de características de personalización
- Uso de cabeceras en la petición
- Opciones de configuración de la herramienta
Despliegue con Docker
- Facilita su integración en entornos modernos
- Facilita la escalabilidad y su uso en entornos distribuidos
Tiene un diseño modular, donde cada módulo se configura de forma independiente
Facilita establecer generar webhooks para la subida de ficheros asíncrona
Maneja documentos grandes, pero puede ser necesario tener que realizar algún tipo de ajuste del contenedor
Se le puede añadir autenticación a nivel de herramientas Nginx o Traefik
Dispone de monitorización básica pero se le puede integrar con herramientas como Prometheus y Grafana

Referencias:

Página web oficial
Repositorio de código del proyecto
Documentación del proyecto

A containerized API for seamless PDF conversion | Gotenberg

A containerized API for seamless PDF conversion

Gotenberg

Este es el índice que se va a utilizar para estructurar este artículo

1. Introducción
2. Stack Tecnológico
3. Ejemplos de Uso
4. Conclusiones

1. Introducción

En este apartado se tratarán los siguiente puntos :

1.1. Introducción al uso de contenedores como aceleradores del desarrollo
1.2. ¿Qué necesidades tenemos para tener un "Gotenberg" con contenedores?

1.1. Introducción al uso de contenedores como aceleradores del desarrollo

Para centralizar esta información en un único punto y así poder facilitar su consulta se ha diseñado un artículo específico

1.2. ¿Qué necesidades tenemos para requerir un "Gotenberg" con contenedores?

Los motivos principales que me llevaron a tratar de investigar en tener un Gotenberg dentro de un contenedor fueron los siguientes:

Disponer de una instalación inmutable
Replicar la instalación del producto del cliente en local o en un servidor propio (versionado, entorno, etc.)
- Uso con contenedores
Minimizar en un entorno previo los posibles cambios de configuración que pudiéramos requerir --> Perdiendo el miedo a los cambios :-)
Asegurarse de que a todo el mundo le funcionaba de primeras
Aprovechar todas las funcionalidades de la propia herramienta
Disponer de un API complejo para pruebas
...

2. Stack Tecnológico

Este es el stack tecnológico elegido para implementar la funcionalidad "n8n":

Docker - Tecnología de Contenedores/Containers
Docker Hub - Repositorio de Docker Público donde se ubican las imágenes oficiales
Gotenberg - API REST para convertir a PDF

3. Ejemplos de Uso

Para enseñar a utilizarlo y así practicar se ha habilitado un repositorio, este repositorio se reutilizará para otros artículos de "Acelerando los desarrollos con contenedores".

La parte de que tiene que ver con este artículo se encuentra en el apartado de docker/gotenberg/8.17

Este proyecto consta de un fichero Docker Compose con los siguientes elementos:

Herramienta gotenberg

Se establece la imagen de n8n con una versión establecida: gotenberg/gotenberg:8.17.1
- Esta es la versión con la que se configuró la imagen
- Se aconseja estar actualizado a nivel de la herramienta
Se define el nombre del contenedor como: gotenberg
Se define la política de restart
Se establece comandos de ejecución de la herramienta
- Se configuran aspectos como : nivel de logs, etc.
Se define el puerto:
- 3000 para las peticiones HTTP a la API

Ejemplo de fichero "docker-compose.yaml"

# Use Case: Basic Installation
services:
   # Project URL: https://github.com/gotenberg/gotenberg
   # Docs URL: https://gotenberg.dev/docs/getting-started/introduction
   gotenberg:
      image: gotenberg/gotenberg:8.17.1
      container_name: gotenberg
      restart: always
      networks: ['demo']
      command:
         # *** General ***
         - gotenberg
         - --log-level=debug # Logging levels
         - --api-timeout=10s
      ports:
         - 3000:3000
      #volumes:
         # *** Volume configuration ***
         #- ./gotenberg-data:/home/gotenberg

#volumes:
#   gotenberg-data:

networks:
   demo:
      name: demo
      driver: bridge

Para ver como lanzarlo ver fichero README dentro del proyecto.

3.1. Scripts de Soporte

N/A

3.2. Investigar lo que se usa

Cuando uno crea un contenedor basado en una imagen, ya se ha visto que consideraciones se deben tener para llegar a entender que es lo que hace.

Si tienes alguna duda vuelve a revisar el apartado "Soporte de Análisis de Contenedores" del artículo de introducción : Acelerando los desarrollos con contenedores: Introducción

Ejemplo de ejecución para mostrar la información del proceso ejecutado tras realizar un "up"

Ejemplo de inspección sobre el contenedor creado

Ejemplo de investigación general dentro del contenedor

Se podrán validar algunos de los aspectos configurados como puede ser la cadena de conexión a la base de datos, etc.

3.3. Verificar resultados

Se accede a la URL del SonarQube con:

http://localhost:3000/

De esta forma podemos verificar que se encuentran arrancado y funcionando

Se podría invocar alguno de los endpoints de gestión: /health, /version, etc.

http://localhost:3000/health

o

curl --request GET http://localhost:3000/health

3.4. Pruebas de Funcionamiento

La herramienta proporciona 3 posibles caminos para las conversiones

3.4.1. Conversión con Chromiun
3.4.2. Conversión con LibreOffice
3.4.3. Conversión a PDF/A y PDF/UA

3.4.1. Conversión con Chromiun

Esta conversión engloba conversiones a PDF de documentos tipo web.

Ver documentación (Se detallan los endpoints cubiertos, propiedades de la página o páginas de resultado, trabajo con múltiples "Media Type", etc.)

El propio módulo de Chromiun tiene su configuración específica

Consideraciones:

Engloba conversiones utilizando de fuente: una URL, un fichero de HTML, un fichero de Markdown o una captura de pantalla
Facilita trabajar con múltiples ficheros
Incluye cabeceras de uso en la petición de respuesta
Algunos de las conversiones tienen limitaciones, por lo que conviene revisar la información de cada endpoint
Trabaja con formatos de PDF/A y PDF/UA

3.4.2. Conversión con LibreOffice

Esta conversión engloba conversiones a PDF de documentos tipo Office.

Ver documentación (Se detallan los endpoints cubiertos, propiedades de la página o páginas de resultado, compresión de calidad, merge, etc)

El propio módulo de LibreOffice tiene su configuración específica

Consideraciones:

Engloba conversiones utilizando de fuente: Word, Excel, Powerpoint, etc.
- Oficiales y formatos libres
- Dispone de muchos formatos permitidos
- Permite compresión de calidad
- Trabaja con formatos de PDF/A y PDF/UA

3.4.3. Conversión a PDF/A y PDF/UA

Esta conversión engloba conversiones a PDF de documentos PDF.

Ver documentación (Se detallan los endpoints cubiertos, lectura de metadatos, merge, split, etc)

El propio módulo de LibreOffice tiene su configuración específica

Consideraciones:

Engloba operaciones con PDFs: merge, split, etc.

3.5. Práctica

Ejemplo de URL

Queremos generar un PDF a partir de la página web mostrada de : www.enmilocalfunciona.io

Ejemplo de petición cURL con algunos modificadores

curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--form url=https://www.enmilocalfunciona.io/ \
--form landscape=true \
--form marginTop=1 \
--form marginBottom=1 \
-o ./resultado.pdf

Resultado

4. Conclusiones

Si alguna vez soñaste con convertir documentos a PDF sin perder horas de tu vida en procesos manuales, Gotenberg puede ser uno de los mejores compañeros. Facilita un API REST muy potente con el que convertir una gran tipología de documentos a PDF.

Uno de sus puntos fuertes es su despliegue mediante contenedores Docker lo que facilita enormemente su uso, sin llegar a entender cómo funciona por dentro...jejeje.

En esta versión enseñamos una configuración básica, pero posteriormente se puede adaptar mucho más a cada casuística incluyendo aspectos de autenticación, proxys, monitorización, etc.

Gotenberg puede ser esa herramienta que nunca supiste que necesitabas 😃