Sådan self-hoster du Gotenberg i 2026: HTML-til-PDF, timeouts og skrifttyper
Deploy Gotenberg med den rigtige port, persistent storage, TLS, authentication og backups. Fejlsøg, når requests bruger det forkerte multipart-felt i produktion.
En fejlslagen Gotenberg-deployment går ikke altid ned. Den kan vise en login-side, mens requests bruger det forkerte multipart-felt, eller konverteringer overskrider proxyens timeouts. Start i stedet med et end-to-end-tjek: send HTML og assets som multipart-data, generér en PDF, gentag med et Office-dokument, og inspicér health-endpointet efter hver konvertering.
Dette tjek matcher det katalogiserede formål med Gotenberg: en HTTP-service, der konverterer HTML, Markdown og Office-filer til PDF. Det afslører også manglende dependencies, forkerte proxy-antagelser og ephemeral data tidligere, end en uptime probe kan.
Porte, processer og private services
Lad ikke Gotenberg-imaget ved et uheld bestemme produktionsarkitekturen. Imaget leverer en proces på port 3000; storage, routing og eksterne krav kræver stadig bevidste lifecycles. Det lokale runtime-krav er tilstrækkelig CPU- og memory headroom til Chromium- og LibreOffice-workers. Test denne grænse før eksponering og igen efter udskiftning af en container.
Deploymenten er klar til mere dybdegående test, når den kan sende HTML og assets som multipart-data, generere en PDF, gentage med et Office-dokument og inspicere health-endpointet efter hver konvertering. Følg transaktionen i logs, og hold øje med antal Chromium- og LibreOffice-processer, temporary disk, dokumentkompleksitet og proxy-timeouts. Disse observationer viser, om den aktuelle topologi isolerer den rigtige komponent.
Gør Gotenberg recovery målbar
Der forventes ingen writable application state i standard-Gotenberg-imaget. Bevar ingen persistent app-data; gem i stedet fonts, templates og deployment-konfiguration, herunder den fastlåste digest og den gennemgåede route-konfiguration, frem for at tage backup af et tomt container-filsystem.
Opret Gotenberg fra bunden på en anden host, og verificér, at custom fonts, templates og command flags kan genskabes, og at kendte dokumenter rendere med det forventede antal sider. Hvis der tilføjes en separat database, room server eller authentication layer, skal komponenten have sin egen eksplicitte recovery-ejer. Guiden fra Git til produktion viser, hvordan et reproducerbart artifact erstatter en container-backup.
Registrér rebuild-kommandoen og testen med kendt output sammen med releasen. En stateless recovery-plan lykkes ved at reproducere adfærd ud fra trusted inputs; den bør ikke afhænge af, at man kopierer en opaque, kørende container.
Reducér Gotenbergs beføjelser
Det værdifulde asset i Gotenberg er den code path, der håndterer user input. Den applikationsspecifikke risiko er at tillade ubegrænsede offentlige konverteringer uden size- og timeout-kontrol; i produktion bør conversion endpoints være private, eller der bør håndhæves size-, rate- og timeout-kontrol, før untrusted files tillades.
Standard-containeren har ingen administrator secret, så authentication hører hjemme på HTTPS-routen, hvis servicen er privat. Fastlås buildet, undgå brede filesystem mounts, og begræns antal Chromium- og LibreOffice-processer, temporary disk, dokumentkompleksitet og proxy-timeouts. Brug et kendt test-input til at bekræfte, at det servede build producerer det forventede output efter hver opdatering.
Gotenbergs release gate
Gør Gotenberg-smoke-testen til en reproducerbar release-kommando eller en kort runbook. Outputtet skal demonstrere dette resultat: send HTML og assets som multipart-data, generér en PDF, gentag med et Office-dokument, og inspicér health-endpointet efter hver konvertering. Registrér application version, container digest, route hostname og test-data identifier sammen med resultatet.
Kør det samme tjek efter en almindelig container-udskiftning og efter gendannelse uden persistent app-data; gem fonts, templates og deployment-konfiguration et andet sted. Gendannelsen er lykkedes, når custom fonts, templates og command flags kan genskabes, og kendte dokumenter rendere med det forventede antal sider. Sammenlign timing og forbrug relateret til antal Chromium- og LibreOffice-processer, temporary disk, dokumentkompleksitet og proxy-timeouts; en stor ændring bør undersøges, selv når den afsluttende handling stadig lykkes.
Udfør derefter en sikker fejltest: indsend ufarligt input tæt på den resource- eller formatgrænse, der er knyttet til denne boundary: requests bruger det forkerte multipart-felt, eller konverteringer overskrider proxy-timeouts. Bekræft, at Gotenberg synliggør fejlen og vender tilbage til normal drift uden destruktive manuelle ændringer. Gem kun det nødvendige, redigerede logudsnit. Denne gate i fire dele dækker startup, persistence, recovery og failure handling.
Gør Gotenberg-startup reproducerbar
Brug en kommando, der eksponerer alle vigtige valg. Denne baseline binder Gotenberg til hostens loopback, tilføjer de kendte data mounts og angiver den første nødvendige indstilling. Bekræft det lokale krav før eksponering: tilstrækkelig CPU- og memory headroom til Chromium- og LibreOffice-workers.
docker run -d \
--name gotenberg \
--restart unless-stopped \
-p 127.0.0.1:3000:3000 \
gotenberg/gotenberg:8
Erstat floating tags med en testet version eller digest. Efter startup skal du inspicere docker logs --tail 200 gotenberg og bekræfte, at processen lytter på port 3000. Udfør derefter Gotenbergs acceptance action; et svar fra root-siden kan ikke bevise, at hele scenariet lykkes: send HTML og assets som multipart-data, generér en PDF, gentag med et Office-dokument, og inspicér health-endpointet efter hver konvertering.
Undgå, at proxy-succes skjuler fejl i applikationen
Vælg det endelige Gotenberg-hostname, før brugere gemmer callbacks eller client settings, og eksponér derefter conversion API'et via HTTPS eller et privat internt domæne. Platform-routen bør terminere TLS én gang og pege på den private port 3000.
Kør acceptance-transaktionen eksternt. Hvis klienten aldrig når Gotenberg, kan du bruge tjeklisten til SSL-validering til DNS- og certifikatkontrol. Hvis requesten når Gotenberg, men requests bruger det forkerte multipart-felt, eller konverteringer overskrider proxy-timeouts, skal du stoppe med at ændre proxy-redirects og i stedet inspicere den applikationsspecifikke boundary.
Kapacitets- og upgrade-tjek
Den nyttige serviceindikator for Gotenberg er en vellykket gennemførelse af “send HTML og assets som multipart-data, generér en PDF, gentag med et Office-dokument, og inspicér health-endpointet efter hver konvertering”. Kombinér resultatet med antal Chromium- og LibreOffice-processer, temporary disk, dokumentkompleksitet og proxy-timeouts; en grøn root-side siger intet om output-kompatibilitet eller resource exhaustion.
Før du udskifter imaget, skal du tage højde for denne risiko: API-routes, Chromium-flags og LibreOffice-adfærd kan ændre sig mellem større Gotenberg-versioner. Test repræsentative inputs og boundary-inputs mod begge versioner, og behold den gamle digest, indtil kandidaten består. Hvis requests bruger det forkerte multipart-felt, eller konverteringer overskrider proxy-timeouts, skal du inspicere request-format, client behavior og runtime-logs, før du ændrer route- eller storage-indstillinger.
Hvor Dockup fjerner arbejde for Gotenberg
En one-click Gotenberg-template bør indeholde image digest, port 3000, health-timing, domæne og TLS. Da baseservicen er stateless, kan Dockup genskabe den direkte på Dockup compute eller en tilsluttet maskine uden at lade, som om et tomt volume er en backup.
Efter launch skal du eksponere conversion API'et via HTTPS eller et privat internt domæne. Dockup bør bevare Gotenbergs runtime-indstillinger, mens operatøren bekræfter dette lokale krav: tilstrækkelig CPU- og memory headroom til Chromium- og LibreOffice-workers. Verificér dette resultat: send HTML og assets som multipart-data, generér en PDF, gentag med et Office-dokument, og inspicér health-endpointet efter hver konvertering. Alle senere stateful extensions skal erklære deres eget mount, secret og restore-test i stedet for lydløst at ændre betydningen af basetemplaten.
Ofte stillede spørgsmål
Hvad kræver Gotenberg til en produktionsdeployment?
Route Gotenberg-containeren på port 3000 gennem én HTTPS-origin. Det lokale runtime-krav er tilstrækkelig CPU- og memory headroom til Chromium- og LibreOffice-workers. Kald ikke Gotenberg klar, før du kan sende HTML og assets som multipart-data, generere en PDF, gentage med et Office-dokument og inspicere health-endpointet efter hver konvertering.
Hvilke Gotenberg-data hører hjemme i en backup?
Standard-Gotenberg-imaget har ikke noget påkrævet application-data mount. Bevar deployment-konfigurationen, og tag separat backup af tilsluttet state; recovery er bestået, når custom fonts, templates og command flags kan genskabes, og kendte dokumenter rendere med det forventede antal sider.
Kræver Gotenberg HTTPS bag en reverse proxy?
Brug HTTPS til den offentlige Gotenberg-origin, og behold port 3000 på den interne route. Anvend Gotenberg-indstillingen korrekt: eksponér conversion API'et via HTTPS eller et privat internt domæne. For Gotenberg beskytter HTTPS credentials eller user content under transport og sikrer ensartet origin-sensitive client behavior.
Hvordan bør en Gotenberg-opgradering testes?
Deploy det nye Gotenberg-image ved siden af det aktuelle, og gentag acceptance-transaktionen med kendt input. Vær særligt opmærksom, fordi API-routes, Chromium-flags og LibreOffice-adfærd kan ændre sig mellem større Gotenberg-versioner. Standard-containeren har ingen data migration, så behold den tidligere digest, indtil output- og kompatibilitetstjek er bestået.