Comment auto-héberger Gotenberg en 2026 : HTML vers PDF, délais d’expiration et polices

Un déploiement Gotenberg défaillant ne plante pas forcément. Il peut servir une page de connexion alors que les requêtes utilisent le mauvais champ multipart, ou que les conversions dépassent les délais d’expiration du proxy. Commencez plutôt par une vérification de bout en bout : envoyez le HTML et les assets sous forme de données multipart, générez un PDF, recommencez avec un document Office, puis inspectez le endpoint de health après chaque conversion.

Cette vérification correspond à la fonction répertoriée de Gotenberg : un service HTTP qui convertit des fichiers HTML, Markdown et Office en PDF. Elle permet également de détecter plus tôt les dépendances manquantes, les mauvaises hypothèses concernant le proxy et les données éphémères qu’un simple probe de disponibilité.

Ports, processus et services privés

Ne laissez pas l’image Gotenberg imposer par inadvertance l’architecture de production. L’image fournit un processus sur le port 3000 ; le stockage, le routage et les exigences externes nécessitent toujours des cycles de vie définis explicitement. L’exigence du runtime local est de disposer d’une marge suffisante en CPU et en mémoire pour les workers Chromium et LibreOffice. Testez cette limite avant l’exposition, puis à nouveau après le remplacement d’un conteneur.

Le déploiement est prêt pour des tests plus approfondis lorsqu’il peut envoyer le HTML et les assets sous forme de données multipart, générer un PDF, recommencer avec un document Office, puis inspecter le endpoint de health après chaque conversion. Suivez la transaction dans les logs et surveillez le nombre de processus Chromium et LibreOffice, l’espace disque temporaire, la complexité des documents et les délais d’expiration du proxy. Ces observations indiquent si la topologie actuelle isole le bon composant.

Rendez la récupération de Gotenberg mesurable

Aucun état applicatif accessible en écriture n’est attendu dans l’image Gotenberg standard. Ne conservez aucune donnée applicative durable ; gardez les polices, les templates et la configuration de déploiement, notamment le digest épinglé et la configuration des routes validée, plutôt que de sauvegarder un système de fichiers de conteneur vide.

Recréez Gotenberg à partir de zéro sur un autre hôte et vérifiez que les polices personnalisées, les templates et les options de commande sont reproductibles, et que les documents connus sont rendus avec le nombre de pages attendu. Si une base de données distincte, un room server ou une couche d’authentification est ajouté, attribuez à ce composant son propre responsable explicite de la récupération. Le guide du dépôt Git à la production explique comment un artefact reproductible remplace une sauvegarde de conteneur.

Enregistrez la commande de reconstruction et le test de sortie connue avec la release. Un plan de récupération sans état réussit en reproduisant le comportement à partir d’entrées fiables ; il ne doit pas dépendre de la copie d’un conteneur opaque en cours d’exécution.

Réduisez les privilèges détenus par Gotenberg

L’actif précieux de Gotenberg est le chemin de code qui traite les entrées utilisateur. Le risque propre à l’application consiste à autoriser des conversions publiques sans restrictions de taille ni de délai ; en production, les endpoints de conversion doivent rester privés ou appliquer des limites de taille, de débit et de délai avant d’autoriser des fichiers non fiables.

Le conteneur standard ne contient aucun secret d’administration ; l’authentification doit donc être gérée au niveau de la route HTTPS si le service est privé. Épinglez le build, évitez les montages de système de fichiers trop larges et limitez le nombre de processus Chromium et LibreOffice, l’espace disque temporaire, la complexité des documents et les délais d’expiration du proxy. Utilisez une entrée de test connue pour confirmer que le build servi produit le résultat attendu après chaque mise à jour.

La gate de release de Gotenberg

Transformez le smoke test Gotenberg en commande de release reproductible ou en court runbook. Sa sortie doit démontrer le résultat suivant : envoyer le HTML et les assets sous forme de données multipart, générer un PDF, recommencer avec un document Office, puis inspecter le endpoint de health après chaque conversion. Enregistrez la version de l’application, le digest du conteneur, le hostname de la route et l’identifiant des données de test avec le résultat.

Exécutez la même vérification après un remplacement standard du conteneur et après la restauration sans données applicatives durables ; conservez les polices, les templates et la configuration de déploiement ailleurs. La restauration a réussi lorsque les polices personnalisées, les templates et les options de commande sont reproductibles, et que les documents connus sont rendus avec le nombre de pages attendu. Comparez la durée et la consommation associées au nombre de processus Chromium et LibreOffice, à l’espace disque temporaire, à la complexité des documents et aux délais d’expiration du proxy ; une variation importante mérite une investigation même si l’action finale réussit toujours.

Exercez ensuite un échec sans danger : envoyez une entrée inoffensive proche de la limite de ressources ou de format associée à cette limite : les requêtes utilisent le mauvais champ multipart ou les conversions dépassent les délais d’expiration du proxy. Confirmez que Gotenberg expose l’erreur et revient à la normale sans modifications manuelles destructrices. Ne conservez que l’extrait de log nécessaire, après l’avoir expurgé. Cette gate en quatre parties couvre le démarrage, la persistance, la récupération et la gestion des erreurs.

Rendez le démarrage de Gotenberg reproductible

