Deploying the Apollo Runtime in Docker

This guide shows you how to run the Apollo Runtime container, which includes both the Apollo Router and MCP Server in a single image.

If you only need the Apollo Router without MCP Server functionality, see Router-only Docker container.

This guide explains how to:

• Run a basic Apollo Runtime container with default configuration

• Customize configuration to override defaults

• Manually specify a supergraph for your Router

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

Prerequisites

Before you start:

1. Set up a GraphQL API in GraphOS.

   • Save your APOLLO_KEY and APOLLO_GRAPH_REF. You'll need them when deploying the Router.

2. Install Docker locally.

3. Choose a container version to deploy (for example, latest or a specific version tag). For versioning details, see the container tags documentation.

Quick start

Run the following command, replacing the APOLLO_GRAPH_REF and APOLLO_KEY values with your own.

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

This command runs the Apollo Runtime image with Docker, downloads your supergraph schema from Apollo and uses a default configuration that listens on port 4000.

Enabling MCP

Enable the Apollo MCP Server using the MCP_ENABLE environment variable. Export container port 8000 for Streamable HTTP connections to the MCP server with 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

Provide your own configuration by mounting the directory containing your configuration files to /config:

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>

Mount specific files, such as your schema file:

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

When overriding the default Router configuration, preserve the 0.0.0.0 bind address (for all interfaces). This ensures the Router is accessible outside the container. Without this, the Router only listens on localhost.

Use this method for local supergraph schemas, persisted query manifests, Router configuration, and more. Learn more in the configuration documentation.

Specifying the supergraph

To avoid automatically updating your supergraph via Apollo Uplink, or if you can't access Apollo Uplink from your environment, use one of these options:

1. Use a local supergraph file, as documented in Configuring using local files.

2. Use 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>

The Router uses the schema from the specified graph artifact instead of Apollo Uplink. The Router still fetches entitlements and persisted queries from Uplink. Learn more in the Router CLI Configuration Reference.

Running a specific Router and MCP version

The Apollo Runtime uses a three-part tagging scheme separated by underscores: container version, Apollo Router version, and MCP Server version. This allows you to pin specific versions of the runtime components.

Tag format examples

Latest of everything:

1ghcr.io/apollographql/apollo-runtime:latest

This retrieves the newest versions of all components.

Pinned container and router:

1ghcr.io/apollographql/apollo-runtime:v0.1.0_router2.1.2

This locks the runtime container and router versions while always fetching the latest MCP server.

Pinned router and MCP server:

1ghcr.io/apollographql/apollo-runtime:latest_router2.1.2_mcp-server0.2.1

This fixes specific router and MCP server versions but keeps the container version current.

Alternative registry

If ghcr.io is inaccessible to you, all images are also available on DockerHub as of 0.0.13_router2.5.0_mcp-server0.7.0 onwards:

1docker pull apollograph/apollo-runtime