Skip to main content
Version: 8.x

Installation

This guide is not intended to provide a comprehensive tour of Docker and its orchestrators. Rather, it's designed to be concise enough to assist beginners in getting started while helping power users sidestep potential pitfalls.

danger

We do not recommend exposing your instances to the external world. In terms of security, you should consider Gotenberg as a database.

Live Demo 🔥​

Before downloading the Docker image, you might want to experiment with Gotenberg. We offer a demo API for this purpose:

As you navigate through the documentation, feel free to open a terminal or Postman and try out the routes using the demo URL.

For instance:

curl \
--request POST https://demo.gotenberg.dev/forms/chromium/convert/url \
--form url=https://sparksuite.github.io/simple-html-invoice-template/ \
-o my.pdf
info

The demo operates on a Render instance with 512MB of RAM and 0.5 CPU.

At present, the restrictions are:

  • A maximum of two requests per second per IP.
  • A body limit of 5MB.

Docker​

To start a default Docker container of Gotenberg, run:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Alternatively, using the historic Docker repository from our sponsor TheCodingMachine:

docker run --rm -p 3000:3000 thecodingmachine/gotenberg:8
info

The API will be available at http://localhost:3000.

Docker Compose​

Incorporating Gotenberg into your Docker Compose services stack is as straightforward as:

docker-compose.yml
services:
  # Your other services.

  gotenberg:
    image: gotenberg/gotenberg:8
info

The API will be accessible at gotenberg:3000 within your Docker Compose network. This means your other services can interact with Gotenberg using gotenberg:3000.

If you want to expose the API to your localhost, consider adding a ports section:

docker-compose.yml
services:
  # Your other services.

  gotenberg:
    image: gotenberg/gotenberg:8
    ports:
      - "3000:3000"
info

The API will be available at http://localhost:3000.

Kubernetes​

The Docker image employs a specific non-root user, named gotenberg, with a User ID (uid) and Group ID (gid) of 1001.

When detailing the pod's deployment specification, remember to include:

securityContext:
  readOnlyRootFilesystem: false
  allowPrivilegeEscalation: false
  privileged: false
  runAsUser: 1001

Other than that, ensure to allocate sufficient memory and CPU resources (at least 512Mi for memory and 0.2 for CPU).

A community Helm chart is also available at MaikuMori/helm-charts and on ArtifactHub.

Cloud Run​

If cost-efficiency is a priority for you, Cloud Run could be an appealing option.

We have a dedicated Docker image tag specifically for this provider:

gotenberg/gotenberg:8-cloudrun

Alternatively, using the historic Docker repository from our sponsor TheCodingMachine:

thecodingmachine/gotenberg:8-cloudrun

Using the Google Cloud CLI:

gcloud run deploy {deployment_name} \
--memory=1Gi \
--image=gotenberg/gotenberg:8-cloudrun \
--args=gotenberg \
--args="--api-port-from-env=PORT" \
--args="--webhook-disable=true" \
--args="--chromium-auto-start=true" \
--args="--libreoffice-auto-start=true"
  • At least 1Gi of memory is required for a smooth experience.
  • By default, requests are sent to port 8080, but you can configure Cloud Run to send requests to the port of your choice. Cloud Run injects the PORT environment variable into the ingress container.
  • The webhook feature does not work properly, as Cloud Run may stop the container if there is no HTTP activity, regardless of the asynchronous processes.
  • Enabling Chromium and/or LibreOffice auto-start improves the readiness of Gotenberg in a serverless context.
info

Consider using HTTP/2 to bypass the 32MB request size limit.

Modules Configuration​

The Docker image internally employs a binary that offers flags to configure its multiple modules (for more detailed information, refer to the configuration guide).

To set one or more flags, it's necessary to override the Docker image's default command.

For example, with the Docker CLI:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8 gotenberg --my-module-property=foo

Or with Docker Compose:

docker-compose.yml
services:
  # Your other services.

  gotenberg:
    image: gotenberg/gotenberg:8
    command:
      - "gotenberg"
      - "--my-module-property=foo"
caution

Do not redefine the Gotenberg Docker image default entrypoint, but override the command instead. See this issue for more details.

What's next?​

Now that you have Gotenberg up and running, you can start using it. Install a custom client or read the routes guide to learn more.