Utilisez une commande qui expose chaque choix important. Cette configuration de référence lie Gotenberg à la loopback de l’hôte, ajoute les montages de données connus et fournit le premier paramètre requis. Confirmez l’exigence du runtime local avant l’exposition : une marge suffisante en CPU et en mémoire pour les workers Chromium et LibreOffice.

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

Remplacez les tags flottants par une version testée ou un digest. Après le démarrage, inspectez docker logs --tail 200 gotenberg et confirmez que le processus écoute sur le port 3000. Exécutez ensuite l’action d’acceptation de Gotenberg ; une réponse de la page racine ne peut pas prouver que le scénario complet fonctionne : envoyez le HTML et les assets sous forme de données multipart, générez un PDF, recommencez avec un document Office, puis inspectez le endpoint de health après chaque conversion.

Évitez qu’un succès du proxy masque une défaillance de l’application

Choisissez le hostname Gotenberg définitif avant que les utilisateurs n’enregistrent des callbacks ou des paramètres client, puis exposez l’API de conversion via HTTPS ou un domaine interne privé. La route de la plateforme doit terminer TLS une seule fois et cibler le port privé 3000.

Exécutez la transaction d’acceptation depuis l’extérieur. Si le client n’atteint jamais Gotenberg, utilisez la checklist de validation SSL pour vérifier le DNS et le certificat. Si la requête atteint Gotenberg, mais que les requêtes utilisent le mauvais champ multipart ou que les conversions dépassent les délais d’expiration du proxy, cessez de modifier les redirections du proxy et inspectez plutôt la limite propre à l’application.

Vérifications de capacité et de mise à niveau

L’indicateur de service utile pour Gotenberg est la réussite de « l’envoi du HTML et des assets sous forme de données multipart, de la génération d’un PDF, de la répétition avec un document Office et de l’inspection du endpoint de health après chaque conversion ». Associez ce résultat au nombre de processus Chromium et LibreOffice, à l’espace disque temporaire, à la complexité des documents et aux délais d’expiration du proxy ; une page racine au vert ne dit rien de la compatibilité de la sortie ni de l’épuisement des ressources.

Avant de remplacer l’image, tenez compte du risque suivant : les routes d’API, les flags Chromium et le comportement de LibreOffice peuvent changer entre les versions majeures de Gotenberg. Testez des entrées représentatives et limites sur les deux versions, et conservez l’ancien digest jusqu’à la validation du candidat. Si les requêtes utilisent le mauvais champ multipart ou que les conversions dépassent les délais d’expiration du proxy, inspectez le format de la requête, le comportement du client et les logs du runtime avant de modifier les paramètres de route ou de stockage.

Là où Dockup simplifie le travail avec Gotenberg

Un template Gotenberg en un clic doit intégrer le digest de l’image, le port 3000, le timing du health check, le domaine et TLS. Comme le service de base est sans état, Dockup peut le recréer directement sur le compute Dockup ou sur une machine attachée, sans faire passer un volume vide pour une sauvegarde.

Après le lancement, exposez l’API de conversion via HTTPS ou un domaine interne privé. Dockup doit conserver les paramètres du runtime Gotenberg pendant que l’opérateur confirme l’exigence locale suivante : une marge suffisante en CPU et en mémoire pour les workers Chromium et LibreOffice. Vérifiez ce résultat : envoyez le HTML et les assets sous forme de données multipart, générez un PDF, recommencez avec un document Office, puis inspectez le endpoint de health après chaque conversion. Toute extension ultérieure avec état doit déclarer son propre montage, son secret et son test de restauration, plutôt que de modifier silencieusement la signification du template de base.

Foire aux questions

De quoi Gotenberg a-t-il besoin pour un déploiement en production ?

Acheminez le conteneur Gotenberg sur le port 3000 via une seule origine HTTPS. L’exigence du runtime local est de disposer d’une marge suffisante en CPU et en mémoire pour les workers Chromium et LibreOffice. Ne considérez pas Gotenberg comme prêt avant de pouvoir envoyer le HTML et les assets sous forme de données multipart, générer un PDF, recommencer avec un document Office, puis inspecter le endpoint de health après chaque conversion.

Quelles données Gotenberg doivent figurer dans une sauvegarde ?

L’image Gotenberg standard ne possède aucun montage de données applicatives requis. Conservez sa configuration de déploiement et sauvegardez séparément tout état connecté ; la récupération est validée lorsque les polices personnalisées, les templates et les options de commande sont reproductibles, et que les documents connus sont rendus avec le nombre de pages attendu.

Gotenberg nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de Gotenberg et conservez le port 3000 sur la route interne. Appliquez correctement le paramètre Gotenberg : exposez l’API de conversion via HTTPS ou un domaine interne privé. Pour Gotenberg, HTTPS protège les identifiants ou le contenu utilisateur en transit et garantit un comportement cohérent du client, sensible à l’origine.

Comment tester une mise à niveau de Gotenberg ?

Déployez l’image Gotenberg candidate à côté de la version actuelle et répétez la transaction d’acceptation avec une entrée connue. Soyez particulièrement attentif, car les routes d’API, les flags Chromium et le comportement de LibreOffice peuvent changer entre les versions majeures de Gotenberg. Le conteneur standard n’a pas de migration de données ; conservez donc le digest précédent jusqu’à la validation de la sortie et de la compatibilité.