Convert documents to PDF with Gotenberg

4 min read Updated 1 day ago

Convert documents to PDF with Gotenberg

Gotenberg is a Docker-powered API for converting documents to PDF. It takes HTML, Markdown and Office documents, renders them, and returns a print-ready PDF, all through a simple HTTP call. It is stateless, which means it does not keep anything between requests: you send it a document, it hands you back a PDF, and nothing is stored.

It is a good fit when your application needs to produce documents on demand:

  • Invoice generation. Render a template with your customer's details and convert it to a PDF to attach to an email or let them download.
  • Report creation. Turn dashboards, analytics or summaries written as HTML or Markdown into a shareable file.
  • Document conversion. Convert Office documents, like a spreadsheet or a presentation, into a plain PDF anyone can open.
  • Print-ready PDFs. Get consistent pagination and styling for anything you want to look the same on screen and on paper.

Adding it

  1. Open your application and add a service from the Custom services card.
  2. Pick Gotenberg.
  3. Choose how much memory it gets. Converting a document is a short burst of work, so the smallest size is usually plenty unless you are converting large files back to back.
  4. Pick a version. 8 is the default and is what we recommend; 7 is available if a tool your application uses expects the older API.
  5. Review and save. A deployment starts the service, and once it is healthy it is ready to accept requests.

The variables it adds

Once the service is running, your application gets three environment variables to point at it:

  • GOTENBERG_URL is the full address, like http://gotenberg:3000, and is what you use for API calls.
  • GOTENBERG_HOST is the hostname on its own.
  • GOTENBERG_PORT is the port, 3000.

Point whatever client or HTTP call your application uses at GOTENBERG_URL. It listens on HTTP, so a plain request library is all you need.

Calling it

Gotenberg exposes a set of HTTP endpoints, one per conversion type. The most common one converts HTML to PDF. Here is a curl example that posts a local index.html file and writes the result to a PDF:

curl --request POST \
  --url "$GOTENBERG_URL/forms/chromium/convert/html" \
  --header 'Content-Type: multipart/form-data' \
  --form 'files=@index.html' \
  --output result.pdf

The HTML is sent as a multipart form, Gotenberg renders it in a headless browser, and the PDF comes back in the response. Other endpoints follow the same shape for other formats, for example converting Markdown or Office documents.

Configuration

Gotenberg does not need much to work out of the box, but a few settings are worth knowing about. They live under Service configuration when you are in the edit modal, with LOG_LEVEL, DEFAULT_WAIT_TIMEOUT and DEFAULT_WAIT_DELAY in Advanced settings.

  • LOG_LEVEL controls how much the service writes to its logs. The default is info. Use error to keep logs minimal, or debug when you are trying to work out why a conversion is failing. The accepted values are error, warn, info and debug.
  • DEFAULT_WAIT_TIMEOUT is how many seconds Gotenberg waits for a page to settle before giving up and rendering what it has. The default is 30. Raise it for pages heavy on JavaScript that take a while to finish loading.
  • DEFAULT_WAIT_DELAY is how long Gotenberg waits after a page has loaded before rendering it. The default is 1s. A short delay lets fonts and images finish drawing in, so increase it if your PDF usually comes back missing the last bits of styling.

Saving your changes

In the edit modal, the button that applies changes is Update resources (creating the service the first time uses Create service). Saving restarts the service, so anything it is handling at that moment, such as a conversion in flight, is dropped. Roll changes out during a quiet moment.