Gotenberg — API-Driven Document Conversion and PDF Generation Server

Introduction

Gotenberg is a Docker-based, stateless API server for converting documents to PDF. It wraps Chromium and LibreOffice behind a simple HTTP API, letting any application generate high-fidelity PDFs from HTML, Markdown, Office files, or live URLs without managing browser or office suite dependencies directly.

What Gotenberg Does

• Converts HTML, Markdown, and URLs to PDF via a headless Chromium engine
• Transforms Office documents (DOCX, XLSX, PPTX, ODT) to PDF using LibreOffice
• Merges multiple PDFs into a single document with configurable page ordering
• Supports custom headers, footers, page size, margins, and landscape orientation
• Provides webhook-based async processing for long-running conversions

Architecture Overview

Gotenberg is a Go application that orchestrates Chromium and LibreOffice as conversion engines inside a single Docker container. Incoming HTTP multipart requests are routed to the appropriate engine, which processes the document and returns a PDF stream. The server is stateless by design, making it straightforward to scale horizontally behind a load balancer. Health check endpoints support container orchestration.

Self-Hosting & Configuration

• Run as a single Docker container with no external dependencies
• Configure via environment variables or CLI flags for API port, timeouts, and concurrency
• Set Chromium flags for custom rendering behavior like disabling JavaScript or sandbox mode
• Adjust LibreOffice listener pool size for Office document throughput
• Place behind a reverse proxy with rate limiting for production exposure

Key Features

• Stateless design enables effortless horizontal scaling
• High-fidelity rendering using real Chromium and LibreOffice engines
• Multipart form API works from any language with HTTP support
• Webhook mode for asynchronous PDF delivery to callback URLs
• Built-in health and metrics endpoints for monitoring

Comparison with Similar Tools

• wkhtmltopdf — Older HTML-to-PDF converter using QtWebKit; lacks modern CSS support and active maintenance
• Puppeteer — Node.js Chrome automation; requires custom server code and browser management
• WeasyPrint — Python HTML/CSS to PDF library; good for simple layouts but limited JavaScript support
• Apache PDFBox — Java library for PDF manipulation; lower-level and requires JVM integration
• Prince XML — High-quality HTML to PDF engine; commercial license required

FAQ

Q: What file formats can Gotenberg convert to PDF? A: HTML, Markdown, URLs (via Chromium), plus DOCX, XLSX, PPTX, ODT, ODS, ODP, and other LibreOffice-supported formats.

Q: Can I customize the PDF output (headers, footers, margins)? A: Yes. The API accepts parameters for page size, margins, header/footer HTML templates, landscape mode, and print background graphics.

Q: How do I handle large volumes of conversion requests? A: Run multiple Gotenberg containers behind a load balancer. Each instance is stateless, so scaling is a matter of adding replicas.

Q: Does Gotenberg support authentication? A: Gotenberg itself does not enforce auth. Place it behind a reverse proxy or API gateway to add authentication and rate limiting.

Sources

• https://github.com/gotenberg/gotenberg
• https://gotenberg.dev/docs/getting-started/introduction