Configuration

The Docker image internally employs a binary that offers flags to configure its multiple modules. This guide contains a comprehensive list of flags that you can use to fine-tune Gotenberg according to your specific requirements.

API

The API module is an HTTP/1 and HTTP/2 (H2C) server.

The following flags allow you to configure the API module:

Flag	Description	Default
--api-port	Set the port on which the API should listen.	3000
--api-port-from-envt	Set the environment variable with the port on which the API should listen - override the default port.	None
--api-timeout	Set the time limit for requests.	30s
--api-root-path	Set the root path of the API - for service discovery via URL paths.	/
--api-trace-header	Set the header name to use for identifying requests.	Gotenberg-Trace
--api-disable-health-check-logging	Disable health check logging.	false

Chromium

The Chromium module interacts with the Chromium browser to convert HTML documents to PDF.

The following flags allow you to configure the Chromium module:

Flag	Description	Default
--chromium-allow-file-access-from-files	Allow file:// URIs to read other file:// URIs.	false
--chromium-allow-insecure-localhost	Ignore TLS/SSL errors on localhost.	false
--chromium-allow-list	Set the allowed URLs for Chromium using a regular expression.	All
--chromium-deny-list	Set the denied URLs for Chromium using a regular expression.	^file:///[^tmp].*
--chromium-ignore-certificate-errors	Ignore the certificate errors.	false
--chromium-disable-web-security	Don't enforce the same-origin policy.	false
--chromium-incognito	Start Chromium with incognito mode.	false
--chromium-failed-starts-threshold	Set the number of consecutive failed starts after which the module is considered unhealthy.	5
--chromium-host-resolver-rules	Set custom mappings to the host resolver.	None
--chromium-proxy-server	Set the outbound proxy server; this switch only affects HTTP and HTTPS requests.	None
--chromium-disable-javascript	Disable JavaScript.	false
--chromium-disable-routes	Disable the routes.	false

info

It starts a dedicated Chromium instance for each conversion.

info

If --chromium-failed-starts-threshold=0, there is no health check for this module.

caution

The amd64 Docker image uses Google Chrome stable, while other architectures use an earlier version of Chromium.

LibreOffice

The LibreOffice module interacts with LibreOffice to convert numerous documents to PDF, thanks to unoconv.

The following flags allow you to configure the LibreOffice module:

Flag	Description	Default
--libreoffice-disable-routes	Disable the route.	false
--uno-listener-start-timeout	Time limit for starting the LibreOffice listener.	10s
--uno-listener-restart-threshold	Conversions limit after which the LibreOffice listener is restarted.	10

Stateful or Stateless

By default, a long-running LibreOffice listener handles the conversions. This stateful mode allows for faster unitary conversion, but there is a lock mechanism as a single LibreOffice listener cannot perform parallel operations.

In other words, under heavy load, you should consider scaling up your number of Gotenberg instances or switch the LibreOffice module to a stateless mode with --uno-listener-restart-threshold=0 (i.e., a dedicated LibreOffice listener per conversion).

info

Gotenberg restarts the long-running LibreOffice listener if it is unhealthy before and after a conversion.

info

If --uno-listener-restart-threshold=0 (i.e., stateless mode), there is no health check for this module.

caution

The --uno-* properties also impact the performance of the UNO PDF engine (see PDF Engines).

Switch Language

By default, LibreOffice uses the English language when it converts documents to PDF. You may override this behavior by building your own Docker image.

For instance, with the German language:

FROM gotenberg/gotenberg:7

USER root

RUN apt-get update -qq &&\
    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t bullseye-backports libreoffice-l10n-de &&\
    sed -i '/de_DE.UTF-8/s/^# //g' /etc/locale.gen &&\
    locale-gen &&\
    # Cleanup.
    # Note: the Debian image does automatically a clean after each install thanks to a hook.
    # Therefore, there is no need for apt-get clean.
    # See https://stackoverflow.com/a/24417119/3248473.
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

ENV LANG de_DE.UTF-8
ENV LANGUAGE de_DE:de
ENV LC_ALL de_DE.UTF-8

USER gotenberg

PDF Engines

