Skip to main content

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.

caution

Publishing container ports is insecure by default. Meaning, when you publish a container's ports it becomes available not only to the Docker host, but to the outside world as well.

If you include the localhost IP address (127.0.0.1, or ::1) with the publish flag, only the Docker host and its containers can access the published container port.

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

Docker Compose​

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

compose.yaml
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 on your host, consider adding a ports section:

compose.yaml
services:
  # Your other services.

  gotenberg:
    image: gotenberg/gotenberg:8
    ports:
      - "3000:3000"
     # Or more secure:
     # - "127.0.0.1:3000:3000"
info

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

Kubernetes​

The Docker image runs as a non-root user named gotenberg, with a user ID (UID) and group ID (GID) of 1001.

info

Since Gotenberg 8.21.0, the image also supports arbitrary user IDs (OpenShift).

When defining the pod’s deployment spec, make sure to include the following:

securityContext:
  readOnlyRootFilesystem: false
  allowPrivilegeEscalation: false
  privileged: false
  runAsUser: 1001 # unless using an arbitrarily assigned user ID.

Additionally, ensure the container has adequate resource allocations — at least 512Mi of memory and 0.2 CPU.

A community-maintained 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

This image is preconfigured for Cloud Run:

  • Uses the PORT environment variable provided by Cloud Run.
  • Logs in a format compatible with Cloud Run.
  • Auto-starts Chromium and LibreOffice for faster readiness.
  • Uses synchronous webhook mode, since Cloud Run may stop the container if there’s no HTTP activity.
tip

At least 1Gi of memory is required for a smooth experience.

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

AWS Lambda​

If cost-efficiency is a priority, AWS Lambda can be a good option.

We provide a dedicated Docker image tag, available on both linux/amd64 and linux/arm64 architectures:

gotenberg/gotenberg:8-aws-lambda

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

thecodingmachine/gotenberg:8-aws-lambda

This image is preconfigured for AWS Lambda:

  • Uses the AWS_LWA_PORT environment variable to configure its port.
  • Auto-starts Chromium and LibreOffice for faster readiness.
  • Uses synchronous webhook mode, since AWS may stop the container if there’s no HTTP activity.

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.