Installation

Don't expose Gotenberg to the public internet. Treat it like a database: keep it behind your firewall.

Live Demo

Try the API without installing anything:

• https://demo.gotenberg.dev

Open a terminal and run:

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

The demo runs on a Render instance (512MB RAM, 0.5 CPU) with rate limits: 2 requests/second per IP, 5MB body limit.

A community-maintained web UI is available at nktnet1/gotenui (Live Demo).

Docker

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

The API is now available at http://localhost:3000.

By default, published ports are accessible from the outside world. Bind to localhost for a more secure setup:

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

Image Variants

Gotenberg ships three image variants:

Image	Size	Includes
gotenberg/gotenberg:8	Full	Chromium, LibreOffice, and PDF Engines.
gotenberg/gotenberg:8-chromium	~30% smaller	Chromium and PDF Engines. No office document conversion.
gotenberg/gotenberg:8-libreoffice	~40% smaller	LibreOffice and PDF Engines. No URL/HTML/Markdown conversion or screenshots.

All variants include PDF Engines (merge, split, encrypt, watermark, metadata, bookmarks, attachments, etc.).

Feature Availability

Feature	Full	Chromium	LibreOffice
URL / HTML / Markdown to PDF	✅	✅	❌
Screenshots	✅	✅	❌
Office document conversion (.docx, .xlsx, .pptx, etc.)	✅	❌	✅
Merge, split, rotate, flatten PDFs	✅	✅	✅
Encrypt, watermark, stamp PDFs	✅	✅	✅
Read/write metadata & bookmarks	✅	✅	✅
File attachments	✅	✅	✅
Factur-X / ZUGFeRD e-invoicing	✅	❌	✅
PDF/A & PDF/UA conversion	✅	❌	✅
Webhooks & async processing	✅	✅	✅
Download from remote URLs	✅	✅	✅

Requesting an unavailable feature returns an error.

Docker Compose

compose.yaml

services:
  # Your other services.

  gotenberg:
    image: gotenberg/gotenberg:8

Other services in the same Compose network can reach Gotenberg at gotenberg:3000.

To also expose it on your host, add 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"

Kubernetes

The image runs as a non-root user gotenberg (UID/GID 1001). Since 8.21.0, arbitrary user IDs (OpenShift) are also supported.

Include this in your pod’s deployment spec:

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

Allocate at least 512Mi of memory and 0.2 CPU. A community-maintained Helm chart is available at MaikuMori/helm-charts (ArtifactHub).

Cloud Run

gotenberg/gotenberg:8-cloudrun
gotenberg/gotenberg:8-chromium-cloudrun
gotenberg/gotenberg:8-libreoffice-cloudrun

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.

Allocate at least 1Gi of memory for a smooth experience. Consider HTTP/2 to bypass the 32MB request size limit.

AWS Lambda (Beta)

Available on linux/amd64 and linux/arm64:

gotenberg/gotenberg:8-aws-lambda
gotenberg/gotenberg:8-chromium-aws-lambda
gotenberg/gotenberg:8-libreoffice-aws-lambda

Preconfigured for AWS Lambda:

• Uses the AWS_LWA_PORT environment variable to configure its port.
• Set AWS_LWA_READINESS_CHECK_PATH with the route /health.
• Set AWS_LWA_INVOKE_MODE with the value buffered.
• Uses synchronous webhook mode, since AWS may stop the container if there’s no HTTP activity.
• See https://github.com/awslabs/aws-lambda-web-adapter for more AWS related options.

The buffered invoke mode supports responses up to 6MB. For larger outputs, use the webhook feature to upload results to S3.

SnapStart

Since 8.39.0, the images support Lambda SnapStart. It reduces cold start latency, and costs less than Provisioned Concurrency.

• Keep --chromium-auto-start=true and --libreoffice-auto-start=true. Both processes start during init and become part of the snapshot.
• Enable SnapStart with ApplyOn: PublishedVersions, and invoke a published version or an alias. SnapStart doesn't apply to $LATEST.
• Init runs when you publish a version, with a limit of 130 seconds. The adapter ignores AWS_LWA_ASYNC_INIT under SnapStart. Set AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS to bound the wait.

SnapStart limits /tmp to 512MB, which caps the size of conversions. It doesn't work with Provisioned Concurrency or EFS. See #1704 for test results.

There is an ongoing discussion about improving this variant. Feedback welcome.

What's Next?

Install a client or jump to the routes overview.