PdfTurtle

PdfTurtle is an open-source, self-hosted HTML-to-PDF tool that renders PDF reports and documents from HTML templates or raw HTML using a Chromium engine. It runs as a stateless Go microservice, accepts a ZIP bundle of templates and assets plus a JSON model, and returns a rendered PDF file.

What is PdfTurtle?

PdfTurtle is a self-hostable HTML-to-PDF rendering service written in Go. It takes HTML templates (or raw HTML) and a JSON model as input, and outputs a PDF rendered by the latest Chromium engine via the chromedp driver. The project is maintained by Lucas Gaitzsch and distributed as a Docker image on Docker Hub, with a web-based Playground available at pdfturtle.gaitzsch.dev for interactive template design.

Key Features

• Free, open source, self-hosted — no per-document fees; you deploy the container to your own infrastructure.
• HTML and CSS with JavaScript — uses the current Chromium engine via chromedp, so templates support modern web standards.
• Built-in template engines — golang (html/template), django (pongo2), and handlebars (raymond) with a choice of key per request.
• ZIP bundle workflow — package index.html, header.html, footer.html, assets and options.json into one ZIP and send it with a JSON model.
• Bundled fonts — ships with Open Sans, Roboto, and Noto Emoji for consistent PDF typography.
• Playground frontend — a web UI with model, body, header, footer and assets tabs for rapid template development.
• Container image — available on Docker Hub, with a -playground tag that includes the web UI.
• Configurable runtime — render timeout (default 30s), worker instances (default 30), max body size (default 32MB), and optional bearer token secret.

Who is it for?

• Backend developers building applications that generate PDFs on demand — they can call the REST API with a bundle and model and get a PDF file back.
• Frontend developers who need to turn HTML/CSS designs into printable documents — they can design and preview templates in the Playground before integrating.
• DevOps teams that want a self-hosted document service — they can deploy the Docker container, configure worker instances and timeouts, and scale replicas behind a load balancer.
• Teams using multiple template syntaxes — the service supports Go, Django-like, and Handlebars templates in the same deployment.

What can you do with PdfTurtle?

• Generate PDFs from HTML templates: send a ZIP bundle containing your template and assets plus a JSON model, and receive a rendered PDF.
• Split reusable bundles: put a common header.html in one bundle and combine it with another bundle's body, so shared headers stay DRY.
• Include barcodes and JSON in templates: template functions like barcodeQr, barcodeEan, and marshal let templates render QR/EAN codes or embed JSON strings.
• Design templates visually: use the Playground to iterate on the model, body, header and footer, then download the bundle for your project.

How does PdfTurtle work?

1. Design your PDF in the Playground: paste an example JSON model, create body/header/footer HTML, add assets, and set options.
2. Download the result as a ZIP bundle and place it in your project's resources.
3. Send the bundle plus your real JSON model to a PdfTurtle instance (via a client library or Swagger-generated client) and get back a rendered PDF.

FAQ

Is PdfTurtle free?

Yes. PdfTurtle is free and open source. You self-host the Docker image, so there are no per-document costs or subscription tiers. A public demo Playground is available at pdfturtle.gaitzsch.dev.

What template engines does PdfTurtle support?

PdfTurtle includes three template engines: Go's html/template, a Django-syntax engine (pongo2), and a Handlebars-syntax engine (raymond). You select the engine by key when calling the service.

How do I run PdfTurtle with Docker?

Pull lucasgaitzsch/pdf-turtle and run it with port 8000 exposed, for example docker run -d -p 8000:8000 lucasgaitzsch/pdf-turtle. For the bundled Playground UI, use the -playground tag.

What are the default limits?

The default render timeout is 30 seconds, the max body size is 32 MB, and the service starts 30 worker instances. All are configurable via command-line arguments or environment variables.

Is there a client library for my language?

Official client libraries exist for .NET Standard 2.0 and Go. For other languages, you can generate a client from the Swagger/OpenAPI description at /swagger/doc.json.