Deploying GraphOS 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.

• Debugging your containerized router.

• 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, additional details on version information are available here.

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 a router 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

In order to serve MCP requests, the MCP server needs to be enabled and port 5000 published.

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 path which contains 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:<router-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 here.

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

Documentation for the Docker container which contains only the Router is available here.