Gotenberg: Die Referenz-Architektur für PDF-Generierung als Microservice

TL;DR

PDF-Generierung ist in der modernen Webentwicklung oft ein technischer Schuldenberg. Veraltete Tools wie wkhtmltopdf werden nicht mehr gewartet, und das Einbetten von Headless-Browsern in Applikations-Container bläht diese unnötig auf und schafft Sicherheitslücken. Gotenberg löst dieses Problem radikal: Es kapselt die Komplexität von Chromium und LibreOffice in einer zustandslosen API. Anstatt PDF-Logik mühsam in jeden Microservice zu bauen, delegieren Sie die Aufgabe an einen zentralen, skalierbaren Service, der HTML, Markdown und Office-Dokumente pixelgenau konvertiert.

1. Das Architektur-Prinzip: Stateless API statt “Fat Container”

Der traditionelle Weg, PDFs zu erstellen, besteht darin, Bibliotheken direkt in der Applikation zu installieren. Das führt zu “Fat Containers”: Ihr schlanker Node.js- oder Go-Service ist plötzlich 1 GB groß, weil er einen kompletten Chrome-Browser und tausende System-Fonts mitschleppen muss.

Gotenberg dreht das um. Es fungiert als dedizierter Microservice.

• Entkopplung: Ihre Applikation (z.B. der Shop) sendet lediglich HTML/CSS oder Office-Dateien an die Gotenberg-API (POST /forms/chromium/convert/html).
• Antwort: Gotenberg rendert das Dokument in einer isolierten Umgebung und streamt das fertige PDF zurück. Ihre App-Container bleiben klein, sicher und schnell.

2. Kern-Feature: Chromium & LibreOffice Engine

Viele alte PDF-Generatoren scheitern an modernem Web-Design (Flexbox, Grid, Custom Fonts). Gotenberg nutzt unter der Haube echte Industriestandards:

• Chromium: Für HTML-zu-PDF. Das bedeutet, Sie können moderne CSS3-Features, Webfonts und sogar JavaScript nutzen, um Ihre PDFs zu designen. Was Sie im Browser sehen, landet im PDF.
• LibreOffice: Für Office-zu-PDF. Gotenberg konvertiert Word (.docx), Excel (.xlsx) und Powerpoint zuverlässig in PDF, ohne dass Sie komplexe Java- oder .NET-Stacks benötigen.
• PDF-Engine (QPDF): Ermöglicht das Zusammenfügen (Mergen) mehrerer PDFs zu einem einzigen Dokument direkt über die API.

3. Asynchrone Verarbeitung mit Webhooks

PDF-Generierung ist rechenintensiv. Wenn ein Nutzer einen Jahresreport mit 500 Seiten anfordert, soll der HTTP-Request nicht ins Timeout laufen.

Gotenberg unterstützt Webhooks. Sie senden den Auftrag ab und geben eine Rückruf-URL an. Gotenberg verarbeitet den Job im Hintergrund und pusht das fertige PDF (oder einen Download-Link) an Ihre Applikation zurück, sobald es fertig ist. Das verhindert blockierte Threads in Ihrem Frontend.

4. Betriebsmodelle im Vergleich: In-App / AWS Lambda vs. ayedo Managed Gotenberg

Hier entscheidet sich, ob PDF-Generierung ein Wartungs-Albtraum oder ein Commodity-Service ist.

Szenario A: In-App Libraries & AWS Lambda (Der Wartungs-Sumpf)

Viele Teams versuchen, PDF-Generierung selbst zu bauen, oft auf AWS Lambda oder direkt im App-Code.

• Dependency Hell: Um puppeteer (Headless Chrome) auf Lambda zum Laufen zu kriegen, kämpfen Sie mit strikten Größenlimits (250 MB Layer Limit), fehlenden Shared Libraries (libnss, libatk) und Font-Rendering-Problemen (“Tofu”-Zeichen statt Emojis).
• Security Risiko: Wenn Sie Binaries wie wkhtmltopdf auf Ihrem Webserver installieren, erhöhen Sie die Angriffsfläche drastisch (RCE-Lücken).
• Veraltete Technik: wkhtmltopdf ist “archived” und erhält keine Updates mehr. Wer darauf setzt, baut auf technischem Sondermüll.

Szenario B: Gotenberg mit Managed Kubernetes von ayedo

Im ayedo App-Katalog steht Gotenberg als fertiger Service bereit.

• Plug & Play: Der Service ist vorkonfiguriert mit den nötigen Fonts und Engines. Keine Installation von System-Paketen in Ihren App-Containern nötig.
• Skalierbarkeit: Da Gotenberg stateless ist, kann der Service in Kubernetes einfach horizontal skaliert werden. Bei Lastspitzen (z.B. Rechnungsversand am Monatsende) fahren automatisch mehr Pods hoch.
• Standardisierte API: Alle Ihre Teams – egal ob sie PHP, Python oder Java nutzen – verwenden denselben zentralen Service. Das vereinheitlicht das Look & Feel aller Unternehmens-Dokumente.

Technischer Vergleich der Betriebsmodelle

FAQ: Gotenberg & Document Strategy

Warum nicht einfach eine SaaS-Lösung (wie PDFShift) nutzen?

Datenschutz und Kosten. SaaS-Anbieter berechnen oft pro generiertem Dokument. Bei tausenden Rechnungen wird das teuer. Zudem müssen Sie sensible Kundendaten (Rechnungsinhalte) an einen Drittanbieter senden. Mit Gotenberg im eigenen Cluster verlassen die Daten niemals Ihre Infrastruktur.

Kann Gotenberg mit meinen Custom Fonts umgehen?

Ja. Sie können Schriftarten (.ttf, .otf) einfach als Teil des API-Requests mitsenden. Gotenberg installiert diese temporär für den Render-Prozess. Das garantiert, dass Ihre Corporate Identity (CI) pixelgenau eingehalten wird, egal auf welchem Server der Prozess läuft.

Ersetzt Gotenberg “wkhtmltopdf”?

Ja, vollständig. wkhtmltopdf basiert auf einer uralten Qt-Webkit-Version, die modernes CSS (Grid, Flexbox) nicht versteht. Gotenberg nutzt Chromium. Die Migration bedeutet meist: Besseres CSS schreiben können und weniger Hacks für das Layout benötigen.

Wie performant ist das?

Chromium zu starten kostet CPU. Gotenberg ist jedoch optimiert: Die API hält den Browser-Prozess nicht unnötig offen. In einem Kubernetes Cluster lässt sich die Performance über Resource Requests (cpu, memory) exakt steuern. Für High-Volume-Szenarien ist die asynchrone Webhook-API der empfohlene Weg.

Fazit

Dokumente sind ein wesentlicher Bestandteil von Geschäftsprozessen. Die technische Erzeugung sollte jedoch kein Kernproblem Ihrer Entwickler sein. Wer versucht, Browser-Engines manuell in Applikationen zu integrieren, verschwendet Zeit mit Wartung und Konfiguration. Gotenberg abstrahiert dieses Problem weg. Es liefert eine robuste, API-gesteuerte “Druckerei” für Ihre Cloud-Infrastruktur. Mit dem ayedo Managed Stack erhalten Sie diese Komponente sofort einsatzbereit – für PDFs, die so gut aussehen wie Ihre Webseite, ohne den operativen Schmerz.