How Gotenberg works
Gotenberg is an HTTP API in a Docker container. You post files and form fields; it answers with a PDF, an image, a ZIP of several files, or JSON.
What runs inside
- Chromium prints web pages: a URL, an HTML file with its assets, or Markdown. It also takes screenshots.
- LibreOffice converts office documents: Word, Excel, PowerPoint, OpenDocument and over a hundred more formats. Gotenberg drives it through lok, a small program built on LibreOfficeKit.
- litho, Gotenberg's PDF engine, written in Go, does everything to PDFs: merge, split, stamp, sign, encrypt, make PDF/A, PDF/UA or both, and validate.
Every image variant includes litho. The -chromium and -libreoffice variants leave out the other engine: see Install.
The routes
- Conversion routes turn what you send into PDF:
/forms/chromium/convert/*and/forms/libreoffice/convert. The screenshot routes,/forms/chromium/screenshot/*, make images instead. - PDF routes work on PDFs you upload:
/forms/pdf/piperuns a list of stages, and each stage has a route of its own, such as/forms/pdf/merge. - Read routes answer JSON about PDFs:
/forms/pdf/info,/forms/pdf/metadata,/forms/pdf/validate, and so on.
Routes lists them all, and shows what works where.
Stages
A stage is one operation on a PDF: merge, stamp, redact, sign, make PDF/A. A request lists them in its stages field, and Gotenberg runs them in order:
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@report.docx \
--form files=@annex.docx \
--form 'stages=[
{ "op": "merge" },
{ "op": "remediate", "profile": "PDF/A-2b" }
]' \
-o documents.pdf
The conversion routes and /forms/pdf/pipe take stages. A few rules keep a list sensible, such as signing last: see Order rules.
Native field or stage
Some results have two ways in. A field whose name starts with native asks Chromium or LibreOffice to do it while they make the PDF. A stage does it afterwards, with litho, on any route:
| Result | Native field | Stage | Pick the stage when |
|---|---|---|---|
| PDF/A | nativePdfa: LibreOffice, four levels, unchecked | remediate: any route, eleven levels, reports what's left | Usually: it checks its result |
| PDF/UA | nativePdfua: LibreOffice, PDF/UA-1, unchecked | remediate: PDF/UA-1 or PDF/UA-2, tags the PDF if needed | Always, to claim conformance |
| Tags | nativeTaggedPdf: from your source's structure | autotag: inferred from the page layout | The PDF comes from elsewhere |
| Bookmarks | nativeBookmarks: from the headings | set-bookmarks: the list you give | You want your own titles, or after a merge |
| Pages | nativePages: the engine skips the others, which is faster | select: also odd, even, last, exclusions such as !1, and a new order | You reorder, or pick after a merge |
| Watermark | nativeWatermarkText: LibreOffice, any script, sized to the page | stamp-text: any route, at an exact position, any script the image has a font for | The PDF comes from Chromium or elsewhere |
| Image size | nativeQuality: LibreOffice, lowers the quality | optimize: keeps the quality, packs the file | You can't lose quality |
What comes back
- One file answers as itself, and several as a ZIP.
- A PDF from a URL or HTML takes a random name, an office document
report.docx.pdf, a merge the name of its first file. The parts of asplitcount from 0,report_0.pdf, and rendered pages from 1,report_1.png. Gotenberg-Output-Filenamenames the result instead.- With webhook headers, Gotenberg answers right away and uploads the result: see Deliver with webhooks.
What Gotenberg checks
remediatereports the violations it couldn't fix inGotenberg-Remediation-Residual, and still answers 200: check the header.- Nothing checks what the
nativefields produce./forms/pdf/validatechecks any PDF against PDF/A, PDF/UA or Factur-X. - A stage that rewrites the file refuses a signed PDF, since rewriting it would drop the signature: see which stages rewrite.
How a request flows
- Gotenberg reads the form: uploaded files, ZIP archives, and files to download from URLs.
- A conversion route hands the files to Chromium or LibreOffice. A PDF route skips this step.
- Gotenberg runs the stages, in order.
- It answers with the result, or uploads it to your webhook.
Gotenberg keeps nothing between requests. It deletes a request's files once it answers, so you can run as many containers as you need behind a load balancer.
Keep it private
Gotenberg loads the URLs and opens the documents callers send it. Keep it behind your firewall: Secure your deployment covers the rest.
Open source
Gotenberg is open source, under the MIT license, on GitHub. Its sponsors, listed at the bottom of every docs page, fund its development.