Aus HTML und Word mach PDF: PDF-Generator Gotenberg 9 komplett umgebaut

Version 9.0.0 von Gotenberg ist erschienen, kurz darauf folgte bereits Version 9.1.0. Die PDF-API erhält eine eigene Engine für die PDF-Bearbeitung, Verarbeitungsschritte in frei wählbarer Reihenfolge und eine neue LibreOffice-Anbindung. Der Umstieg von Version 8 erfordert Änderungen an API-Aufrufen und Konfiguration.

Mit Gotenberg können Entwickler PDF-Erzeugung und -Bearbeitung in ihre Anwendungen einbinden. Die quelloffene, als Docker-Container verfügbare API wandelt Webseiten, HTML, Markdown und Office-Dokumente in PDFs um. Für Webinhalte nutzt sie Chromium, für Office-Dateien LibreOffice.

Eigene Engine für PDF-Bearbeitung und Normprüfung

Die in Go geschriebene PDF-Engine litho ersetzt pdfcpu, QPDF, pdftk und ExifTool. Sie läuft direkt im Gotenberg-Prozess. Die neue Engine signiert Dokumente, versieht sie mit Zeitstempeln und rendert Seiten als PNG oder JPEG. Beim Schwärzen entfernt sie die betroffenen Inhalte aus der Datei, statt sie nur in der Anzeige zu verdecken. Außerdem kann sie Formulare ausfüllen, Formularfelder in statische Seiteninhalte (Flattening) umwandeln und PDFs ohne Verlust an Bildqualität verkleinern. Verarbeitungsschritte, die vorhandene Signaturen entfernen würden, lehnt Gotenberg mit HTTP 400 ab.

Mit remediate korrigiert litho PDFs anhand eines gewählten Konformitätsprofils und prüft anschließend das Ergebnis. Unterstützt werden elf PDF/A-Konformitätsstufen für die Langzeitarchivierung sowie PDF/UA-1 und PDF/UA-2 für barrierefreie Dokumente. Auch die Kombination von PDF/A und PDF/UA sowie Factur-X gehören dazu. Letzteres verbindet eine lesbare PDF-Rechnung mit maschinenlesbaren XML-Rechnungsdaten.

Zwei Response-Header melden verbleibende Regelverstöße und Korrekturen, die litho zum Erhalt von Seiten, Text und Bildern zurückgenommen hat. Eine automatische Reparatur bedeutet damit nicht zwangsläufig vollständige Normkonformität. Über /forms/pdf/validate lassen sich auch vorhandene PDFs unabhängig von einer Konvertierung prüfen.

Verarbeitungsschritte statt fester Nachbearbeitung

Bisher steuerten einzelne Formularfelder die Nachbearbeitung in einer festen Reihenfolge. Nun übergeben Clients im Feld stages eine Liste von Verarbeitungsschritten, die Gotenberg in der angegebenen Reihenfolge ausführt. Das funktioniert mit den Konvertierungsendpunkten für Chromium und LibreOffice. Für vorhandene Dokumente steht /forms/pdf/pipe bereit. Version 9.0.0 bietet 26 solcher Schritte, die auch einzeln über /forms/pdf/<op> erreichbar sind. Details zum Aufbau der Listen finden sich in der Dokumentation zur Anfrageverarbeitung.

So kann eine Anwendung etwa zuerst ein Wasserzeichen aufbringen und anschließend mit remediate die gewünschte Normkonformität wiederherstellen. Ungültige Reihenfolgen weist Gotenberg mit HTTP 400 zurück, bevor die Verarbeitung beginnt. Sechs weitere Endpunkte liefern Informationen, Validierungsergebnisse, Metadaten, Lesezeichen, Anhänge und Formularfelder als JSON.

LibreOfficeKit ersetzt die bisherige Anbindung

Für Office-Konvertierungen ersetzt der dauerhaft laufende LibreOfficeKit-Prozess lok den bisherigen unoconverter samt Python und soffice-Listener. Gotenberg überwacht lok und startet ihn nach einem Absturz neu. Durch den Umbau der PDF- und Office-Anbindung verschwinden neben den bisherigen PDF-Werkzeugen auch Java und Python aus dem Docker-Image. Damit müssen Betreiber weniger Pakete patchen und erhalten keine CVE-Meldungen mehr zu Werkzeugen, die Gotenberg gar nicht mitliefert. Makros bleiben in LibreOffice standardmäßig deaktiviert; einschalten lässt sich ihre Ausführung über das Flag --libreoffice-enable-macros.

LibreOffice kann über nativePdfa direkt PDF/A-1b, PDF/A-2b, PDF/A-3b oder PDF/A-4 exportieren; nativePdfua unterstützt PDF/UA-1. Gotenberg wiederholt den PDF/A-Export allerdings nicht mehr nach der weiteren Bearbeitung. Wenn nachgelagerte Schritte die Konformität beeinträchtigen können, soll remediate die Verarbeitung abschließen. EPUB-Dateien nimmt die LibreOffice-Konvertierung nicht mehr an.

Neue API-Optionen und Änderungen beim Umstieg

Mit dem Feld archives kann die API hochgeladene ZIP-Archive entpacken. Betreiber begrenzen dabei die Zahl der Einträge und das Größenverhältnis beim Entpacken (zum Schutz vor ZIP-Bomben) über zwei neue Flags. Das gemeinsame Feld paperSize legt für Chromium und LibreOffice das Papierformat fest, etwa A4, Letter oder Legal.

Beim Upgrade müssen Clients die bisherigen Endpunkte unter /forms/pdfengines auf /forms/pdf umstellen und Nachbearbeitungsfelder durch stages ersetzen. Konvertierungsfelder, für die es nun auch einen eigenen Verarbeitungsschritt gibt, erhalten zur Unterscheidung das Präfix native (etwa nativePdfa). Entfernte Endpunkte antworten mit HTTP 404 und nennen ihren Nachfolger. Veraltete Felder führen zu HTTP 400 mit einem Hinweis auf die neue Verwendung.

Auch Monitoring-Konfigurationen benötigen Anpassungen: Namen von Metriken und Spans folgen nun den OpenTelemetry-Konventionen. Das bisherige Prometheus-Modul entfällt, den Export übernimmt OTEL_METRICS_EXPORTER=prometheus. Der Upgradeleitfaden von Gotenberg ordnet die bisherigen Endpunkte, Felder, Flags, Metriken und Spans ihren neuen Entsprechungen zu.

Wer das Docker-Image mit dem Tag latest herunterlädt, bekommt jetzt Gotenberg 9. Wer noch nicht umgestiegen ist, sollte vorerst gotenberg/gotenberg:8 verwenden. Image-Varianten, unterstützte Architekturen, Container-Benutzer, Port und Startbefehl bleiben unverändert. Weitere Änderungen, Sicherheitskorrekturen und Bugfixes listen die Release Notes zu Gotenberg 9.0.0 auf.