Så självhostar du Gotenberg 2026: HTML till PDF, timeouts och typsnitt
Distribuera Gotenberg med rätt port, beständig lagring, TLS, autentisering och säkerhetskopior. Felsök när anrop använder fel multipart-fält i produktion.
En misslyckad Gotenberg-distribution kraschar inte alltid. Den kan visa en inloggningssida medan anrop använder fel multipart-fält eller konverteringar överskrider proxy-timeouts. Börja i stället med en end-to-end-kontroll: skicka HTML och tillgångar som multipart-data, generera en PDF, upprepa med ett Office-dokument och kontrollera health-endpointen efter varje konvertering.
Kontrollen motsvarar Gotenbergs dokumenterade syfte: en HTTP-tjänst som konverterar HTML-, Markdown- och Office-filer till PDF. Den synliggör också saknade beroenden, felaktiga antaganden om proxyn och ephemeral data tidigare än vad en enkel uptime-kontroll gör.
Portar, processer och privata tjänster
Låt inte Gotenberg-imagen av misstag bestämma produktionsarkitekturen. Imagen tillhandahåller en process på 3000; lagring, routing och externa krav behöver fortfarande egna, genomtänkta livscykler. Det lokala runtime-kravet är tillräcklig CPU- och minnesmarginal för Chromium- och LibreOffice-workers. Testa den gränsen före publicering och igen efter att en container har ersatts.
Distributionen är redo för mer djupgående tester när den kan skicka HTML och tillgångar som multipart-data, generera en PDF, upprepa med ett Office-dokument och kontrollera health-endpointen efter varje konvertering. Följ transaktionen i loggarna och övervaka antal Chromium- och LibreOffice-processer, temporärt diskutrymme, dokumentkomplexitet och proxy-timeouts. Observationerna visar om den aktuella topologin isolerar rätt komponent.
Gör Gotenberg-återställning mätbar
Ingen skrivbar applikationsdata förväntas finnas i standardimagen för Gotenberg. Bevara ingen beständig appdata; spara typsnitt, mallar och konfigurationsfiler för deployment, inklusive den låsta digesten och den granskade route-konfigurationen, i stället för att säkerhetskopiera ett tomt containerfilsystem.
Skapa Gotenberg från grunden på en annan host och verifiera att anpassade typsnitt, mallar och command flags kan återskapas och att kända dokument renderas med förväntat antal sidor. Om en separat databas, room server eller autentiseringslager läggs till ska komponenten ha en egen, uttrycklig återställningsansvarig. Guiden från Git till produktion visar hur en reproducerbar artefakt ersätter en containersäkerhetskopia.
Dokumentera rebuild-kommandot och testet med känt resultat tillsammans med releasen. En stateless återställningsplan lyckas genom att återskapa beteendet från betrodda indata; den ska inte vara beroende av att kopiera en ogenomskinlig, körande container.
Begränsa den behörighet Gotenberg har
Den värdefulla tillgången i Gotenberg är kodvägen som hanterar användarindata. Den applikationsspecifika risken är att tillåta obegränsade publika konverteringar utan storleks- och timeout-kontroller; i produktion bör konverteringsendpoints hållas privata eller skyddas med storleks-, rate- och timeout-kontroller innan obetrodda filer tillåts.
Standardcontainern har ingen administratörshemlighet, så autentisering hör hemma vid HTTPS-routen om tjänsten är privat. Lås bygget, undvik breda filesystem mounts och begränsa antal Chromium- och LibreOffice-processer, temporärt diskutrymme, dokumentkomplexitet och proxy-timeouts. Använd kända testindata för att bekräfta att den serverade imagen ger förväntat resultat efter varje uppdatering.
Gotenbergs release gate
Gör Gotenbergs smoke test till ett reproducerbart release-kommando eller en kort runbook. Resultatet måste visa följande: skicka HTML och tillgångar som multipart-data, generera en PDF, upprepa med ett Office-dokument och kontrollera health-endpointen efter varje konvertering. Dokumentera applikationsversion, container-digest, route-hostnamn och identifierare för testdata tillsammans med resultatet.
Kör samma kontroll efter ett vanligt containerbyte och efter att ingen beständig appdata har återställts; spara typsnitt, mallar och konfigurationsfiler för deployment någon annanstans. Återställningen har lyckats när anpassade typsnitt, mallar och command flags kan återskapas och kända dokument renderas med förväntat antal sidor. Jämför tidsåtgång och resursförbrukning kopplad till antal Chromium- och LibreOffice-processer, temporärt diskutrymme, dokumentkomplexitet och proxy-timeouts; en stor förändring bör undersökas även när slutåtgärden fortfarande lyckas.
Testa sedan ett säkert fel: skicka ofarlig indata nära resurs- eller formatgränsen för den här delen: anrop använder fel multipart-fält eller konverteringar överskrider proxy-timeouts. Bekräfta att Gotenberg visar felet och återgår till normalt läge utan destruktiva manuella ändringar. Spara endast det nödvändiga, redigerade loggutdraget. Den här gate:en täcker uppstart, persistens, återställning och felhantering.
Gör Gotenberg-uppstarten reproducerbar
Använd ett kommando som visar alla viktiga val. Den här baslinjen binder Gotenberg till hostens loopback, lägger till de kända datamounterna och anger den första obligatoriska inställningen. Bekräfta det lokala kravet före exponering: tillräcklig CPU- och minnesmarginal för Chromium- och LibreOffice-workers.
docker run -d \
--name gotenberg \
--restart unless-stopped \
-p 127.0.0.1:3000:3000 \
gotenberg/gotenberg:8
Ersätt flytande taggar med en testad version eller digest. Kontrollera efter uppstart docker logs --tail 200 gotenberg och bekräfta att processen lyssnar på 3000. Kör sedan Gotenbergs acceptanstest; ett svar från root-sidan kan inte bevisa att hela scenariot lyckas: skicka HTML och tillgångar som multipart-data, generera en PDF, upprepa med ett Office-dokument och kontrollera health-endpointen efter varje konvertering.
Förhindra att en lyckad proxy döljer applikationsfel
Välj det slutliga Gotenberg-hostnamnet innan användare sparar callbacks eller klientinställningar och exponera sedan konverterings-API:t via HTTPS eller en privat intern domän. Plattformens route bör terminera TLS en gång och rikta trafiken mot den privata porten 3000.
Kör acceptanstransaktionen externt. Om klienten aldrig når Gotenberg använder du checklistan för SSL-validering för kontroller av DNS och certifikat. Om anropet når Gotenberg men anrop använder fel multipart-fält eller konverteringar överskrider proxy-timeouts ska du sluta ändra proxy-redirects och i stället granska den applikationsspecifika gränsen.
Kapacitets- och uppgraderingskontroller
Den användbara tjänsteindikatorn för Gotenberg är att “skicka HTML och tillgångar som multipart-data, generera en PDF, upprepa med ett Office-dokument och kontrollera health-endpointen efter varje konvertering” lyckas. Kombinera resultatet med antal Chromium- och LibreOffice-processer, temporärt diskutrymme, dokumentkomplexitet och proxy-timeouts; en grön root-sida säger ingenting om kompatibilitet i resultatet eller slut på resurser.
Ta hänsyn till följande risk innan du ersätter imagen: API-routes, Chromium flags och LibreOffice-beteende kan ändras mellan större Gotenberg-versioner. Testa representativa indata och gränsfall mot båda versionerna och behåll den gamla digesten tills kandidaten har godkänts. Om anrop använder fel multipart-fält eller konverteringar överskrider proxy-timeouts ska du granska request-format, klientbeteende och runtime-loggar innan du ändrar route- eller lagringsinställningar.
Så minskar Dockup arbetet med Gotenberg
En Gotenberg-mall med ett klick bör innehålla image-digest, port 3000, health-timing, domän och TLS. Eftersom bastjänsten är stateless kan Dockup återskapa den direkt på Dockup compute eller en ansluten maskin utan att låtsas att en tom volym är en säkerhetskopia.
Efter start exponeras konverterings-API:t via HTTPS eller en privat intern domän. Dockup bör bevara Gotenbergs runtime-inställningar medan operatören bekräftar det lokala kravet: tillräcklig CPU- och minnesmarginal för Chromium- och LibreOffice-workers. Verifiera följande resultat: skicka HTML och tillgångar som multipart-data, generera en PDF, upprepa med ett Office-dokument och kontrollera health-endpointen efter varje konvertering. Alla senare stateful utökningar måste deklarera en egen mount, secret och ett eget återställningstest i stället för att tyst ändra betydelsen av basmallen.
Vanliga frågor
Vad behöver Gotenberg för en produktionsdistribution?
Routa Gotenberg-containern på port 3000 genom en enda HTTPS-origin. Det lokala runtime-kravet är tillräcklig CPU- och minnesmarginal för Chromium- och LibreOffice-workers. Markera inte Gotenberg som redo förrän du kan skicka HTML och tillgångar som multipart-data, generera en PDF, upprepa med ett Office-dokument och kontrollera health-endpointen efter varje konvertering.
Vilka Gotenberg-data hör hemma i en säkerhetskopia?
Standardimagen för Gotenberg har ingen obligatorisk mount för applikationsdata. Bevara dess konfigurationsfiler för deployment och säkerhetskopiera ansluten state separat; återställningen är godkänd när anpassade typsnitt, mallar och command flags kan återskapas och kända dokument renderas med förväntat antal sidor.
Kräver Gotenberg HTTPS bakom en reverse proxy?
Använd HTTPS för den publika Gotenberg-originen och behåll port 3000 på den interna routen. Tillämpa Gotenberg-inställningen korrekt: exponera konverterings-API:t via HTTPS eller en privat intern domän. För Gotenberg skyddar HTTPS autentiseringsuppgifter eller användarinnehåll under transport och håller origin-känsligt klientbeteende konsekvent.
Hur bör en Gotenberg-uppgradering testas?
Distribuera kandidatimagen för Gotenberg bredvid den aktuella och upprepa acceptanstransaktionen med kända indata. Var särskilt uppmärksam eftersom API-routes, Chromium flags och LibreOffice-beteende kan ändras mellan större Gotenberg-versioner. Standardcontainern har ingen datamigrering, så behåll den tidigare digesten tills kontrollerna av resultat och kompatibilitet har godkänts.