pdforge

Product

Resources

Integrations

Pricing

Try for free

pdforge

pdf guide

Agnostic

Scale PDF Generation from HTML using Gotenberg

Marcelo | Founder of pdforge

Apr 14, 2025

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 ECS

AWS ECS offers scalable container orchestration for Gotenberg:

- Create a task definition in ECS with the Docker image gotenberg/gotenberg:8.

- Configure resources (minimum 1Gi memory recommended).

- Set up an ECS service for automated management and scaling.

- Use an Application Load Balancer for incoming requests.

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 Using pdforge

pdforge is a third-party pdf generation API. You can create beautiful reports with flexible layouts and complex components with an easy-to-use opinionated no-code builder. Let the AI do the heavy lifting by generating your templates, creating custom components or even filling all the variables for you.

You can handle high-volume PDF generation from a single backend call.

Here’s an example of how to generate pdf with pdforge via an API call:

curl -X POST https://api.pdforge.com/v1/pdf/sync \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{"templateId":"your-template","data":{"invoice_number":"your-invoice-number"}}'

You can create your account, experience our no-code builder and create your first layout template without any upfront payment clicking here.

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.

However, for teams seeking simplicity, dynamic templates, or those wanting to offload infrastructure maintenance, solutions like pdforge present compelling alternatives. By streamlining the complexities of dynamic document creation and handling scalable PDF generation effortlessly, pdforge helps SaaS companies prioritize innovation and productivity over operational concerns.