Gotenberg zelf hosten in 2026: HTML-naar-pdf, time-outs en fonts

Een mislukte Gotenberg-deployment crasht niet altijd. De service kan een loginpagina tonen terwijl requests het verkeerde multipart-veld gebruiken of conversies langer duren dan de proxy-time-outs. Begin in plaats daarvan met een end-to-end controle: verstuur HTML en assets als multipart-data, genereer een PDF, herhaal dit met een Office-document en controleer het health-endpoint na elke conversie.

Deze controle sluit aan bij het gedocumenteerde doel van Gotenberg: een HTTP-service die HTML, Markdown en Office-bestanden converteert naar PDF. De controle maakt ook ontbrekende dependencies, verkeerde proxy-aannames en vluchtige data eerder zichtbaar dan een uptime-probe kan.

Poorten, processen en private services

Laat de Gotenberg-image niet per ongeluk de productiearchitectuur bepalen. De image levert een proces op 3000; opslag, routing en externe vereisten hebben nog steeds bewust beheerde lifecycles nodig. De lokale runtimevereiste is voldoende CPU- en geheugenruimte voor Chromium- en LibreOffice-workers. Test die grens vóór publicatie en opnieuw na het vervangen van een container.

De deployment is klaar voor uitgebreidere tests wanneer deze HTML en assets als multipart-data kan versturen, een PDF kan genereren, dit kan herhalen met een Office-document en het health-endpoint na elke conversie kan controleren. Volg de transactie in de logs en houd het aantal Chromium- en LibreOffice-processen, tijdelijke schijfruimte, documentcomplexiteit en proxy-time-outs in de gaten. Deze observaties laten zien of de huidige topologie het juiste component isoleert.

Maak herstel van Gotenberg meetbaar

In de standaard-Gotenberg-image wordt geen schrijfbare applicatiestatus verwacht. Bewaar geen duurzame appdata; bewaar fonts, templates en deploymentconfiguratie, inclusief de vastgezette digest en gecontroleerde routeconfiguratie, in plaats van een lege containerfilesystem te back-uppen.

Maak Gotenberg vanaf nul aan op een andere host en controleer of aangepaste fonts, templates en commandoflags reproduceerbaar zijn en bekende documenten het verwachte aantal pagina's opleveren. Als er een aparte database, roomserver of authenticatielaag wordt toegevoegd, wijs dan voor dat component een eigen expliciete recovery-eigenaar aan. De handleiding van Git naar productie laat zien hoe een reproduceerbaar artefact een containerback-up vervangt.

Leg het rebuild-commando en de test met bekende output vast bij de release. Een stateless recoveryplan slaagt door gedrag te reproduceren vanuit betrouwbare inputs; het mag niet afhankelijk zijn van het kopiëren van een ondoorzichtige, draaiende container.

Beperk de bevoegdheden van Gotenberg

Het waardevolle asset in Gotenberg is het codepad dat user input verwerkt. Het applicatiespecifieke risico is dat onbeperkte publieke conversies worden toegestaan zonder limieten voor omvang en time-outs; in productie moeten conversie-endpoints privé blijven of moeten er limieten voor omvang, rate en time-outs worden ingesteld voordat onbetrouwbare bestanden worden toegelaten.

De standaardcontainer bevat geen administrator secret, dus authenticatie hoort thuis op de HTTPS-route als de service privé is. Zet de build vast, vermijd brede filesystem-mounts en beperk het aantal Chromium- en LibreOffice-processen, tijdelijke schijfruimte, documentcomplexiteit en proxy-time-outs. Gebruik bekende testinput om na elke update te bevestigen dat de geserveerde build de verwachte output produceert.

De Gotenberg-release-gate

Maak van de Gotenberg-smoketest een herhaalbaar releasecommando of een korte runbook. De output moet deze uitkomst aantonen: verstuur HTML en assets als multipart-data, genereer een PDF, herhaal dit met een Office-document en controleer het health-endpoint na elke conversie. Leg de applicatieversie, containerdigest, route-hostname en identifier van de testdata vast bij het resultaat.

Voer dezelfde controle uit na een reguliere containerwissel en nadat er geen duurzame appdata is teruggezet; bewaar fonts, templates en deploymentconfiguratie elders. De restore is geslaagd wanneer aangepaste fonts, templates en commandoflags reproduceerbaar zijn en bekende documenten het verwachte aantal pagina's opleveren. Vergelijk timing en verbruik met betrekking tot het aantal Chromium- en LibreOffice-processen, tijdelijke schijfruimte, documentcomplexiteit en proxy-time-outs; een grote verandering verdient onderzoek, ook wanneer de uiteindelijke actie nog steeds slaagt.

Voer daarna een veilige fouttest uit: dien onschadelijke input in die dicht bij de resource- of formatlimiet voor deze grens ligt: requests gebruiken het verkeerde multipart-veld of conversies overschrijden de proxy-time-outs. Bevestig dat Gotenberg de fout zichtbaar maakt en zonder destructieve handmatige wijzigingen terugkeert naar normaal. Bewaar alleen het noodzakelijke, geanonimiseerde logfragment. Deze vierdelige gate dekt opstarten, persistentie, recovery en foutafhandeling.

Maak het opstarten van Gotenberg reproduceerbaar

