Why self-host a PDF generation API?
SaaS PDF services (Puppeteer Cloud, PDFShift, DocRaptor) charge per document, per page or by API call volume. As soon as your application generates invoices, reports or contracts at scale, the cost grows linearly with your usage. Gotenberg replaces them with a fixed monthly VPS cost, regardless of how many PDFs you generate. It also keeps your documents private: nothing leaves your infrastructure during conversion.
What Gotenberg can convert
- HTML to PDF via a full Chromium instance — CSS, web fonts, JavaScript and print media queries are all honoured.
- Any URL to PDF — archive dashboard views, generate weekly reports or capture payment receipts.
- LibreOffice documents (DOCX, XLSX, PPTX, ODT, ODS, ODP and 20+ formats) to PDF without installing Microsoft Office.
- Markdown to PDF via the Chromium route with configurable CSS.
- Multiple PDFs merged into a single file in one API call.
- Images (PNG, JPEG, WebP, TIFF) converted to PDF.
Requirements
A VPS with at least 1 vCPU and 1 GB RAM (2 GB recommended for concurrent Chromium rendering). Ubuntu 22.04 or 24.04 with Docker installed. No domain is needed — you can call the API on http://127.0.0.1:3000 from your backend application on the same server, or expose it to your internal network only.
Deploy Gotenberg step by step
Create the compose file
SSH into your VPS and create a directory:
mkdir gotenberg && cd gotenbergCreate docker-compose.yml:
services:
gotenberg:
image: gotenberg/gotenberg:8
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000"Binding to 127.0.0.1 prevents direct access from the internet — the API is only reachable from your application on the same server or via a reverse proxy.
Start the container
Run docker compose up -d. Gotenberg pulls the image (~1.5 GB, includes Chromium and LibreOffice) and starts the HTTP server. Check the health endpoint:
curl http://127.0.0.1:3000/healthA {"status":"up"} response confirms the service is ready.
Generate your first PDF from HTML
Create a minimal HTML file (invoice.html) and convert it:
curl -s --request POST http://127.0.0.1:3000/forms/chromium/convert/html \
--form '[email protected]' \
-o invoice.pdfThe response is the PDF as a binary stream — pipe it to a file, a response object, or an S3 upload.
Convert a Word document to PDF
Upload a DOCX file to the LibreOffice route:
curl -s --request POST http://127.0.0.1:3000/forms/libreoffice/convert \
--form '[email protected]' \
-o contract.pdfGotenberg uses the embedded LibreOffice engine for conversion — no Microsoft Office licence required.
Add authentication (recommended)
Gotenberg has no built-in auth. The recommended approach: install nginx, create a reverse proxy from https://gotenberg.your-domain.com to http://127.0.0.1:3000, and add HTTP basic auth. Only your application's backend should call this endpoint — never expose it unauthenticated to the public internet, as it can be abused to render arbitrary URLs.
Integrate with your application
Gotenberg is language-agnostic — any HTTP client works. Libraries exist for PHP (gotenberg-php), Node.js (chromiumly), Python (gotenberg-client), Go and others. For Laravel, a first-party package wraps the API. In Node.js, you can call it with axios or the native fetch API by POSTing a FormData object with the HTML content or file.
