Gotenberg 2026 selbst hosten: HTML-zu-PDF, Timeouts und Fonts

Ein fehlgeschlagenes Gotenberg-Deployment führt nicht immer zu einem Absturz. Möglicherweise wird eine Login-Seite ausgeliefert, während Requests das falsche Multipart-Feld verwenden oder Konvertierungen die Proxy-Timeouts überschreiten. Beginne stattdessen mit einer End-to-End-Prüfung: Sende HTML und Assets als Multipart-Daten, rendere ein PDF, wiederhole den Vorgang mit einem Office-Dokument und überprüfe den Health-Endpunkt nach jeder Konvertierung.

Diese Prüfung entspricht dem dokumentierten Zweck von Gotenberg: einem HTTP-Service, der HTML-, Markdown- und Office-Dateien in PDF konvertiert. Außerdem macht sie fehlende Dependencies, falsche Proxy-Annahmen und flüchtige Daten früher sichtbar als ein einfacher Uptime-Check.

Ports, Prozesse und private Services

Überlasse es nicht versehentlich dem Gotenberg-Image, die Production-Architektur festzulegen. Das Image stellt einen Prozess auf Port 3000 bereit; Storage, Routing und externe Abhängigkeiten benötigen weiterhin bewusst definierte Lifecycles. Die lokale Runtime-Anforderung besteht aus ausreichenden CPU- und Memory-Reserven für Chromium- und LibreOffice-Worker. Teste diese Grenze vor der Veröffentlichung und erneut nach dem Austausch eines Containers.

Das Deployment ist bereit für weiterführende Tests, wenn es HTML und Assets als Multipart-Daten senden, ein PDF rendern, den Vorgang mit einem Office-Dokument wiederholen und den Health-Endpunkt nach jeder Konvertierung überprüfen kann. Verfolge die Transaktion in den Logs und beobachte die Anzahl der Chromium- und LibreOffice-Prozesse, temporären Speicherplatz, die Komplexität der Dokumente und Proxy-Timeouts. Diese Beobachtungen zeigen, ob die aktuelle Topologie die richtige Komponente isoliert.

Gotenberg-Recovery messbar machen

Im standardmäßigen Gotenberg-Image wird kein beschreibbarer Application State erwartet. Bewahre keine dauerhaften App-Daten auf, sondern sichere Fonts, Templates und die Deployment-Konfiguration einschließlich des fixierten Digests und der geprüften Route-Konfiguration, statt ein leeres Container-Dateisystem zu sichern.

Erstelle Gotenberg auf einem anderen Host von Grund auf neu und überprüfe, dass benutzerdefinierte Fonts, Templates und Command-Flags reproduzierbar sind und bekannte Dokumente mit der erwarteten Seitenanzahl gerendert werden. Wenn eine separate Datenbank, ein Room Server oder eine Authentifizierungsschicht hinzugefügt wird, weise dieser Komponente einen eigenen, ausdrücklich benannten Recovery-Verantwortlichen zu. Der Git-to-Production-Leitfaden zeigt, wie ein reproduzierbares Artefakt ein Container-Backup ersetzt.

Halte den Rebuild-Befehl und den Test mit bekanntem Output gemeinsam mit dem Release fest. Ein Stateless-Recovery-Plan ist erfolgreich, wenn er das Verhalten aus vertrauenswürdigen Eingaben reproduziert; er sollte nicht davon abhängen, einen undurchsichtigen laufenden Container zu kopieren.

Die von Gotenberg gehaltenen Berechtigungen reduzieren

Das wertvolle Asset in Gotenberg ist der Codepfad, der User-Input verarbeitet. Das anwendungsspezifische Risiko besteht darin, uneingeschränkte öffentliche Konvertierungen ohne Größen- und Timeout-Limits zuzulassen. In Production sollten die Konvertierungsendpunkte privat bleiben oder Größen-, Rate- und Timeout-Limits durchsetzen, bevor nicht vertrauenswürdige Dateien akzeptiert werden.

Der Standard-Container enthält kein Administrator-Secret. Die Authentifizierung gehört daher an die HTTPS-Route, wenn der Service privat ist. Fixiere den Build, vermeide weitreichende Filesystem-Mounts und begrenze die Anzahl der Chromium- und LibreOffice-Prozesse, den temporären Speicherplatz, die Dokumentkomplexität und Proxy-Timeouts. Verwende bekannte Testeingaben, um nach jedem Update zu bestätigen, dass der bereitgestellte Build den erwarteten Output erzeugt.

