Gotenberg PDF: setup and automation guide for 2026

Gotenberg is an open source, Docker-based API for converting HTML, URLs, Markdown, and Office documents into PDFs. It runs as a stateless service — send it a file or URL, get back a PDF. No browser automation scripts, no headless Chrome configuration, no wkhtmltopdf dependency hell.

The reason Gotenberg has become the default choice for programmatic PDF generation is simplicity. One Docker container handles Chromium rendering, LibreOffice conversion, and PDF merging through a clean HTTP API. According to the Gotenberg GitHub repository, the project has over 7,500 stars and averages 2 million+ Docker pulls per month as of early 2026. A 2025 StackOverflow developer survey found that 34% of developers generating PDFs programmatically use a containerized conversion service — up from 19% in 2023.

Unlike generic AI automation posts, this guide shows real CodeWords workflows — not just theory. You will set up Gotenberg and build automated PDF pipelines that handle templates, batch processing, and dynamic content.

Related reading: workflow automation platform, automation tools, AI automation tools, self-hosted AI starter kit, CodeWords integrations, pricing, and CodeWords templates.

TL;DR

• Gotenberg converts HTML, URLs, and Office files to PDFs via a simple HTTP API running in a Docker container.
• The API supports page size, margins, headers, footers, wait delays, and PDF metadata — enough for invoices, reports, contracts, and any templated document.
• CodeWords can call Gotenberg as part of a serverless workflow: generate dynamic HTML from data, send it to Gotenberg, and distribute the resulting PDF via email, Slack, or Google Drive.

How do you set up Gotenberg?

The setup is minimal. If you have Docker, you are five minutes from a running PDF service.

Step 1: Pull and run the container.

docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8

This starts Gotenberg on port 3000. The service is ready when http://localhost:3000/health returns 200 OK.

Step 2: Test with a URL-to-PDF conversion.

curl --request POST http://localhost:3000/forms/chromium/convert/url \
  --form url=https://example.com \
  -o example.pdf

If example.pdf appears and opens correctly, Gotenberg is working. The Chromium route handles URL and HTML conversion. The LibreOffice route handles Office documents.

Step 3: Test HTML-to-PDF conversion.

Create an index.html file with your content:

curl --request POST http://localhost:3000/forms/chromium/convert/html \
  --form files=@index.html \
  -o output.pdf

Gotenberg renders the HTML using Chromium, applies default or custom page settings, and returns the PDF.

What are the key API endpoints?

Gotenberg organizes its API around conversion engines and input types.

Chromium routes (HTML, URL, Markdown → PDF):

• /forms/chromium/convert/url — Convert a web page to PDF
• /forms/chromium/convert/html — Convert an HTML file to PDF
• /forms/chromium/convert/markdown — Convert Markdown to PDF

LibreOffice routes (Office docs → PDF):

• /forms/libreoffice/convert — Convert .docx, .xlsx, .pptx, .odt, and other Office formats to PDF

PDF routes (merge, convert):

• /forms/pdfengines/merge — Merge multiple PDFs into one
• /forms/pdfengines/convert — Convert PDF to PDF/A format

Each route accepts multipart form data with optional parameters for page size, margins, orientation, scale, headers, footers, and rendering wait time.

How do you customize PDF output?

Gotenberg's customization parameters handle most production PDF requirements.

Page size and margins:

curl --request POST http://localhost:3000/forms/chromium/convert/html \
  --form files=@index.html \
  --form paperWidth=8.5 \
  --form paperHeight=11 \
  --form marginTop=0.5 \
  --form marginBottom=0.5 \
  --form marginLeft=0.75 \
  --form marginRight=0.75 \
  -o output.pdf

Headers and footers: Create separate HTML files for the header and footer content, then pass them as form fields:

curl --request POST http://localhost:3000/forms/chromium/convert/html \
  --form files=@index.html \
  --form files=@header.html \
  --form files=@footer.html \
  -o output.pdf

Header and footer templates can include dynamic variables: date, title, pageNumber, and totalPages using Chromium's built-in template syntax.

Wait delay: For pages with JavaScript-rendered content, add a wait time so Chromium finishes rendering before capturing:

--form waitDelay=3s

Landscape orientation:

--form landscape=true

How do you build an automated PDF pipeline?

The real value of Gotenberg is not one-off conversions. It is automated pipelines that generate PDFs from dynamic data at scale.

Pattern 1: Invoice generation.

1. Fetch order data from your database or CRM
2. Render an HTML invoice template with the order data (using Jinja2, Handlebars, or any template engine)
3. Send the rendered HTML to Gotenberg
4. Email the resulting PDF to the customer and archive it in Google Drive

Pattern 2: Report generation.

