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.
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:
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 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.
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:
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:
Using a local supergraph file, as documented in the Configuring using local files section.
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:
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.