2026'da Gotenberg'i Self-Host Etme: HTML'den PDF'ye Dönüşüm, Zaman Aşımları ve Fontlar
Gotenberg'i doğru port, kalıcı depolama, TLS, kimlik doğrulama ve yedeklemelerle dağıtın. Üretimde istekler yanlış multipart alanını kullandığında yaşanan sorunları giderin.
Başarısız bir Gotenberg dağıtımı her zaman çökmeyebilir. İstekler yanlış multipart alanını kullanırken bir giriş sayfası sunabilir veya dönüşümler proxy zaman aşımlarını aşabilir. Bunun yerine uçtan uca bir kontrolle başlayın: HTML'yi ve varlıkları multipart veri olarak gönderin, bir PDF oluşturun, işlemi bir Office belgesiyle tekrarlayın ve her dönüşümden sonra health endpoint'i inceleyin.
Bu kontrol, Gotenberg'in kataloglanmış kullanım amacıyla örtüşür: HTML, Markdown ve Office dosyalarını PDF'ye dönüştüren bir HTTP servisi. Ayrıca eksik bağımlılıkları, yanlış proxy varsayımlarını ve geçici verileri bir uptime probe'dan daha erken ortaya çıkarır.
Portlar, işlemler ve özel servisler
Üretim mimarisini yanlışlıkla Gotenberg image'ının seçmesine izin vermeyin. Image, 3000 portunda çalışan bir process sağlar; depolama, routing ve dış gereksinimlerin yaşam döngülerini yine bilinçli şekilde yönetmeniz gerekir. Yerel runtime gereksinimi, Chromium ve LibreOffice worker'ları için yeterli CPU ve memory kapasitesidir. Bu sınırı yayına almadan önce ve bir container değişiminden sonra tekrar test edin.
Dağıtım; HTML'yi ve varlıkları multipart veri olarak gönderebildiğinde, bir PDF oluşturabildiğinde, işlemi bir Office belgesiyle tekrarlayabildiğinde ve her dönüşümden sonra health endpoint'ini inceleyebildiğinde daha kapsamlı testlere hazırdır. İşlemi log'larda takip edin; Chromium ve LibreOffice process sayısını, geçici diski, belge karmaşıklığını ve proxy time out'larını izleyin. Bu gözlemler, mevcut topolojinin doğru bileşeni izole edip etmediğini gösterir.
Gotenberg kurtarma sürecini ölçülebilir hâle getirin
Standart Gotenberg image'ı içinde yazılabilir bir uygulama durumu beklenmez. Kalıcı uygulama verilerini korumayın; bunun yerine boş bir container dosya sistemini yedeklemek yerine fontları, template'leri ve sabitlenmiş digest ile gözden geçirilmiş route yapılandırması da dâhil olmak üzere dağıtım yapılandırmasını saklayın.
Gotenberg'i başka bir host üzerinde sıfırdan oluşturun ve özel fontların, template'lerin ve command flag'lerinin yeniden üretilebilir olduğunu; bilinen belgelerin beklenen sayfa sayısıyla oluşturulduğunu doğrulayın. Ayrı bir veritabanı, room server veya authentication katmanı eklenirse bu bileşene kendi açık recovery sorumlusunu atayın. Git'ten production'a dağıtım rehberi, yeniden üretilebilir bir artifact'in container yedeğinin yerini nasıl aldığını gösterir.
Yeniden oluşturma komutunu ve bilinen çıktı testini release ile birlikte kaydedin. Stateless bir recovery planı, güvenilir girdilerden davranışı yeniden üreterek başarılı olur; opak bir çalışan container'ın kopyalanmasına bağlı olmamalıdır.
Gotenberg'in sahip olduğu yetkiyi azaltın
Gotenberg'deki değerli varlık, kullanıcı girdilerini işleyen code path'tir. Uygulamaya özgü risk, boyut ve timeout kontrolleri olmadan herkese açık dönüşümlere izin verilmesidir; production ortamında conversion endpoint'leri private tutulmalı veya güvenilmeyen dosyalara izin verilmeden önce boyut, rate ve timeout kontrolleri uygulanmalıdır.
Standart container'da administrator secret bulunmadığından authentication, servis private ise HTTPS route'unda uygulanmalıdır. Build'i pin'leyin, geniş kapsamlı filesystem mount'larından kaçının ve Chromium ile LibreOffice process sayısını, geçici diski, belge karmaşıklığını ve proxy time out'larını sınırlandırın. Sunulan build'in her güncellemeden sonra beklenen çıktıyı ürettiğini doğrulamak için bilinen bir test girdisi kullanın.
Gotenberg release gate'i
Gotenberg smoke test'ini tekrarlanabilir bir release komutuna veya kısa bir runbook'a dönüştürün. Çıktı şu sonucu kanıtlamalıdır: HTML'yi ve varlıkları multipart veri olarak gönderin, bir PDF oluşturun, işlemi bir Office belgesiyle tekrarlayın ve her dönüşümden sonra health endpoint'ini inceleyin. Sonuçla birlikte uygulama sürümünü, container digest'ini, route hostname'ini ve test verisi tanımlayıcısını kaydedin.
Aynı kontrolü rutin bir container değişiminden sonra ve kalıcı uygulama verilerini geri yüklemeden çalıştırın; fontları, template'leri ve dağıtım yapılandırmasını başka bir yerde saklayın. Restore işlemi; özel fontlar, template'ler ve command flag'leri yeniden üretilebilir olduğunda ve bilinen belgeler beklenen sayfa sayısıyla oluşturulduğunda başarılıdır. Chromium ve LibreOffice process sayısı, geçici disk, belge karmaşıklığı ve proxy time out'larıyla ilgili süreyi ve tüketimi karşılaştırın; son işlem hâlâ başarılı olsa bile büyük bir değişiklik incelenmeye değerdir.
Ardından güvenli bir hata senaryosu çalıştırın: bu sınırla ilişkili kaynak veya format limitine yakın, zararsız bir girdi gönderin: istekler yanlış multipart alanını kullanıyor veya dönüşümler proxy time out'larını aşıyor. Gotenberg'in hatayı görünür hâle getirdiğini ve yıkıcı manuel düzenlemeler olmadan normale döndüğünü doğrulayın. Yalnızca gerekli, hassas verileri çıkarılmış log bölümünü saklayın. Bu dört parçalı gate; başlatma, kalıcılık, recovery ve hata yönetimini kapsar.
Gotenberg başlangıcını yeniden üretilebilir hâle getirin
Her önemli seçeneği açıkça belirten bir komut kullanın. Bu temel yapılandırma, Gotenberg'i host loopback adresine bağlar, bilinen data mount'larını ekler ve ilk gerekli ayarı sağlar. Dış erişime açmadan önce yerel gereksinimi doğrulayın: Chromium ve LibreOffice worker'ları için yeterli CPU ve memory kapasitesi.
docker run -d \
--name gotenberg \
--restart unless-stopped \
-p 127.0.0.1:3000:3000 \
gotenberg/gotenberg:8
Değişken tag'leri test edilmiş bir sürüm veya digest ile değiştirin. Başlangıçtan sonra docker logs --tail 200 gotenberg komutunu inceleyin ve process'in 3000 portunu dinlediğini doğrulayın. Ardından Gotenberg kabul testini çalıştırın; root-page yanıtı tek başına tüm senaryonun başarılı olduğunu kanıtlayamaz: HTML'yi ve varlıkları multipart veri olarak gönderin, bir PDF oluşturun, işlemi bir Office belgesiyle tekrarlayın ve her dönüşümden sonra health endpoint'ini inceleyin.
Proxy başarısının uygulama hatasını gizlemesini önleyin
Kullanıcılar callback'leri veya client ayarlarını kaydetmeden önce nihai Gotenberg hostname'ini belirleyin; ardından conversion API'yi HTTPS veya private bir internal domain üzerinden yayınlayın. Platform route'u TLS'i bir kez sonlandırmalı ve private 3000 portunu hedeflemelidir.
Kabul işlemini dışarıdan çalıştırın. Client Gotenberg'e hiç ulaşamıyorsa DNS ve sertifika kontrolleri için SSL doğrulama kontrol listesini kullanın. İstek Gotenberg'e ulaşıyor ancak istekler yanlış multipart alanını kullanıyor veya dönüşümler proxy time out'larını aşıyorsa proxy redirect'lerini değiştirmeyi bırakın ve bunun yerine uygulamaya özgü sınırı inceleyin.
Kapasite ve upgrade kontrolleri
Gotenberg için yararlı servis göstergesi, “HTML'yi ve varlıkları multipart veri olarak gönderin, bir PDF oluşturun, işlemi bir Office belgesiyle tekrarlayın ve her dönüşümden sonra health endpoint'ini inceleyin” işleminin başarıyla tamamlanmasıdır. Bu sonucu Chromium ve LibreOffice process sayısı, geçici disk, belge karmaşıklığı ve proxy time out'larıyla birlikte değerlendirin; yeşil bir root page, çıktı uyumluluğu veya kaynak tükenmesi hakkında hiçbir şey söylemez.
Image'ı değiştirmeden önce şu riski hesaba katın: API route'ları, Chromium flag'leri ve LibreOffice davranışı, Gotenberg'in major sürümleri arasında değişebilir. Temsili ve sınırdaki girdileri her iki sürümle test edin ve aday sürüm başarılı olana kadar eski digest'i saklayın. İstekler yanlış multipart alanını kullanıyorsa veya dönüşümler proxy time out'larını aşıyorsa route ya da depolama ayarlarını değiştirmeden önce request format'ını, client davranışını ve runtime log'larını inceleyin.
Dockup, Gotenberg için hangi işleri ortadan kaldırır?
Tek tıklamalı bir Gotenberg template'i image digest'ini, 3000 portunu, health zamanlamasını, domain'i ve TLS'i içermelidir. Temel servis stateless olduğundan Dockup, boş bir volume'ün yedek olduğunu varsaymadan servisi doğrudan Dockup compute üzerinde veya bağlı bir makinede yeniden oluşturabilir.
Başlatmanın ardından conversion API'yi HTTPS veya private bir internal domain üzerinden yayınlayın. Operatör şu yerel gereksinimi doğrularken Dockup, Gotenberg runtime ayarlarını korumalıdır: Chromium ve LibreOffice worker'ları için yeterli CPU ve memory kapasitesi. Şu sonucu doğrulayın: HTML'yi ve varlıkları multipart veri olarak gönderin, bir PDF oluşturun, işlemi bir Office belgesiyle tekrarlayın ve her dönüşümden sonra health endpoint'ini inceleyin. Daha sonra eklenecek stateful her extension, temel template'in anlamını sessizce değiştirmek yerine kendi mount'unu, secret'ını ve restore test'ini tanımlamalıdır.
Sık sorulan sorular
Gotenberg'in production dağıtımı için nelere ihtiyacı vardır?
Gotenberg container'ını 3000 portu üzerinden tek bir HTTPS origin'e route edin. Yerel runtime gereksinimi, Chromium ve LibreOffice worker'ları için yeterli CPU ve memory kapasitesidir. HTML'yi ve varlıkları multipart veri olarak gönderemeden, bir PDF oluşturamadan, işlemi bir Office belgesiyle tekrarlayamadan ve her dönüşümden sonra health endpoint'ini inceleyemeden Gotenberg'i hazır kabul etmeyin.
Hangi Gotenberg verileri yedekte yer almalıdır?
Standart Gotenberg image'ında gerekli bir application-data mount'u bulunmaz. Dağıtım yapılandırmasını koruyun ve bağlı durumları ayrı ayrı yedekleyin; özel fontlar, template'ler ve command flag'leri yeniden üretilebilir olduğunda ve bilinen belgeler beklenen sayfa sayısıyla oluşturulduğunda recovery başarılıdır.
Gotenberg'in reverse proxy arkasında HTTPS kullanması gerekir mi?
Public Gotenberg origin'i için HTTPS kullanın ve 3000 portunu internal route üzerinde tutun. Gotenberg ayarını doğru uygulayın: conversion API'yi HTTPS veya private bir internal domain üzerinden yayınlayın. Gotenberg için HTTPS, credentials veya kullanıcı içeriğinin aktarım sırasında korunmasını ve origin'e duyarlı client davranışının tutarlı kalmasını sağlar.
Gotenberg upgrade'i nasıl test edilmelidir?
Aday Gotenberg image'ını mevcut sürümün yanında dağıtın ve kabul işlemini bilinen bir girdiyle tekrarlayın. API route'ları, Chromium flag'leri ve LibreOffice davranışı Gotenberg'in major sürümleri arasında değişebileceğinden bu noktalara özellikle dikkat edin. Standart container'da data migration bulunmaz; bu nedenle çıktı ve uyumluluk kontrolleri başarılı olana kadar önceki digest'i saklayın.