# Convert documents to PDF with Gotenberg

> Turn HTML, Markdown and Office documents into print-ready PDFs.

## 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:

```bash
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.