Gotenberg: The Reference Architecture for PDF Generation as a Microservice

TL;DR

PDF generation is often a technical debt in modern web development. Outdated tools like wkhtmltopdf are no longer maintained, and embedding headless browsers in application containers unnecessarily bloats them and creates security vulnerabilities. Gotenberg radically solves this problem: it encapsulates the complexity of Chromium and LibreOffice in a stateless API. Instead of painstakingly building PDF logic into every microservice, delegate the task to a central, scalable service that converts HTML, Markdown, and Office documents with pixel-perfect precision.

1. The Architectural Principle: Stateless API instead of “Fat Container”

The traditional way to create PDFs is to install libraries directly in the application. This leads to “Fat Containers”: your slim Node.js or Go service suddenly becomes 1 GB large because it has to carry a full Chrome browser and thousands of system fonts.

Gotenberg turns this around. It acts as a dedicated Microservice.

• Decoupling: Your application (e.g., the shop) simply sends HTML/CSS or Office files to the Gotenberg API (POST /forms/chromium/convert/html).
• Response: Gotenberg renders the document in an isolated environment and streams the finished PDF back. Your app containers remain small, secure, and fast.

2. Core Feature: Chromium & LibreOffice Engine

Many old PDF generators fail with modern web design (Flexbox, Grid, Custom Fonts). Gotenberg uses real industry standards under the hood:

• Chromium: For HTML-to-PDF. This means you can use modern CSS3 features, web fonts, and even JavaScript to design your PDFs. What you see in the browser ends up in the PDF.
• LibreOffice: For Office-to-PDF. Gotenberg reliably converts Word (.docx), Excel (.xlsx), and PowerPoint to PDF without needing complex Java or .NET stacks.
• PDF Engine (QPDF): Allows merging multiple PDFs into a single document directly via the API.

3. Asynchronous Processing with Webhooks

PDF generation is computationally intensive. When a user requests a 500-page annual report, the HTTP request should not time out.

Gotenberg supports webhooks. You submit the job and provide a callback URL. Gotenberg processes the job in the background and pushes the finished PDF (or a download link) back to your application once it’s ready. This prevents blocked threads in your frontend.

4. Operating Models Compared: In-App / AWS Lambda vs. ayedo Managed Gotenberg

Here it is decided whether PDF generation is a maintenance nightmare or a commodity service.

Scenario A: In-App Libraries & AWS Lambda (The Maintenance Swamp)

Many teams attempt to build PDF generation themselves, often on AWS Lambda or directly in the app code.

• Dependency Hell: To get puppeteer (Headless Chrome) running on Lambda, you struggle with strict size limits (250 MB layer limit), missing shared libraries (libnss, libatk), and font rendering issues (“Tofu” characters instead of emojis).
• Security Risk: Installing binaries like wkhtmltopdf on your web server drastically increases the attack surface (RCE vulnerabilities).
• Outdated Technology: wkhtmltopdf is “archived” and no longer receives updates. Those who rely on it build on technical junk.

Scenario B: Gotenberg with Managed Kubernetes from ayedo

In the ayedo app catalog, Gotenberg is available as a ready-to-use service.

• Plug & Play: The service is preconfigured with the necessary fonts and engines. No installation of system packages in your app containers is needed.
• Scalability: Since Gotenberg is stateless, the service can be easily horizontally scaled in Kubernetes. During peak loads (e.g., invoice dispatch at the end of the month), more pods are automatically spun up.
• Standardized API: All your teams—whether they use PHP, Python, or Java—use the same central service. This standardizes the look and feel of all company documents.

Technical Comparison of Operating Models

FAQ: Gotenberg & Document Strategy

Why not just use a SaaS solution (like PDFShift)?

Privacy and cost. SaaS providers often charge per generated document. With thousands of invoices, this becomes expensive. Additionally, you have to send sensitive customer data (invoice contents) to a third party. With Gotenberg in your own cluster, the data never leaves your infrastructure.

Can Gotenberg handle my custom fonts?

Yes. You can simply send fonts (.ttf, .otf) as part of the API request. Gotenberg temporarily installs them for the rendering process. This ensures that your corporate identity (CI) is maintained pixel-perfectly, no matter which server the process runs on.

Does Gotenberg replace “wkhtmltopdf”?

Yes, completely. wkhtmltopdf is based on an ancient Qt-Webkit version that doesn’t understand modern CSS (Grid, Flexbox). Gotenberg uses Chromium. The migration usually means: being able to write better CSS and needing fewer hacks for the layout.

How performant is it?

Starting Chromium costs CPU. However, Gotenberg is optimized: the API does not keep the browser process open unnecessarily. In a Kubernetes cluster, performance can be precisely controlled via resource requests (cpu, memory). For high-volume scenarios, the asynchronous webhook API is the recommended way.

Conclusion

Documents are an essential part of business processes. However, technical generation should not be a core problem for your developers. Those who attempt to manually integrate browser engines into applications waste time on maintenance and configuration. Gotenberg abstracts this problem away. It provides a robust, API-driven “printing press” for your cloud infrastructure. With the ayedo Managed Stack, you get this component ready to use— for PDFs that look as good as your website, without the operational pain.