Product

Resources

Integrations

Pricing

Try for free

← blog posts

Scale PDF Generation from HTML using Gotenberg

Written by

Marcelo | Founder of pdf noodle

Last Updated

Dec 4, 2025

Tags

PDF Guide

Agnostic

What is Gotenberg?

Gotenberg is a powerful, open-source web API dedicated to converting various document formats into PDFs. Written in Go and currently at version 8, it excels at swiftly transforming HTML, URLs, and Markdown files into professional PDFs. Ideal for developers seeking scalable document conversion solutions, Gotenberg's Docker-based deployment simplifies the setup and maintenance processes, making it perfect for SaaS platforms.

You can check out their well-written and complete documentation here.

Setting Up Your Gotenberg Instance

Since Gotenberg is fully containerized, you have multiple deployment methods at your disposal—from local Docker setups to managed Kubernetes clusters and cloud-based serverless solutions. If you're unfamiliar with deploying containerized applications, this guide will walk you through each approach clearly and step by step.

Deploying Gotenberg using Docker Compose

Deploying Gotenberg with Docker Compose is straightforward. Ensure Docker is installed and running:

version: '3'
services:
  gotenberg:
    image: gotenberg/gotenberg:8
    ports:
      - "3000:3000"

Run docker-compose up -d to initiate your instance rapidly.

Deploying Gotenberg using Kubernetes

For resilience and scalability, Kubernetes deployment is ideal. Use this deployment YAML:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gotenberg
spec:
  replicas: 2
  selector:
    matchLabels:
      app: gotenberg
  template:
    metadata:
      labels:
        app: gotenberg
    spec:
      containers:
      - name: gotenberg
        image: gotenberg/gotenberg:8
        ports:
        - containerPort: 3000

Deploy with kubectl apply -f gotenberg.yaml.

Deploying Gotenberg using Google Cloud Run

For cost-effective serverless deployment, Google Cloud Run is a compelling choice. Utilize the specialized Docker image:

- gotenberg/gotenberg:8-cloudrun

- Alternatively, use the historical Docker image: thecodingmachine/gotenberg:8-cloudrun

Use the Google Cloud CLI:

gcloud run deploy {deployment_name} \
--memory=1Gi \
--image=gotenberg/gotenberg:8-cloudrun \
--args=gotenberg \
--args="--gotenberg-build-debug-data=false" \
--args="--api-port-from-env=PORT" \
--args="--log-enable-gcp-fields=true" \
--args="--webhook-disable=true" \
--args="--chromium-auto-start=true" \
--args="--libreoffice-auto-start=true"

Deploying Gotenberg using AWS Lambda (Recommended for Serverless Workloads)

Gotenberg provides an official Lambda-optimized container image, making AWS Lambda a lightweight and cost-efficient option for PDF generation. This approach is ideal if you want automatic scaling, pay-per-use pricing, and minimal infrastructure management.

Use the dedicated image:

Steps to deploy:

Push the image to Amazon ECR
Create an ECR repository, then build and push the image (optionally via a simple Dockerfile that pins Gotenberg’s version).
Create a Lambda function from the container image
- Minimum recommended memory: 1024 MB (more memory = better Chromium/LibreOffice performance).
- Timeout: 30–60 seconds, depending on document complexity.
Expose the Lambda via Function URL or API Gateway
- For internal traffic, use a Lambda Function URL with AWS_IAM authentication.
- For public or partner-facing tools, place API Gateway in front of Lambda to gain features like rate limiting, IP throttling, API keys, and custom domains.
Call Gotenberg via HTTP
The official Lambda image runs the AWS Lambda Web Adapter, so you interact with Gotenberg exactly as you would in a normal container—using standard endpoints such as:

Notes

Large PDF responses may exceed Lambda’s synchronous payload limits. For heavy workloads, Gotenberg supports webhooks, allowing the Lambda to deliver output directly to S3 or another endpoint.
If you prefer infrastructure-level scaling or long-running workloads, AWS ECS or Fargate remain excellent alternatives.

Generating PDF with Gotenberg

Generating PDF using an URL

Generate PDFs directly from URLs via simple HTTP requests:

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

Generating PDF from HTML

Convert HTML files into PDFs seamlessly:

<!-- example.html -->
<html>
  <head>
    <title>Gotenberg Test</title>
  </head>
  <body>
    <h1>Gotenberg PDF from HTML</h1>
  </body>
</html>

curl --request POST 'http://localhost:3000/forms/chromium/convert/html' \
--form 'files=@"example.html"' \
-o

Generating PDF from Markdown

Quickly convert Markdown files:

<!-- example.md -->

curl --request POST 'http://localhost:3000/forms/chromium/convert/markdown' \
--form 'files=@"example.md"' \
-o

Advanced PDF Configurations

Print options

Customize your PDF output extensively:

