Come eseguire il self-hosting di Gotenberg nel 2026: da HTML a PDF, timeout e font

Un deployment di Gotenberg che non funziona non va necessariamente in crash. Potrebbe servire una pagina di login mentre le richieste usano il campo multipart errato oppure le conversioni superano i timeout del proxy. Inizia invece con un controllo end-to-end: invia HTML e asset come dati multipart, genera un PDF, ripeti con un documento Office e controlla l'health endpoint dopo ogni conversione.

Questo controllo corrisponde allo scopo documentato di Gotenberg: un servizio HTTP che converte file HTML, Markdown e Office in PDF. Inoltre fa emergere prima le dipendenze mancanti, le ipotesi errate sul proxy e i dati effimeri rispetto a un semplice uptime probe.

Porte, processi e servizi privati

Non lasciare che sia l'immagine di Gotenberg a determinare accidentalmente l'architettura di produzione. L'immagine fornisce un processo sulla porta 3000; storage, routing e requisiti esterni richiedono comunque lifecycle definiti consapevolmente. Il requisito del runtime locale è avere margine sufficiente di CPU e memoria per i worker di Chromium e LibreOffice. Verifica questo limite prima dell'esposizione e di nuovo dopo la sostituzione di un container.

Il deployment è pronto per test più approfonditi quando riesce a inviare HTML e asset come dati multipart, generare un PDF, ripetere l'operazione con un documento Office e controllare l'health endpoint dopo ogni conversione. Segui la transazione nei log e monitora il numero di processi di Chromium e LibreOffice, il disco temporaneo, la complessità dei documenti e i timeout del proxy. Queste osservazioni mostrano se la topologia attuale isola il componente corretto.

Rendi misurabile il recovery di Gotenberg

All'interno dell'immagine standard di Gotenberg non è previsto alcuno stato applicativo scrivibile. Non conservare dati applicativi persistenti; mantieni invece font, template e configurazione del deployment, incluso il digest fissato e la configurazione delle route verificata, anziché eseguire il backup di un filesystem vuoto del container.

Crea Gotenberg da zero su un altro host e verifica che font personalizzati, template e flag dei comandi siano riproducibili e che i documenti noti vengano renderizzati con il numero di pagine previsto. Se aggiungi un database separato, un room server o un livello di autenticazione, assegna a ciascun componente un responsabile esplicito per il recovery. La guida da Git alla produzione mostra come un artifact riproducibile sostituisca il backup di un container.

Registra il comando di rebuild e il test con output noto insieme alla release. Un piano di recovery stateless ha successo quando riproduce il comportamento a partire da input attendibili; non dovrebbe dipendere dalla copia di un container in esecuzione e non trasparente.

Riduci l'autorità detenuta da Gotenberg

La risorsa di valore in Gotenberg è il percorso di codice che gestisce gli input degli utenti. Il rischio specifico dell'applicazione consiste nel consentire conversioni pubbliche senza limiti di dimensione e timeout; in produzione gli endpoint di conversione dovrebbero rimanere privati oppure applicare limiti di dimensione, rate e timeout prima di consentire file non attendibili.

Il container standard non contiene alcun secret amministrativo, quindi l'autenticazione deve appartenere alla route HTTPS se il servizio è privato. Fissa la build, evita mount ampi del filesystem e limita il numero di processi di Chromium e LibreOffice, il disco temporaneo, la complessità dei documenti e i timeout del proxy. Usa input di test noti per confermare che la build esposta produca l'output previsto dopo ogni aggiornamento.

Il release gate di Gotenberg

Trasforma lo smoke test di Gotenberg in un comando di release ripetibile o in un breve runbook. Il suo output deve dimostrare questo risultato: inviare HTML e asset come dati multipart, generare un PDF, ripetere l'operazione con un documento Office e controllare l'health endpoint dopo ogni conversione. Registra insieme al risultato la versione dell'applicazione, il digest del container, l'hostname della route e l'identificatore dei dati di test.

Esegui lo stesso controllo dopo una normale sostituzione del container e dopo aver ripristinato l'assenza di dati applicativi persistenti; conserva altrove font, template e configurazione del deployment. Il restore è riuscito quando font personalizzati, template e flag dei comandi sono riproducibili e i documenti noti vengono renderizzati con il numero di pagine previsto. Confronta tempi e consumi relativi al numero di processi di Chromium e LibreOffice, al disco temporaneo, alla complessità dei documenti e ai timeout del proxy; una variazione significativa merita un'indagine anche quando l'azione finale continua ad avere successo.

Poi esegui un failure test sicuro: invia un input innocuo vicino al limite di risorse o formato associato a questo confine: le richieste usano il campo multipart errato oppure le conversioni superano i timeout del proxy. Conferma che Gotenberg segnali il problema e torni alla normalità senza modifiche manuali distruttive. Conserva solo l'estratto di log necessario e con i dati sensibili rimossi. Questo gate in quattro parti copre avvio, persistenza, recovery e gestione dei failure.

Rendi riproducibile l'avvio di Gotenberg

