Docker and the router

The default behaviour of the router images is suitable for a quickstart or development scenario. You'll need to know how to customize this default behaviour if you wish to do any of the following.

Note: The docker documentation for the run command may be helpful when reading through the examples.

Note: The exact image version to use is your choice depending on which release you wish to use. In the following examples, replace <image version> with your chosen version. e.g.: v1.12.1

Override the configuration

Our default Docker images include a basic configuration which can be seen in our repository. Inside the container, this file is located at /dist/config/router.yaml.

If you wish to override the default configuration, it is important to consider and preserve aspects of the default configuration. In particular, it is generally important for the Router to bind to the special "listening address" of 0.0.0.0 (i.e., "all interfaces") to ensure the Router is exposed on a the network interface accessible outside of the local container; without this configuration, the Router will only listen on localhost.

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

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

In this case 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 does run not set any of the available command-line arguments. If you want to set any of the available options, pass the desired options at end of the docker run command. For example, to start the Router using the --log debug argument, you can use the following docker run command:

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

Debugging your container

It's easy to debug your container by changing the entrypoint

1
docker run -p 4000:4000 \
2
  --env APOLLO_GRAPH_REF="<your graph>" \
3
  --env APOLLO_KEY="<your key>" \
4
  --mount "type=bind,source=/router.yaml,target=/dist/config/router.yaml" \
5
  --rm \
6
  --interactive \
7
  --tty \
8
  --entrypoint=bash \
9
  ghcr.io/apollographql/router:<image version>
10
dist# pwd
11
/dist
12
dist# ls
13
config  router  schema
14
dist# exit
15
exit

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

Running the debug container to investigate memory issues

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

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

Specifying the supergraph

If we don't want to use uplink to retrieve our subgraph, we can manually specify the details.

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

Note: In this example we have to mount the local definition of the supergraph 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 router configuration but want to make sure it's used, we just specify the default location of the default configuration.

Building your own container

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:

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

Note: The script has to be run from the dockerfiles/diy directory because it makes assumptions about the relative availability of various files. 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 since it makes the assumption that there is a heaptrack package available to install.