Gebruik een commando waarin elke belangrijke keuze zichtbaar is. Deze baseline bindt Gotenberg aan de loopback van de host, voegt de bekende datamounts toe en geeft de eerste vereiste instelling mee. Controleer de lokale vereiste vóór je de service blootstelt: voldoende CPU- en geheugenruimte voor Chromium- en LibreOffice-workers.

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

Vervang zwevende tags door een geteste versie of digest. Controleer na het opstarten docker logs --tail 200 gotenberg en bevestig dat het proces op 3000 luistert. Voer daarna de Gotenberg-acceptatieactie uit; een response van de rootpagina bewijst niet dat het volledige scenario slaagt: verstuur HTML en assets als multipart-data, genereer een PDF, herhaal dit met een Office-document en controleer het health-endpoint na elke conversie.

Voorkom dat proxy-succes applicatiefouten verbergt

Kies de definitieve Gotenberg-hostname voordat gebruikers callbacks of clientinstellingen opslaan en stel de conversie-API vervolgens beschikbaar via HTTPS of een privé intern domein. De platformroute moet TLS één keer termineren en doorsturen naar de private poort 3000.

Voer de acceptatietransactie extern uit. Als de client Gotenberg nooit bereikt, gebruik dan de SSL-validatiechecklist voor DNS- en certificaatcontroles. Als de request Gotenberg wel bereikt, maar requests het verkeerde multipart-veld gebruiken of conversies de proxy-time-outs overschrijden, stop dan met het wijzigen van proxy-redirects en inspecteer in plaats daarvan de applicatiespecifieke grens.

Capaciteits- en upgradecontroles

De nuttigste service-indicator voor Gotenberg is het succesvol voltooien van “HTML en assets als multipart-data versturen, een PDF genereren, dit herhalen met een Office-document en het health-endpoint na elke conversie controleren”. Combineer dat resultaat met het aantal Chromium- en LibreOffice-processen, tijdelijke schijfruimte, documentcomplexiteit en proxy-time-outs; een groene rootpagina zegt niets over outputcompatibiliteit of uitputting van resources.

Houd vóór het vervangen van de image rekening met dit risico: API-routes, Chromium-flags en LibreOffice-gedrag kunnen veranderen tussen grote Gotenberg-versies. Test representatieve en grensinputs tegen beide versies en bewaar de oude digest totdat de kandidaat is geslaagd. Als requests het verkeerde multipart-veld gebruiken of conversies de proxy-time-outs overschrijden, controleer dan het requestformaat, het gedrag van de client en de runtimelogs voordat je route- of opslaginstellingen wijzigt.

Waar Dockup werk voor Gotenberg wegneemt

Een Gotenberg-template met één klik moet de image-digest, poort 3000, health-timing, het domein en TLS vastleggen. Omdat de basisservice stateless is, kan Dockup deze rechtstreeks opnieuw aanmaken op Dockup compute of een gekoppelde machine, zonder te doen alsof een lege volume een back-up is.

Stel de conversie-API na de start beschikbaar via HTTPS of een privé intern domein. Dockup moet de runtime-instellingen van Gotenberg behouden terwijl de operator deze lokale vereiste controleert: voldoende CPU- en geheugenruimte voor Chromium- en LibreOffice-workers. Controleer deze uitkomst: verstuur HTML en assets als multipart-data, genereer een PDF, herhaal dit met een Office-document en controleer het health-endpoint na elke conversie. Elke latere stateful uitbreiding moet zijn eigen mount, secret en restore-test definiëren, zonder stilzwijgend de betekenis van het basistemplate te veranderen.

Veelgestelde vragen

Wat heeft Gotenberg nodig voor een productie-deployment?

Route de Gotenberg-container op poort 3000 via één HTTPS-origin. De lokale runtimevereiste is voldoende CPU- en geheugenruimte voor Chromium- en LibreOffice-workers. Markeer Gotenberg pas als gereed wanneer je HTML en assets als multipart-data kunt versturen, een PDF kunt genereren, dit kunt herhalen met een Office-document en het health-endpoint na elke conversie kunt controleren.

Welke Gotenberg-data hoort in een back-up?

De standaard-Gotenberg-image heeft geen vereiste mount voor applicatiedata. Bewaar de deploymentconfiguratie en back-up eventueel gekoppelde state afzonderlijk; recovery is geslaagd wanneer aangepaste fonts, templates en commandoflags reproduceerbaar zijn en bekende documenten het verwachte aantal pagina's opleveren.

Heeft Gotenberg HTTPS nodig achter een reverse proxy?

Gebruik HTTPS voor de publieke Gotenberg-origin en houd poort 3000 op de interne route. Pas de Gotenberg-instelling correct toe: stel de conversie-API beschikbaar via HTTPS of een privé intern domein. Voor Gotenberg beschermt HTTPS credentials of user content tijdens transport en zorgt het ervoor dat origingevoelig clientgedrag consistent blijft.

Hoe moet een Gotenberg-upgrade worden getest?

Implementeer de kandidaat-Gotenberg-image naast de huidige image en herhaal de acceptatietransactie met bekende input. Let extra goed op, omdat API-routes, Chromium-flags en LibreOffice-gedrag kunnen veranderen tussen grote Gotenberg-versies. De standaardcontainer heeft geen datamigratie, dus bewaar de vorige digest totdat de output- en compatibiliteitscontroles zijn geslaagd.