Gotenberg

Gotenberg is a container‑native microservice that exposes an HTTP API for converting a wide range of document formats into PDF, merging PDFs, and applying advanced rendering options. Internally it orchestrates Chromium for HTML/Markdown/Web pages, LibreOffice for Office files (DOCX, XLSX, PPTX), and a lightweight PDF engine for operations such as merging or adding watermarks. The service is written in Go (v1.22+), leveraging Go’s concurrency model to handle multiple conversion jobs in parallel while keeping memory usage predictable.

Architecture & Technical Stack

• Language & Runtime: Go 1.22, compiled to a single static binary. The API is built on the net/http package with a custom router that supports multipart/form‑data uploads and JSON payloads.
• Containerization: A multi‑stage Docker build exposes port 3000. The image pulls the latest Chromium and LibreOffice binaries during the build, ensuring no runtime dependencies on the host.
• Concurrency: Each conversion request is processed in its own goroutine, with a configurable worker pool to limit resource contention. The service uses context cancellation to abort long‑running jobs.
• File Handling: Temporary files are stored in a dedicated /tmp directory inside the container, automatically cleaned up after the job completes or fails.
• Extensibility: The API is RESTful, with endpoints such as /forms/chromium/convert/url and /forms/libreoffice/convert. Each endpoint accepts form fields that map directly to Chromium or LibreOffice command‑line flags, allowing developers to fine‑tune rendering (e.g., landscape, marginTop, pdfa).

Core Capabilities

• Format Support: HTML, Markdown, plain text, Office Open XML (DOCX, XLSX, PPTX), PDFs, and more.
• Chromium Features: Headless rendering of web pages, PDF generation from URLs or raw HTML, custom viewport settings, and CSS media queries.
• LibreOffice Features: Batch conversion of Office files, merging multiple documents into a single PDF, and optional PDF/A compliance.
• PDF Engine: Merge PDFs, add bookmarks or watermarks, and split documents.
• Asynchronous Workflow: Optional webhook integration (Gotenberg-Webhook-URL) to receive the resulting PDF once processing is finished, supporting custom headers and HTTP methods.
• Security: Runs in a non‑root container by default, isolates file system access to /tmp, and validates incoming multipart data for size limits.

Deployment & Infrastructure

• Self‑Hosting: A single Docker container is sufficient. For production, run behind a reverse proxy (NGINX, Traefik) and expose HTTPS.
• Scalability: Horizontal scaling is trivial—spin up multiple Gotenberg containers behind a load balancer. The stateless nature of the API means any container can process any job.
• Resource Requirements: A modest CPU (2 cores) and 4 GB RAM are typical for moderate workloads; high‑volume environments may need more memory to accommodate multiple Chromium instances.
• Monitoring: The service emits Prometheus metrics (/metrics) and logs in JSON format, making it easy to integrate with ELK or Loki stacks.

Integration & Extensibility

• SDKs: Official client libraries are available for Go, JavaScript (Node.js), and Python, simplifying HTTP interactions.
• Webhooks: Developers can configure a callback URL that receives the PDF via POST or PUT, with optional custom headers (Gotenberg-Webhook-Extra-Http-Headers) for authentication or routing.
• Custom Flags: Any Chromium or LibreOffice CLI flag can be passed through the form data, enabling advanced use cases like disabling JavaScript, setting custom timeouts, or specifying user agents.
• Plugins: While the core service is monolithic, its modular design allows for future plugin extensions (e.g., custom PDF watermarking or OCR) to be added as separate microservices that communicate over HTTP.

Developer Experience

• Documentation: Comprehensive, example‑driven docs on gotenberg.dev with curl snippets, Go SDK usage, and detailed flag explanations.
• Community: Active GitHub repository with CI/CD pipelines, issue tracking, and a responsive maintainers team. The project is MIT‑licensed, encouraging commercial use without licensing constraints.
• Testing: End‑to‑end tests run against the Docker image, ensuring backward compatibility across releases.

Use Cases

1. Web Applications: Generate PDFs from user‑submitted HTML or Markdown in a Node.js backend.
2. Enterprise Document Management: Convert bulk Office files to PDF/A for archival, triggered via a webhook that uploads the result to an S3 bucket.
3. Reporting Services: Merge multiple PDF reports into a single document before emailing to stakeholders.
4. Content Platforms: Render dynamic web pages to PDFs for offline consumption, using custom headers and authentication tokens.

Advantages Over Alternatives