Hosting Engine as a standalone server in PaaS Environments

How to run the Engine container separately on a Platform as a Service like Heroku

If you want to run Engine separately from your GraphQL server, you can choose to host the Engine Docker container on a platform as a service such as Heroku, and use it as a proxy in front of your API.

To do this, you’ll need to:

  1. Instrument your server with a supported tracing agent that uses the Apollo Tracing format.
  2. Configure and deploy the Engine proxy docker container.
  3. Send requests to your service – you’re all set up!

If you’re using Node, we recommend running the Engine proxy with direction Web framework integration as opposed to within a Docker container inside of a separate app / dyno. In that case, follow the Node setup instructions. For all other platforms, the only available option is to run the proxy in a standalone docker container.

If you’re interested in writing direct a direct Engine web framework integration for your platform, get in touch with us!

For running on Heroku specifically, see our Heroku Engine Proxy example repo.

1. Enable Apollo Tracing

You will need to instrument your GraphQL server with a tracing package that matches your server platform. Engine relies on receiving data in this format to create its performance telemetry reports.

2. Configure the Proxy

2.1 Get your API Key

First, get your Engine API key by creating a service on You will need to log in and click “Add Service” to recieve your API key.

2.2 Follow the Engine Heroku Example to configure your Proxy

The standalone proxy uses a JSON file placed in the Docker container’s root folder to get configuration information. Changes to the config.json will cause the proxy to adopt the new configuration without downtime.

NOTE: For Virtual Hosted environments where the PORT is dynamically set in an environment variable named $PORT, you can leave out the port option. If your environment uses a different environment variable, you can name it with the portFromEnv option instead.

Create a JSON configuration file:

  "apiKey": "<ENGINE_API_KEY>",
  "logging": {
    "level": "INFO"
  "origins": [
      "http": {
        "url": "",
        "overrideRequestHeaders": {
          "Host": ""
  "frontends": [
      "host": "",
      "port": "3000",
      "graphqlPaths": ["/graphql"]

Configuration options:

  1. apiKey: The API key for the Engine service you want to report data to.
  2. logging.level : Logging level for the proxy. Supported values are DEBUG, INFO, WARN, ERROR.
  3. origin.http.url : The URL for your GraphQL server.
  4. origins.http.overrideRequestHeaders.Host: set to the origin hostname so virtual hosting systems can properly route to the origin.
  5. : The hostname the proxy should be available on.
  6. frontend.port : The port the proxy should bind to.
  7. frontend.graphqlPaths : The path for the proxy’s GraphQL server. Defaults to ['/graphql'].

For full configuration details see Proxy config.

It does not matter where you choose to deploy and manage your Engine proxy. We run our own on Amazon’s EC2 Container Service.

We recognize that almost every team using Engine has a slightly different deployment environment, and encourage you to contact us with feedback or for help if you encounter problems running the Engine proxy.

3. View Metrics in Engine

Once your server is set up, navigate your new Engine service on Start sending requests to your GraphQL server to start seeing performance metrics!

Edit on GitHub
// search box