Skip to main content
Version: 8.x

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 (with H2C support) server.

The following flags allow you to configure the API module:

FlagDescriptionDefault
--api-portSet the port on which the API should listen.3000
--api-port-from-envSet the environment variable with the port on which the API should listen - override the default port.None
--api-tls-cert-filePath to the TLS/SSL certificate file - for HTTPS support.None
--api-tls-key-filePath to the TLS/SSL key file - for HTTPS support.None
--api-start-timeoutSet the time limit for the API to start.30s
--api-timeoutSet the time limit for requests.30s
--api-root-pathSet the root path of the API - for service discovery via URL paths./
--api-trace-headerSet the header name to use for identifying requests.Gotenberg-Trace
--api-enable-basic-authEnable basic authentication - will look for the GOTENBERG_API_BASIC_AUTH_USERNAME and GOTENBERG_API_BASIC_AUTH_PASSWORD environment variables.false
--api-disable-health-check-loggingDisable health check logging.false

Chromium

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

A single Chromium browser manages the conversions in a stateful mode, enabling quicker single conversions. However, due to a lock mechanism, a Chromium browser cannot execute parallel operations.

During periods of heavy load, incoming requests will accumulate in the queue until they are processed, time out, or the queue reaches its maximum capacity. In the latter case, the request will be terminated prematurely.

To maintain performance under heavy load, consider increasing the number of Gotenberg instances.

caution

The amd64 Docker image uses Google Chrome stable, while other architectures use Chromium.

The armhf Docker image uses an earlier version of Chromium. See #709 for more details.

The following flags allow you to configure the Chromium module:

FlagDescriptionDefault
--chromium-restart-afterNumber of conversions after which Chromium will automatically restart. Set to 0 to disable this feature.0*
--chromium-max-queue-sizeMaximum request queue size for Chromium. Set to 0 to disable this feature.0
--chromium-auto-startAutomatically launch Chromium upon initialization if set to true; otherwise, Chromium will start at the time of the first conversion.false
--chromium-start-timeoutMaximum duration to wait for Chromium to start or restart.20s
--chromium-allow-file-access-from-filesAllow file:// URIs to read other file:// URIs.false
--chromium-allow-insecure-localhostIgnore TLS/SSL errors on localhost.false
--chromium-allow-listSet the allowed URLs for Chromium using a regular expression.All
--chromium-deny-listSet the denied URLs for Chromium using a regular expression.^file:(?!//\/tmp/).*
--chromium-ignore-certificate-errorsIgnore the certificate errors.false
--chromium-disable-web-securityDon't enforce the same-origin policy.false
--chromium-incognitoStart Chromium with incognito mode.false
--chromium-host-resolver-rulesSet custom mappings to the host resolver.None
--chromium-proxy-serverSet the outbound proxy server; this switch only affects HTTP and HTTPS requests.None
--chromium-clear-cacheClear Chromium cache between each conversion.false
--chromium-clear-cookiesClear Chromium cookies between each conversion.false
--chromium-disable-javascriptDisable JavaScript.false
--chromium-disable-routesDisable the routes.false

*Restarting Chromium currently results in memory leaks.

LibreOffice

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

A single LibreOffice instance manages the conversions in a stateful mode, enabling quicker single conversions. However, due to a lock mechanism, a LibreOffice instance cannot execute parallel operations.

During periods of heavy load, incoming requests will accumulate in the queue until they are processed, time out, or the queue reaches its maximum capacity. In the latter case, the request will be terminated prematurely.

To maintain performance under heavy load, consider increasing the number of Gotenberg instances.

The following flags allow you to configure the LibreOffice module:

FlagDescriptionDefault
--libreoffice-restart-afterNumber of conversions after which LibreOffice will automatically restart. Set to 0 to disable this feature.10
--libreoffice-max-queue-sizeMaximum request queue size for LibreOffice. Set to 0 to disable this feature.0
--libreoffice-auto-startAutomatically launch LibreOffice upon initialization if set to true; otherwise, LibreOffice will start at the time of the first conversion.false
--libreoffice-start-timeoutMaximum duration to wait for LibreOffice to start or restart.20s
--libreoffice-disable-routesDisable the routes.false

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

USER root

RUN apt-get update -qq &&\
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t bookworm-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:

EngineMergeConvert into PDF/ARead/Write metadataName
ExifToolexiftool
PDFtkpdtk
pdfcpupdcpu
QPDFqpdf
UNOlibreoffice-pdfengine

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

FlagDescriptionDefault
--pdfengines-enginesSet the PDF engines and their order.All
--pdfengines-disable-routesDisable the routes.false
info

For instance, the value "pdftk,libreoffice-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:

FlagDescriptionDefault
--webhook-allow-listSet the allowed URLs for the webhook feature using a regular expression.All
--webhook-deny-listSet the denied URLs for the webhook feature using a regular expression.None
--webhook-error-allow-listSet the allowed URLs in case of an error for the webhook feature using a regular expression.All
--webhook-error-deny-listSet the denied URLs in case of an error for the webhook feature using a regular expression.None
--webhook-max-retrySet the maximum number of retries for the webhook feature.4
--webhook-retry-min-waitSet the minimum duration to wait before trying to call the webhook again.1s
--webhook-retry-max-waitSet the maximum duration to wait before trying to call the webhook again.30s
--webhook-client-timeoutSet the time limit for requests to the webhook.30s
--webhook-disableDisable 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:

FlagDescriptionDefault
--prometheus-collect-intervalSet the interval for collecting modules' metrics.1s
--prometheus-namespaceSet the namespace of modules' metrics.gotenberg
--prometheus-disable-collectDisable the collect of metrics.false
--prometheus-disable-route-loggingDisable 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:

FlagDescriptionDefault
--log-formatSpecify the format of logging. Options include auto, json, or text.auto
--log-levelChoose the level of logging detail. Options include error, warn, info, or debug.info
--log-fields-prefixPrepend 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:

FlagDescriptionDefault
--gotenberg-graceful-shutdown-durationSet 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:8

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

USER root

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

USER gotenberg

Via .deb packages

FROM gotenberg/gotenberg:8

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

USER root

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

USER gotenberg