PDF Rendering Service (Gotenberg)

A shared, in‑house PDF rendering service for NHS applications, based on Gotenberg.

---

Purpose

This service provides a central, reusable capability for generating PDFs from HTML and other document formats, using a headless Chromium engine.

It is intended to:

• Avoid duplication of PDF rendering logic across teams
• Provide consistent, browser‑accurate PDF output
• Keep PDF generation within NHS‑managed infrastructure
• Reduce reliance on application‑embedded rendering libraries

---

Scope

This repository contains:

• Configuration and infrastructure for running the PDF rendering service
• Reference deployment examples for local and non‑production use

This repository does not contain:

• Application‑specific PDF templates or layouts
• Client SDKs or framework‑specific integrations
• Business logic or domain‑specific rendering rules

Applications interact with the service over HTTP.

---

Intended Usage

The service is designed to be consumed by multiple applications.

Typical usage patterns include:

• HTML‑to‑PDF generation
• Server‑side rendering of reports, letters, and documents
• Integration with application frameworks via HTTP‑based PDF drivers

Laravel applications commonly integrate via [Spatie’s laravel-pdf Gotenberg driver], but the service itself is framework‑agnostic.

---

Running locally

This service can be run locally using Docker Compose.

Prerequisites

• Docker Engine
• Docker Compose v2 (available via the docker compose command)

Start the service

From the root of the repository:

docker compose up

This will:

• Pull the gotenberg/gotenberg:8 image if required
• Start the Gotenberg service
• Attach the terminal to the service logs

By default, the service will be available at:

http://localhost:3000

Stop the service

To stop the service when running in the foreground:

Ctrl + C

Run in the background

To start the service in detached mode:

docker compose up -d

To view logs while running in the background:

docker compose logs -f

Stop and clean up

To stop the service and remove the container and network created by Compose:

docker compose down

This does not remove the Docker image.

---

Service interface

The service exposes a stateless HTTP API for document and PDF processing.

Applications interact with the service by sending HTTP requests to defined endpoints and receiving the resulting PDF (or ZIP archive) directly in the response.

Protocol

• HTTP/1.1 (HTTP/2 supported by Gotenberg)
• Requests are typically POST
• Payloads use multipart/form-data
• Responses return binary PDF (or ZIP) content

API style

The API is language‑agnostic and can be consumed by any application capable of making HTTP requests.

Client libraries are available for several languages (for example PHP and Python), but they are optional conveniences. All clients ultimately interact with the same underlying HTTP endpoints.

Example (URL to PDF)

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

Supported capabilities

At a high level, the service supports:

• HTML, URL, and Markdown to PDF (Chromium)
• Office document to PDF conversion (LibreOffice)
• PDF post‑processing (merge, split, metadata, PDF/A, etc.)

For full endpoint details and options, refer to the upstream Gotenberg documentation.