How donue-labs/gotenberg works
Project type and purpose
• Gotenberg is a backend-only, containerized HTTP microservice (written in Go) that exposes a REST API for converting documents (HTML, Markdown, Word, Excel, etc.) into PDF.
• It follows a plugin-style, modular monolith architecture: a single service exposing multiple “modules” (Chromium, LibreOffice, PDF engines, ExifTool, Webhook, Prometheus).
Top-level components (to include
• Clients – any HTTP clients (curl, Postman, other microservices) that call Gotenberg’s endpoints.
• API Layer – the Go HTTP server (Gin/Gonic or net/http) handling routing, middleware (logging, metrics, CORS, body size limits), and request validation.
• Core Service – the Gotenberg binary running inside a Docker container. Inside it:
– Context & Env manager (pkg/gotenberg/context.go, env.go)
– Supervisor (pkg/gotenberg/supervisor.go) orchestrates module execution and cleanup
– FileSystem abstraction (pkg/gotenberg/fs.go) for temp directories and file management
– Logging & metrics (pkg/gotenberg/logging.go, metrics.go)
– Plugin registry (pkg/gotenberg/modules.go) loading each module’s routes and handlers
– Chromium (headless browser)
– LibreOffice (headless office suite)
– pdfcpu, qpdf, pdftk (PDF manipulations)
– ExifTool (metadata extraction)
– Webhook (callback client)
– Prometheus (metrics exporter endpoint)
• External binaries or services – for modules that shell out to external tools (e.g. Chrome executable, libreoffice binary, qpdf binary).
• Temporary File Store – ephemeral file system inside the container (or a mounted Docker volume) for staging input/output files.
• Networking – Docker’s internal network (shown when using docker-compose), exposing port 3000 on the host.
• Optional External Systems – Webhook receivers (if the webhook module is used), monitoring system scraping Prometheus metrics.
Relationships and data flow
1. Client issues HTTP request → hits API Layer
2. Middleware processes auth/logging/metrics → forwards to core router
3. Router delegates to Supervisor with a context
4. Supervisor loads appropriate module plugin based on the route (e.g. /convert/html uses Chromium module)
5. Module writes input to temp store → invokes binary or Go library → produces PDF in temp store
6. Module streams PDF back via HTTP response or stores it and triggers a Webhook callback
7. Metrics middleware exposes Prometheus metrics on /metrics
8. Unity: Supervisor cleans up temp files, collects logs, updates metrics
Architectural patterns & design principles
• Modular Monolith / Plugin Architecture – each conversion engine is isolated in its own package under pkg/modules.
• Supervisor Pattern – central orchestrator handles module lifecycle and error handling.
• Middleware Chain – cross-cutting concerns (logging, metrics, request size limits) applied uniformly.
• Containerization – the entire service and its dependencies run in a single Docker container for consistency.
Important technologies & frameworks
• Go (Gin/Gonic or net/http router, go modules)
• Docker & Docker Compose (build/Dockerfile, docker-compose.yml)
• GitHub Actions (CI/CD pipelines under .github/workflows)
• Prometheus client library for metrics
• External executables: Chromium, LibreOffice, qpdf, pdfcpu, pdftk, ExifTool
Detail is key
– Include every module you see under pkg/modules.
– Show the temp file system and cleanup step.
– Don’t forget cross-cutting middleware (logging, metrics).