User Documentation


Sign up for Upsun

Get your free trial by clicking the link below.

Get your Upsun free trial

Gotenberg is a stateless API for converting various document formats into PDF files. For more information, see the Gotenberg documentation.

Supported versions Anchor to this heading

  • 8

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches.

Relationship reference Anchor to this heading

Example information available through the PLATFORM_RELATIONSHIPS environment variable or by running platform relationships.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the PLATFORM_RELATIONSHIPS environment variable directly rather than hard coding any values.


For some advanced use cases, you can use the PLATFORM_RELATIONSHIPS environment variable. The structure of the PLATFORM_RELATIONSHIPS environment variable can be obtained by running platform relationships in your terminal:

      "host": "gotenberg.internal",
      "hostname": "",
      "cluster": "p2f2xrzyq7a6k-main-bvxea6i",
      "service": "gotenberg",
      "rel": "http",
      "scheme": "http",
      "port": "3000",
      "type": "gotenberg:8",
      "instance_ips": [
      "ip": "",
      "url": "http://gotenberg.internal:3000"

Here is an example of how to gather PLATFORM_RELATIONSHIPS environment variable information in a .environment file:

# Decode the built-in credentials object variable.

# Set environment variables for individual credentials.
export APP_GOTENBERG_HOST=="$(echo $RELATIONSHIPS_JSON | jq -r '.gotenberg[0].host')"

Usage example Anchor to this heading

1. Configure the service Anchor to this heading

To define the service, use the gotenberg type:
# The name of the service container. Must be unique within a project.
    type: gotenberg:<VERSION>

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

2. Add the relationship Anchor to this heading

To define the relationship, use the http endpoint:
# Relationships enable access from this app to a given service.

You can define <SERVICE_NAME> as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.

With the above definition, uses the http endpoint, providing a relationship (the network address a service is accessible from) that is identical to the name of the service.

The application has access to the service via this relationship and its corresponding PLATFORM_RELATIONSHIPS environment variable.

The http endpoint uses port 3000 by default.

Example configuration Anchor to this heading

Service definition Anchor to this heading

# The name of the service container. Must be unique within a project.
    type: gotenberg:8

App configuration Anchor to this heading
# Relationships enable access from this app to a given service.
    gotenberg: "gotenberg:http"

Generate a PDF using Gotenberg Anchor to this heading

As an example, to generate a PDF file of the website, run the following cURL command:

curl \
--request POST \
--form url= \
--form landscape=true \
--form marginTop=1 \
--form marginBottom=1 \
-o my.pdf

Is this page helpful?