Deploying the Apollo Runtime 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.

Quick start

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

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:

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

To serve MCP requests, enable the Apollo MCP Server using the MCP_ENABLE environment variable. You'll also need to export the container port where the MCP server is running, port 8000 by default, for Streamable HTTP connections to the MCP server, using the -p 8000:8000 flag.

1docker run \
2  -p 4000:4000 \
3  -p 8000:8000 \
4  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
5  --env APOLLO_KEY="<your-graph-api-key>" \
6  --env MCP_ENABLE=1 \
7  --rm \
8  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:

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:

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.

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 a graph artifact reference

Using a graph artifact reference

⚠️ This option is in preview and doesn't support hot-reloading of schemas.

Set the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable to use the supergraph schema from a graph artifact:

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

When you set this option, the router uses the schema from the specified graph artifact instead of Apollo Uplink. The router still fetches entitlements and persisted queries from Uplink. For more information on graph artifacts, see the Router CLI Configuration Reference.

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.