Deploying the Apollo Runtime in Docker

Run an Apollo Runtime container image in Docker


This guide provides the following examples of running an Apollo Router container image in Docker:

  • Running a basic example with default configuration.

  • Customizing your configuration to override the default configuration.

  • Manually specifying a supergraph for your router.

The documentation for the docker run command is a helpful reference for the examples in this guide.

The exact image version to use depends on which release you wish to use. In the following examples, replace <image version> with your chosen version. For additional details on versioning, see the container tags documentation.

note
The Apollo Router Core source code and all its distributions are made available under the Elastic License v2.0 (ELv2) license.

Quick start

To run the router, your Docker container must have the APOLLO_GRAPH_REF and APOLLO_KEY environment variables set to your graph ref and API key, respectively.

Below is a basic example of running an Apollo Runtime image with Docker. It downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port 4000.

You can use docker run with the following example command:

Bash
Docker
1docker run \
2  -p 4000:4000 \
3  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
4  --env APOLLO_KEY="<your-graph-api-key>" \
5  --rm \
6  ghcr.io/apollographql/apollo-runtime:latest

Make sure to replace <your-graph-ref> and <your-graph-api-key> with your graph reference and API key, respectively.

Enabling MCP

EXPERIMENTAL
This feature is experimental. For more information about MCP support, review the MCP documentation.

To serve MCP requests, enable the MCP server using the MCP_ENABLE environment variable. You'll also need to export container port 5000 for HTTP Streamable connections to the MCP server, using the -p 5000:5000 flag.

Bash
Docker
1docker run \
2  -p 4000:4000 \
3  -p 5000:5000 \
4  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
5  --env APOLLO_KEY="<your-graph-api-key>" \
6  --env MCP_ENABLE=1 \
7  --env MCP_UPLINK=1 \
8  --rm \
9  ghcr.io/apollographql/apollo-runtime:latest

Configuring using local files

You can provide your own configuration from the host environment to the router by mounting the directory containing your configuration files to /config as follows:

Bash
Docker
1docker run -p 4000:4000 \
2  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
3  --env APOLLO_KEY="<your-graph-api-key>" \
4  -v <<ABSOLUTE_PATH_TO_THE_MY_CONFIG_DIRECTORY>>:/config
5  --rm \
6  ghcr.io/apollographql/apollo-runtime:<runtime-image-version>

You can also mount specific files, for example the schema file, by specifying:

Bash
Docker
1...
2-v <<ABSOLUTE_PATH_TO_SCHEMA_FILE>:/config/schema.graphql 
3...

If you wish to override the default router configuration, it is important to preserve aspects of the default configuration. In particular, it is generally important for the router to bind to and listen on the special address of 0.0.0.0 (for all interfaces) to ensure it's exposed on a network interface that's accessible outside of the local container. Without this configuration, the router will only listen on localhost.

This allows for using local supergraph schemas, persisted query manifests, router configuration, and more. To learn more, review the documentation.

note
Both local and container paths must be specified as absolute paths.

Specifying the supergraph

If you don't want to automatically update your supergraph via Apollo Uplink, or you don't have connectivity to access Apollo Uplink from your environment, you have two options:

  1. Using a local supergraph file, as documented in the Configuring using local files section.

  2. Using an OCI image reference

Using an OCI image reference

You can use the GRAPH_ARTIFACT_REFERENCE environment variable to fetch the supergraph schema from an OCI image:

Bash
1docker run -p 4000:4000 \
2  --env APOLLO_KEY="<your-graph-api-key>" \
3  --env GRAPH_ARTIFACT_REFERENCE="<your-oci-reference>" \
4  --rm \
5  ghcr.io/apollographql/apollo-runtime:<runtime-image-version>

When using this option, the router will fetch the schema from the specified OCI image instead of using Apollo Uplink. Additional information on graph artifacts is available in the router CLI options documentation.

Running a specific Router and MCP version

The container has a tagging scheme that consists of three parts, the container version, the Apollo Router version, and the MCP Server version, each separated by underscores.

To learn more, see the tagging documentation.

Additional router configuration information

For more complex configurations, such as overriding subgraph URLs or propagating headers, see Router Configuration.

Router-only Docker container

Learn more about the Docker container that includes only the Apollo Router in the Router-only Docker container documentation.

Feedback

Edit on GitHub

Ask Community