1. Query analytics data from your dashboard or data warehouse
2. Generate HTML charts and tables from the data
3. Send the compiled report HTML to Gotenberg
4. Distribute the PDF via Slack, email, or a shared drive on a schedule

Pattern 3: Contract and proposal generation.

1. Pull deal details from Pipedrive, HubSpot, or Salesforce
2. Merge deal data into a contract template
3. Generate the PDF through Gotenberg
4. Send for e-signature via DocuSign or post to the CRM as an attachment

In CodeWords, a PDF pipeline looks like this:

Build an invoice PDF pipeline.
Trigger when a new order is marked as paid in the Google Sheet.
Read order data: customer name, items, quantities, prices, tax.
Render the HTML invoice template with the order data.
Send the HTML to Gotenberg to generate a PDF.
Email the PDF to the customer using Gmail.
Upload a copy to the customer's folder in Google Drive.
Log the invoice number and send date to the Google Sheet.

Cody builds this as a serverless workflow that calls your Gotenberg instance as an HTTP step within the pipeline. The template rendering, Gotenberg API call, email, and Drive upload all happen in sequence with error handling at each stage.

How do you handle batch PDF processing?

Batch processing is common for monthly reports, bulk invoices, and certificate generation. Two approaches work well.

Sequential processing with rate limiting. Process one document at a time with a short delay between requests. Gotenberg handles concurrent requests, but Chromium rendering is memory-intensive. On a standard Docker setup (2GB RAM), limit concurrent conversions to 3–5.

Parallel processing with a queue. For high volume (100+ PDFs), queue conversion jobs and process them in parallel with a concurrency limit. CodeWords workflows can handle this by iterating over data rows and sending each to Gotenberg, with built-in retry logic for failures.

Resource tuning for batch workloads. Gotenberg's Docker container defaults work for light usage. For batch processing, increase memory allocation:

docker run -d --name gotenberg -p 3000:3000 \
  --memory=4g \
  gotenberg/gotenberg:8 \
  --api-timeout=120s \
  --chromium-max-queue-size=20

The --api-timeout flag prevents long-running conversions from blocking the queue. The --chromium-max-queue-size controls how many conversions can wait before the server rejects new requests.

What about template management?

Good PDF pipelines separate data from presentation. Use a template engine to maintain reusable HTML templates with placeholder variables.

Jinja2 (Python): The most common choice for server-side rendering. Define an HTML template with {{ variable }} placeholders, render with data, and send to Gotenberg.

Handlebars (JavaScript): Similar approach for Node.js environments. Partials and helpers make complex templates manageable.

CSS for print: Gotenberg renders CSS fully, including @media print rules, CSS Grid, Flexbox, and web fonts. Design your templates with print-specific styles: forced page breaks (page-break-before: always), hidden navigation elements, and optimized font sizes.

Store templates in version control alongside your workflow code. When a template changes, all future PDFs reflect the update without modifying the pipeline logic.

FAQ

Is Gotenberg free?

Yes. Gotenberg is open source under the MIT license. You pay only for the infrastructure to run the Docker container — a basic VPS ($5–20/month) handles moderate volume. The project also offers Gotenberg Cloud as a managed service.

How does Gotenberg compare to wkhtmltopdf?

Gotenberg uses Chromium for rendering, which supports modern CSS (Grid, Flexbox, variables, web fonts) and JavaScript. wkhtmltopdf uses an older WebKit engine with limited CSS support. Gotenberg also runs as a containerized API, while wkhtmltopdf is a CLI tool that requires system-level installation. For new projects, Gotenberg is the stronger choice.

Can Gotenberg handle password-protected PDFs?

Gotenberg does not natively add password protection. Generate the PDF with Gotenberg, then use a tool like qpdf or a Python library (pikepdf, PyPDF2) to encrypt the output before distribution.

What is the maximum file size Gotenberg can handle?

There is no hard file size limit — it depends on your Docker container's memory allocation. Complex HTML with large images or many pages may require 2–4GB of container memory. Monitor memory usage and adjust --memory accordingly.

Where does automated PDF generation lead?

PDF generation sounds like a solved problem until you realize how much manual work still goes into assembling, formatting, and distributing documents. Invoices, reports, proposals, certificates, compliance documents — every business generates them, and most do it with manual exports or brittle scripts.

The shift is from "generate a PDF" to "documents assemble themselves from data." When your invoice pipeline runs on every order, your report pipeline runs on a schedule, and your proposal pipeline triggers from a CRM stage change, documents stop being a task and start being a byproduct of operations.

Set up Gotenberg on your server and build the first pipeline in CodeWords. Start with one template, one data source, and one distribution channel — then scale from there.