Pourquoi auto-héberger une API de génération PDF ?
Les services PDF SaaS (Puppeteer Cloud, PDFShift, DocRaptor) facturent par document, par page ou par volume d'appels API. Dès que votre application génère des factures, rapports ou contrats à l'échelle, le coût augmente linéairement avec votre usage. Gotenberg les remplace par un coût VPS mensuel fixe, quel que soit le nombre de PDF générés. Il préserve également la confidentialité de vos documents : rien ne quitte votre infrastructure pendant la conversion.
Ce que Gotenberg peut convertir
- HTML vers PDF via une instance Chromium complète — CSS, polices web, JavaScript et media queries d'impression sont tous honorés.
- N'importe quelle URL vers PDF — archivez des vues de tableau de bord, générez des rapports hebdomadaires ou capturez des reçus de paiement.
- Documents LibreOffice (DOCX, XLSX, PPTX, ODT, ODS, ODP et 20+ formats) vers PDF sans Microsoft Office.
- Markdown vers PDF via la route Chromium avec CSS configurable.
- Plusieurs PDF fusionnés en un seul fichier en un appel API.
- Images (PNG, JPEG, WebP, TIFF) converties en PDF.
Prérequis
Un VPS avec au moins 1 vCPU et 1 Go de RAM (2 Go recommandés pour le rendu Chromium concurrent). Ubuntu 22.04 ou 24.04 avec Docker installé. Aucun domaine nécessaire — vous pouvez appeler l'API sur http://127.0.0.1:3000 depuis votre backend sur le même serveur, ou l'exposer à votre réseau interne uniquement.
Déployer Gotenberg étape par étape
Créer le fichier compose
Connectez-vous en SSH à votre VPS et créez un répertoire :
mkdir gotenberg && cd gotenbergCréez docker-compose.yml :
services:
gotenberg:
image: gotenberg/gotenberg:8
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000"La liaison à 127.0.0.1 empêche l'accès direct depuis Internet — l'API n'est accessible que depuis votre application sur le même serveur ou via un reverse proxy.
Démarrer le conteneur
Exécutez docker compose up -d. Gotenberg tire l'image (~1,5 Go, inclut Chromium et LibreOffice) et démarre le serveur HTTP. Vérifiez l'endpoint de santé :
curl http://127.0.0.1:3000/healthUne réponse {"status":"up"} confirme que le service est prêt.
Générer votre premier PDF depuis HTML
Créez un fichier HTML minimal (facture.html) et convertissez-le :
curl -s --request POST http://127.0.0.1:3000/forms/chromium/convert/html \
--form '[email protected]' \
-o facture.pdfLa réponse est le PDF en flux binaire — redirigez-le vers un fichier, un objet réponse ou un upload S3.
Convertir un document Word en PDF
Téléversez un fichier DOCX vers la route LibreOffice :
curl -s --request POST http://127.0.0.1:3000/forms/libreoffice/convert \
--form '[email protected]' \
-o contrat.pdfGotenberg utilise le moteur LibreOffice intégré pour la conversion — aucune licence Microsoft Office requise.
Ajouter une authentification (recommandé)
Gotenberg n'a pas d'authentification intégrée. L'approche recommandée : installez nginx, créez un reverse proxy de https://gotenberg.votre-domaine.com vers http://127.0.0.1:3000, et ajoutez une authentification HTTP basic. Seul le backend de votre application devrait appeler cet endpoint — ne l'exposez jamais sans authentification à Internet public, car il peut être utilisé pour rendre des URLs arbitraires.
Intégrer avec votre application
Gotenberg est indépendant du langage — tout client HTTP fonctionne. Des bibliothèques existent pour PHP (gotenberg-php), Node.js (chromiumly), Python (gotenberg-client), Go et d'autres. Pour Laravel, un package officiel encapsule l'API. En Node.js, vous pouvez l'appeler avec axios ou l'API fetch native en envoyant un objet FormData avec le contenu HTML ou le fichier.