The PDF Engines module gathers all engines that can manipulate PDF files. It calls each engine until one successfully handles a task. A PDF engine is an external tool that Gotenberg leverages to perform a specific task, such as merging PDF files.

Currently, Gotenberg supports the following PDF engines:

Engine	Merge	Convert into PDF/A	Name
PDFtk	✅	❌	pdtk
PDFcpu	✅	❌	pdcpu
QPDF	✅	❌	qpdf
UNO	❌	✅	uno-pdfengine

The following flags allow you to configure the PDF Engines module:

Flag	Description	Default
--pdfengines-engines	Set the PDF engines and their order.	All
--pdfengines-disable-routes	Disable the routes.	false

info

For instance, the value "pdftk,uno-pdfengine" selects PDFtk as the first engine, and UNO as the second.

Webhook

The webhook feature enables Gotenberg to upload the output file originating from multipart/form-data routes to a selected destination.

The following flags allow you to configure the Webhook module:

Flag	Description	Default
--webhook-allow-list	Set the allowed URLs for the webhook feature using a regular expression.	All
--webhook-deny-list	Set the denied URLs for the webhook feature using a regular expression.	None
--webhook-error-allow-list	Set the allowed URLs in case of an error for the webhook feature using a regular expression.	All
--webhook-error-deny-list	Set the denied URLs in case of an error for the webhook feature using a regular expression.	None
--webhook-max-retry	Set the maximum number of retries for the webhook feature.	4
--webhook-retry-min-wait	Set the minimum duration to wait before trying to call the webhook again.	1s
--webhook-retry-max-wait	Set the maximum duration to wait before trying to call the webhook again.	30s
--webhook-client-timeout	Set the time limit for requests to the webhook.	30s
--webhook-disable	Disable the webhook feature.	false

Prometheus

The Prometheus module collects metrics from other modules and exposes an HTTP endpoint that can be scraped by Prometheus.

The following flags allow you to configure the Prometheus module:

Flag	Description	Default
--prometheus-collect-interval	Set the interval for collecting modules' metrics.	1s
--prometheus-namespace	Set the namespace of modules' metrics.	gotenberg
--prometheus-disable-collect	Disable the collect of metrics.	false
--prometheus-disable-route-logging	Disable the route logging.	false

Logging

Gotenberg employs a logger that generates structured logs. Structured logs are formatted in a standardized, machine-readable way, making them extremely beneficial for centralized log management.

The following flags allow you to configure the logger:

Flag	Description	Default
--log-format	Specify the format of logging. Options include auto, json, or text.	auto
--log-level	Choose the level of logging detail. Options include error, warn, info, or debug.	info
--log-fields-prefix	Prepend a specified prefix to each field in the logs.	None

Graceful Shutdown

To ensure running tasks have sufficient time to complete, Gotenberg waits for a specific duration before initiating the shutdown process. It may stop earlier if all tasks have completed.

The following flag allows you to configure this duration:

Flag	Description	Default
--gotenberg-graceful-shutdown-duration	Set the graceful shutdown duration.	30s

Docker Image

Fonts

The default Docker image is pre-packaged with an extensive assortment of fonts, including Asian ones. If your application requires additional or specific fonts not included in this collection, you'll need to construct a tailored Docker image to incorporate those fonts.

Via .tff files

FROM gotenberg/gotenberg:7

USER root

COPY /local/path/to/{font}.ttf /usr/local/share/fonts/{font}.ttf

USER gotenberg

Or, if you have many fonts:

FROM gotenberg/gotenberg:7

USER root

COPY /local/path/to/fonts/* /usr/local/share/fonts/

USER gotenberg

---

Via .deb packages

FROM gotenberg/gotenberg:7

USER root

RUN DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends my-fonts-package

USER gotenberg

---

info

You could also mount a volume containing your fonts to /usr/local/share/fonts/ as suggested in this comment.

Ownership

The Docker image employs a specific non-root user, named gotenberg, with a User ID (uid) and Group ID (gid) of 1001. If you want to change these identifiers, you will have to build a custom Docker image:

FROM gotenberg/gotenberg:7

USER root

RUN usermod -u {uid} -g {gid} gotenberg

USER gotenberg