singlePage: false
paperWidth: 8.5
paperHeight: 11
marginTop: 0.39
marginBottom: 0.39
marginLeft: 0.39
marginRight: 0.39
preferCssPageSize: false
generateDocumentOutline: false
printBackground: false
omitBackground: false
landscape: false
scale: 1.0
nativePageRanges: All pages

Example request:

curl -X POST 'http://localhost:3000/forms/chromium/convert/url' \
-F 'url="https://example.com"' \
-F 'paperWidth="8.5"' -F 'paperHeight="11"' \
-F 'marginTop="0.39"' -F 'marginBottom="0.39"' \
-F 'marginLeft="0.39"' -F 'marginRight="0.39"' \
-F 'printBackground=false' -F 'landscape=false' -o

Generating PDF Header and Footer

Customize headers and footers with HTML strings, leveraging classes like pageNumber, totalPages, title, and date:

curl -X POST 'http://localhost:3000/forms/chromium/convert/html' \
-F 'files=@"example.html"' \
-F 'headerTemplate="<span class=\"title\">Header Text</span>"' \
-F 'footerTemplate="<span class=\"pageNumber\"></span>/<span class=\"totalPages\"></span>"' \
-o

Other PDF Functions

Gotenberg leverages LibreOffice to handle diverse PDF tasks, including merging, splitting, compression, and converting to archival PDF/A formats.

Merge example:

curl -X POST 'http://localhost:3000/forms/pdfengines/merge' \
-F 'files=@"file1.pdf"' -F 'files=@"file2.pdf"' \
-o

Alternative: Generate PDFs with pdf noodle

Managing HTML-to-PDF conversion at scale can quickly become a nightmare!

Especially in serverless environments where cold starts, memory limits, and headless browser quirks love to break at the worst possible time (we even wrote a full article about it). Add constant template iterations, version control headaches, and the need to support non-technical contributors, and suddenly your “simple PDF library” turns into an ongoing engineering project.

pdf noodle eliminates all of that.

Instead of maintaining brittle infrastructure or wrestling with outdated pdf libraries, pdf noodle gives you a battle-tested PDF generation API that just works!

Fast, scalable, and designed for both developers and non-developers. You send raw HTML or use our AI-powered template builder, and pdf noodle handles the rendering, scaling, optimization, and delivery so your team doesn’t have to.

Here's an example of a simple API request to generate your pixel-perfect PDF with just a few lines of code:

curl -X POST https://api.pdfnoodle.com/v1/html-to-pdf/sync \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{"html":"<html>your-html-here"}'

pdf noodle also includes a powerful AI Agent that can generate PDF templates instantly, along with a modern editor for refining the design, also using AI, to match your brand. You don't need developing or design experience to quickly update layouts, adjust styling, and manage template versions.

Here’s a quick demo showing how it works:

You can create your account and design your first template without any upfront payment.

Conclusion

Gotenberg offers an efficient, containerized approach to generating PDFs at scale, making it highly suitable for applications with predictable, consistent document formats. Its versatility in deployment and ease of integration into existing infrastructures make it a robust choice for SaaS developers.

If you don't want to waste time maintaining pdfs layouts and their infrastructure or if you don't want to keep track of best practices to generate PDFs at scale, third-party PDF APIs like pdf noodle will save you hours of work and deliver a high quality pdf layout.

Generating pdfs can be annoying!

Let us help you make it easier while you focus on what truly matters for your company.

Generate my first PDF

Generating pdfs can be annoying!

Let us help you make it easier while you focus on what truly matters for your company.

Generate my first PDF

Generating pdfs can be annoying!

Let us help you make it easier while you focus on what truly matters for your company.

Generate my first PDF

Title

Automate PDF Generation in minutes

No code or design experience needed

AI creates your template in seconds

Fine tune the design in our friendly builder

Generate PDFs with our API or integrations

Try for free

7-DAY FREE TRIAL

← blog posts

← blog posts

Scale PDF Generation from HTML using Gotenberg

Written by

Written by

Last Updated

Last Updated

Tags

Tags

PDF Guide

PDF Guide

Agnostic

Agnostic

What is Gotenberg?

Setting Up Your Gotenberg Instance

Deploying Gotenberg using Docker Compose

Deploying Gotenberg using Kubernetes

Deploying Gotenberg using Google Cloud Run

Deploying Gotenberg using AWS Lambda (Recommended for Serverless Workloads)

Steps to deploy:

Generating PDF with Gotenberg

Generating PDF using an URL

Generating PDF from HTML

Generating PDF from Markdown

Advanced PDF Configurations

Print options

Generating PDF Header and Footer

Other PDF Functions

Alternative: Generate PDFs with pdf noodle

Conclusion

Generating pdfs can be annoying!

Generating pdfs can be annoying!

Generating pdfs can be annoying!

Table of contents

Product

Resources

Compare

Integrations

Product

Resources

Compare

Integrations

Product

Resources

Compare

Integrations