Das Gotenberg-Release-Gate

Mache den Gotenberg-Smoke-Test zu einem wiederholbaren Release-Befehl oder einem kurzen Runbook. Sein Output muss dieses Ergebnis belegen: HTML und Assets als Multipart-Daten senden, ein PDF rendern, den Vorgang mit einem Office-Dokument wiederholen und den Health-Endpunkt nach jeder Konvertierung überprüfen. Halte gemeinsam mit dem Ergebnis die Anwendungsversion, den Container-Digest, den Route-Hostname und die Kennung der Testdaten fest.

Führe dieselbe Prüfung nach einem routinemäßigen Container-Austausch und nach der Wiederherstellung ohne dauerhafte App-Daten aus; Fonts, Templates und Deployment-Konfiguration müssen an anderer Stelle erhalten bleiben. Die Wiederherstellung war erfolgreich, wenn benutzerdefinierte Fonts, Templates und Command-Flags reproduzierbar sind und bekannte Dokumente mit der erwarteten Seitenanzahl gerendert werden. Vergleiche Timing und Verbrauch im Zusammenhang mit der Anzahl der Chromium- und LibreOffice-Prozesse, temporärem Speicherplatz, Dokumentkomplexität und Proxy-Timeouts. Eine große Abweichung sollte untersucht werden, selbst wenn der abschließende Schritt weiterhin erfolgreich ist.

Führe anschließend einen sicheren Fehlerfall aus: Sende harmlose Eingaben nahe am Ressourcen- oder Formatlimit, das mit dieser Grenze verbunden ist: Requests verwenden das falsche Multipart-Feld oder Konvertierungen überschreiten die Proxy-Timeouts. Bestätige, dass Gotenberg den Fehler sichtbar macht und ohne destruktive manuelle Änderungen zum Normalbetrieb zurückkehrt. Bewahre nur den erforderlichen, bereinigten Log-Ausschnitt auf. Dieses vierteilige Gate deckt Start, Persistenz, Recovery und Fehlerbehandlung ab.

Den Gotenberg-Start reproduzierbar machen

Verwende einen Befehl, der jede wichtige Entscheidung sichtbar macht. Diese Baseline bindet Gotenberg an das Loopback-Interface des Hosts, fügt die bekannten Daten-Mounts hinzu und liefert die erste erforderliche Einstellung. Bestätige die lokale Anforderung vor der Veröffentlichung: ausreichende CPU- und Memory-Reserven für Chromium- und LibreOffice-Worker.

docker run -d \
  --name gotenberg \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  gotenberg/gotenberg:8

Ersetze Floating Tags durch eine getestete Version oder einen Digest. Überprüfe nach dem Start docker logs --tail 200 gotenberg und bestätige, dass der Prozess auf Port 3000 lauscht. Führe anschließend die Gotenberg-Akzeptanzprüfung aus. Eine Antwort von der Root-Seite kann nicht belegen, dass das vollständige Szenario erfolgreich ist: Sende HTML und Assets als Multipart-Daten, rendere ein PDF, wiederhole den Vorgang mit einem Office-Dokument und überprüfe den Health-Endpunkt nach jeder Konvertierung.

Verhindern, dass ein erfolgreicher Proxy die Anwendungsfehler verdeckt

Lege den endgültigen Gotenberg-Hostnamen fest, bevor Nutzer Callbacks oder Client-Einstellungen speichern, und stelle die Konvertierungs-API über HTTPS oder eine private interne Domain bereit. Die Plattform-Route sollte TLS einmal terminieren und auf den privaten Port 3000 zeigen.

Führe die Akzeptanztransaktion von außen aus. Wenn der Client Gotenberg nie erreicht, verwende die Checkliste zur SSL-Validierung für DNS- und Zertifikatsprüfungen. Wenn der Request Gotenberg erreicht, aber Requests das falsche Multipart-Feld verwenden oder Konvertierungen die Proxy-Timeouts überschreiten, ändere nicht weiter Proxy-Redirects, sondern untersuche stattdessen die anwendungsspezifische Grenze.

Kapazitäts- und Upgrade-Prüfungen

