# Gotenberg — API-Driven Document Conversion and PDF Generation Server

> Docker-powered API server for converting HTML, Markdown, Office documents, and URLs into PDFs using Chromium and LibreOffice.

## Install

Save as a script file and run:

# Gotenberg — API-Driven Document Conversion and PDF Generation

## Quick Use
```bash
docker run -d -p 3000:3000 gotenberg/gotenberg:8
# Convert an HTML file to PDF
curl --request POST http://localhost:3000/forms/chromium/convert/html 
  --form files=@index.html -o result.pdf
# Convert a URL to PDF
curl --request POST http://localhost:3000/forms/chromium/convert/url 
  --form url=https://example.com -o page.pdf
```

## Introduction
Gotenberg is a Docker-based, stateless API server for converting documents to PDF. It wraps Chromium and LibreOffice behind a simple HTTP API, letting any application generate high-fidelity PDFs from HTML, Markdown, Office files, or live URLs without managing browser or office suite dependencies directly.

## What Gotenberg Does
- Converts HTML, Markdown, and URLs to PDF via a headless Chromium engine
- Transforms Office documents (DOCX, XLSX, PPTX, ODT) to PDF using LibreOffice
- Merges multiple PDFs into a single document with configurable page ordering
- Supports custom headers, footers, page size, margins, and landscape orientation
- Provides webhook-based async processing for long-running conversions

## Architecture Overview
Gotenberg is a Go application that orchestrates Chromium and LibreOffice as conversion engines inside a single Docker container. Incoming HTTP multipart requests are routed to the appropriate engine, which processes the document and returns a PDF stream. The server is stateless by design, making it straightforward to scale horizontally behind a load balancer. Health check endpoints support container orchestration.

## Self-Hosting & Configuration
- Run as a single Docker container with no external dependencies
- Configure via environment variables or CLI flags for API port, timeouts, and concurrency
- Set Chromium flags for custom rendering behavior like disabling JavaScript or sandbox mode
- Adjust LibreOffice listener pool size for Office document throughput
- Place behind a reverse proxy with rate limiting for production exposure

## Key Features
- Stateless design enables effortless horizontal scaling
- High-fidelity rendering using real Chromium and LibreOffice engines
- Multipart form API works from any language with HTTP support
- Webhook mode for asynchronous PDF delivery to callback URLs
- Built-in health and metrics endpoints for monitoring

## Comparison with Similar Tools
- **wkhtmltopdf** — Older HTML-to-PDF converter using QtWebKit; lacks modern CSS support and active maintenance
- **Puppeteer** — Node.js Chrome automation; requires custom server code and browser management
- **WeasyPrint** — Python HTML/CSS to PDF library; good for simple layouts but limited JavaScript support
- **Apache PDFBox** — Java library for PDF manipulation; lower-level and requires JVM integration
- **Prince XML** — High-quality HTML to PDF engine; commercial license required

## FAQ
**Q: What file formats can Gotenberg convert to PDF?**
A: HTML, Markdown, URLs (via Chromium), plus DOCX, XLSX, PPTX, ODT, ODS, ODP, and other LibreOffice-supported formats.

**Q: Can I customize the PDF output (headers, footers, margins)?**
A: Yes. The API accepts parameters for page size, margins, header/footer HTML templates, landscape mode, and print background graphics.

**Q: How do I handle large volumes of conversion requests?**
A: Run multiple Gotenberg containers behind a load balancer. Each instance is stateless, so scaling is a matter of adding replicas.

**Q: Does Gotenberg support authentication?**
A: Gotenberg itself does not enforce auth. Place it behind a reverse proxy or API gateway to add authentication and rate limiting.

## Sources
- https://github.com/gotenberg/gotenberg
- https://gotenberg.dev/docs/getting-started/introduction

---
Source: https://tokrepo.com/en/workflows/9144a5f4-3cb4-11f1-9bc6-00163e2b0d79
Author: Script Depot