Usa un comando che esponga ogni scelta importante. Questa configurazione di base associa Gotenberg al loopback dell'host, aggiunge i mount dei dati noti e fornisce la prima impostazione richiesta. Conferma il requisito locale prima dell'esposizione: margine sufficiente di CPU e memoria per i worker di Chromium e LibreOffice.

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

Sostituisci i tag mobili con una versione o un digest testato. Dopo l'avvio, controlla docker logs --tail 200 gotenberg e conferma che il processo sia in ascolto sulla porta 3000. Esegui quindi l'azione di acceptance di Gotenberg; una risposta dalla pagina root non può dimostrare che lo scenario completo abbia successo: invia HTML e asset come dati multipart, genera un PDF, ripeti con un documento Office e controlla l'health endpoint dopo ogni conversione.

Evita che il successo del proxy mascheri un failure dell'applicazione

Scegli l'hostname definitivo di Gotenberg prima che gli utenti salvino callback o impostazioni client, quindi esponi l'API di conversione tramite HTTPS o un dominio interno privato. La route della piattaforma dovrebbe terminare TLS una sola volta e indirizzare alla porta privata 3000.

Esegui la transazione di acceptance dall'esterno. Se il client non raggiunge mai Gotenberg, usa la checklist di validazione SSL per i controlli DNS e del certificato. Se la richiesta raggiunge Gotenberg ma usa il campo multipart errato oppure le conversioni superano i timeout del proxy, smetti di modificare i redirect del proxy e controlla invece il confine specifico dell'applicazione.

Controlli di capacità e aggiornamento

L'indicatore di servizio utile per Gotenberg è il completamento corretto di “inviare HTML e asset come dati multipart, generare un PDF, ripetere con un documento Office e controllare l'health endpoint dopo ogni conversione”. Affianca a questo risultato il numero di processi di Chromium e LibreOffice, il disco temporaneo, la complessità dei documenti e i timeout del proxy; una pagina root verde non dice nulla sulla compatibilità dell'output o sull'esaurimento delle risorse.

Prima di sostituire l'immagine, considera questo rischio: le route API, i flag di Chromium e il comportamento di LibreOffice possono cambiare tra versioni major di Gotenberg. Testa input rappresentativi e di confine su entrambe le versioni e conserva il vecchio digest finché il candidato non supera i test. Se le richieste usano il campo multipart errato oppure le conversioni superano i timeout del proxy, controlla il formato della richiesta, il comportamento del client e i log del runtime prima di modificare le impostazioni di route o storage.

Dove Dockup riduce il lavoro per Gotenberg

Un template Gotenberg one-click dovrebbe codificare il digest dell'immagine, la porta 3000, i tempi dell'health check, il dominio e TLS. Poiché il servizio di base è stateless, Dockup può ricrearlo direttamente sull'infrastruttura di calcolo Dockup o su una macchina collegata senza fingere che un volume vuoto sia un backup.

Dopo l'avvio, esponi l'API di conversione tramite HTTPS o un dominio interno privato. Dockup dovrebbe mantenere le impostazioni del runtime di Gotenberg mentre l'operatore conferma questo requisito locale: margine sufficiente di CPU e memoria per i worker di Chromium e LibreOffice. Verifica questo risultato: invia HTML e asset come dati multipart, genera un PDF, ripeti con un documento Office e controlla l'health endpoint dopo ogni conversione. Qualsiasi estensione stateful successiva deve dichiarare il proprio mount, secret e test di restore, senza modificare silenziosamente il significato del template di base.

Domande frequenti

Di cosa ha bisogno Gotenberg per un deployment di produzione?

Indirizza il container Gotenberg sulla porta 3000 tramite un'unica origine HTTPS. Il requisito del runtime locale è avere margine sufficiente di CPU e memoria per i worker di Chromium e LibreOffice. Non considerare Gotenberg pronto finché non puoi inviare HTML e asset come dati multipart, generare un PDF, ripetere con un documento Office e controllare l'health endpoint dopo ogni conversione.

Quali dati di Gotenberg devono rientrare in un backup?

L'immagine standard di Gotenberg non ha alcun mount obbligatorio per i dati applicativi. Conserva la configurazione del deployment ed esegui separatamente il backup di qualsiasi stato collegato; il recovery è superato quando font personalizzati, template e flag dei comandi sono riproducibili e i documenti noti vengono renderizzati con il numero di pagine previsto.

Gotenberg richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Gotenberg e mantieni la porta 3000 sulla route interna. Applica correttamente l'impostazione di Gotenberg: esponi l'API di conversione tramite HTTPS o un dominio interno privato. Per Gotenberg, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come deve essere testato un aggiornamento di Gotenberg?

Esegui il deployment dell'immagine candidata di Gotenberg accanto a quella attuale e ripeti la transazione di acceptance con input noti. Presta particolare attenzione perché le route API, i flag di Chromium e il comportamento di LibreOffice possono cambiare tra versioni major di Gotenberg. Il container standard non richiede migrazioni dei dati, quindi conserva il digest precedente finché i controlli di output e compatibilità non sono superati.