Docs
Launch GraphOS Studio

Run in Docker

Run the Apollo Router container image in Docker


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

  • Running a basic example with default configuration.
  • Customizing your configuration to override the default configuration.
  • Debugging your containerized .
  • Manually specifying a for your .
  • Building your own Docker image.

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 example v1.32.0.

NOTE

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

Basic example running router in Docker

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

Here's a basic example of running a image in Docker. Make sure to replace <router-image-version> with whichever version you want to use, such as v1.32.0.

Docker
docker run -p 4000:4000 \
--env APOLLO_GRAPH_REF="<your-graph-ref>" \
--env APOLLO_KEY="<your-graph-api-key>" \
--rm \
ghcr.io/apollographql/router:<router-image-version>

This command downloads your from Apollo and uses a default configuration that listens for connections on port 4000.

For more complex configurations, such as overriding URLs or propagating headers, see Configuring the Apollo Router.

Override the configuration

Apollo's default Docker images include a basic router configuration. Inside the container, this file is located at /dist/config/router.yaml.

If you wish to override the default configuration, it is important preserve aspects of the default configuration. In particular, it is generally important for the 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 will only listen on localhost.

You can provide your own configuration from the host environment to the by mounting your configuration to /dist/config/router.yaml as follows:

docker run -p 4000:4000 \
--env APOLLO_GRAPH_REF="<your-graph-ref>" \
--env APOLLO_KEY="<your-graph-api-key>" \
--mount "type=bind,source=/home/user/router.yaml,target=/dist/config/router.yaml" \
--rm \
ghcr.io/apollographql/router:<router-image-version>

NOTE

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

In this example we are mounting a file from the host system (/home/user/router.yaml) in place of the default configuration provided in the image at /dist/config/router.yaml.

Passing command-line arguments to the router binary

By default, the router command invoked inside the published container doesn't set any of the available command-line options. To set them, append the desired option(s) to the docker run command.

For example, to start the using the --log debug option, use the following docker run command with the option added at the end:

docker run -p 4000:4000 \
--env APOLLO_GRAPH_REF="<your-graph-ref>" \
--env APOLLO_KEY="<your-graph-api-key>" \
--rm \
ghcr.io/apollographql/router:<router-image-version> --log debug

Debugging your container

You can debug your container by setting the entrypoint in a docker run command:

docker run -p 4000:4000 \
--env APOLLO_GRAPH_REF="<your graph>" \
--env APOLLO_KEY="<your key>" \
--mount "type=bind,source=/router.yaml,target=/dist/config/router.yaml" \
--rm \
--interactive \
--tty \
--entrypoint=bash \
ghcr.io/apollographql/router:<image version>
dist# pwd
/dist
dist# ls
config router schema
dist# exit
exit

In this example, we've added both interactive and tty flags, and we've changed the entrypoint of the image to be a bash shell.

Running the debug container to investigate memory issues

docker run -p 4000:4000 \
--env APOLLO_GRAPH_REF="<your graph>" \
--env APOLLO_KEY="<your key>" \
--mount "type=bind,source=/data,target=/dist/data"
--rm \
ghcr.io/apollographql/router:<image version>-debug

The runs under the control of heaptrack. The heaptrack output is saved to the /data directory. The output can be analyzed directly using heaptrack_gui or heaptrack_print or shared with Apollo support.

Specifying the supergraph

If you don't want to automatically update your via Apollo Uplink, or you don't have connectivity to access Apollo Uplink from your environment, you can manually specify the details of your in a docker run command:

docker run -p 4000:4000 \
--mount "type=bind,source=/docker.graphql,target=/dist/schema/local.graphql" \
--rm \
ghcr.io/apollographql/router:<image version> -c config/router.yaml -s schema/local.graphql

In this example, we have to mount the local definition of the into our image, and specify the location of the file. It doesn't have to be mounted in the /dist/schema directory, but it's a reasonable location to use. We must specify the configuration file location as well, since overriding the default params will override our default config file location. In this case, since we don't want to change our configuration but want to make sure it's used, we just specify the default location of the default configuration.

Building your own container

NOTE

This section is aimed at developers familiar with tooling such as docker and git who wish to make their own DIY container images. The script here is not a part of the product, but an illustrative example of what's involved in making your own images.

In the dockerfiles/diy directory, we now provide a script, build_docker_image.sh which illustrates how to build your own docker images from either our released tarballs or from a git commit hash or tag. Here's how to use it:

% ./build_docker_image.sh -h
Usage: build_docker_image.sh [-b [-r <repo>]] [-d] [<release>]
-b build docker image from the default repo, if not present build from a released version
-d build debug image, router will run under control of heaptrack
-r build docker image from a specified repo, only valid with -b flag
<release> a valid release. If [-b] is specified, this is optional
Example 1: Building HEAD from the repo
build_docker_image.sh -b
Example 2: Building HEAD from a different repo
build_docker_image.sh -b -r /Users/anon/dev/router
Example 3: Building tag from the repo
build_docker_image.sh -b v0.9.1
Example 4: Building commit hash from the repo
build_docker_image.sh -b 7f7d223f42af34fad35b898d976bc07d0f5440c5
Example 5: Building tag v0.9.1 from the released version
build_docker_image.sh v0.9.1
Example 6: Building a debug image with tag v0.9.1 from the released version
build_docker_image.sh -d v0.9.1

The example uses debian:bullseye-slim image for the final image build. Feel free to modify the script to use images which better suit your own needs, but be careful if using the -d flag because it makes the assumption that there is a heaptrack package available to install.

Previous
Deploy on Kubernetes
Next
Health checks
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company