Der aussagekräftige Service-Indikator für Gotenberg ist der erfolgreiche Abschluss von „HTML und Assets als Multipart-Daten senden, ein PDF rendern, den Vorgang mit einem Office-Dokument wiederholen und den Health-Endpunkt nach jeder Konvertierung überprüfen“. Kombiniere dieses Ergebnis mit der Anzahl der Chromium- und LibreOffice-Prozesse, temporärem Speicherplatz, Dokumentkomplexität und Proxy-Timeouts. Eine grüne Root-Seite sagt nichts über Output-Kompatibilität oder erschöpfte Ressourcen aus.

Berücksichtige vor dem Austausch des Images dieses Risiko: API-Routen, Chromium-Flags und das Verhalten von LibreOffice können sich zwischen großen Gotenberg-Versionen ändern. Teste repräsentative Eingaben und Grenzfälle gegen beide Versionen und behalte den alten Digest, bis der Kandidat erfolgreich ist. Wenn Requests das falsche Multipart-Feld verwenden oder Konvertierungen die Proxy-Timeouts überschreiten, untersuche Request-Format, Client-Verhalten und Runtime-Logs, bevor du Routen- oder Storage-Einstellungen änderst.

Wo Dockup bei Gotenberg Arbeit abnimmt

Ein One-Click-Gotenberg-Template sollte Image-Digest, Port 3000, Health-Timing, Domain und TLS festlegen. Da der Basis-Service Stateless ist, kann Dockup ihn direkt auf Dockup Compute oder einer angeschlossenen Maschine neu erstellen, ohne ein leeres Volume fälschlich als Backup zu behandeln.

Stelle nach dem Start die Konvertierungs-API über HTTPS oder eine private interne Domain bereit. Dockup sollte die Gotenberg-Runtime-Einstellungen beibehalten, während der Operator diese lokale Anforderung bestätigt: ausreichende CPU- und Memory-Reserven für Chromium- und LibreOffice-Worker. Überprüfe dieses Ergebnis: Sende HTML und Assets als Multipart-Daten, rendere ein PDF, wiederhole den Vorgang mit einem Office-Dokument und überprüfe den Health-Endpunkt nach jeder Konvertierung. Jede spätere Stateful-Erweiterung muss ihren eigenen Mount, ihr eigenes Secret und ihren eigenen Restore-Test deklarieren, statt die Bedeutung des Basis-Templates stillschweigend zu verändern.

Häufig gestellte Fragen

Was benötigt Gotenberg für ein Production-Deployment?

Route den Gotenberg-Container auf Port 3000 über einen einzigen HTTPS-Origin. Die lokale Runtime-Anforderung besteht aus ausreichenden CPU- und Memory-Reserven für Chromium- und LibreOffice-Worker. Betrachte Gotenberg erst als bereit, wenn du HTML und Assets als Multipart-Daten senden, ein PDF rendern, den Vorgang mit einem Office-Dokument wiederholen und den Health-Endpunkt nach jeder Konvertierung überprüfen kannst.

Welche Gotenberg-Daten gehören in ein Backup?

Das standardmäßige Gotenberg-Image besitzt keinen erforderlichen Mount für Anwendungsdaten. Bewahre die Deployment-Konfiguration auf und sichere jeden verbundenen State separat. Die Recovery ist erfolgreich, wenn benutzerdefinierte Fonts, Templates und Command-Flags reproduzierbar sind und bekannte Dokumente mit der erwarteten Seitenanzahl gerendert werden.

Benötigt Gotenberg HTTPS hinter einem Reverse Proxy?

Verwende HTTPS für den öffentlichen Gotenberg-Origin und halte Port 3000 auf der internen Route. Setze die Gotenberg-Einstellung korrekt: Stelle die Konvertierungs-API über HTTPS oder eine private interne Domain bereit. Bei Gotenberg schützt HTTPS Credentials oder User-Inhalte bei der Übertragung und sorgt für ein konsistentes, vom Origin abhängiges Client-Verhalten.

Wie sollte ein Gotenberg-Upgrade getestet werden?

Stelle das Gotenberg-Kandidaten-Image neben der aktuellen Version bereit und wiederhole die Akzeptanztransaktion mit bekannten Eingaben. Achte besonders darauf, dass sich API-Routen, Chromium-Flags und das Verhalten von LibreOffice zwischen großen Gotenberg-Versionen ändern können. Der Standard-Container erfordert keine Datenmigration. Behalte daher den vorherigen Digest, bis Output- und Kompatibilitätsprüfungen erfolgreich sind.