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.: v0.15.1

Override the configuration

If you wish to override the default configuration, then you need to provide the new configuration:

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
  ghcr.io/apollographql/router:<image version>

In this case we are mounting a file from our local system's root directory (Note: that path must be absolute) over the top of the default configuration in the image.

If, for whatever reason, we wish to specify a different location for our configuration, we can:

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=/tmp/router.yaml" \
5
  --rm \
6
  ghcr.io/apollographql/router:<image version> -c /tmp/router.yaml

Here, we are mounting our configuration into the /tmp directory and changing the router startup to let it know that it can find configuration in /tmp/router.yaml.

Debugging your container

If you run the debug image, then it's easy to debug your container:

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=sh
9
  ghcr.io/apollographql/router:<image version>-debug
10
/dist # pwd
11
/dist
12
/dist # ls
13
LICENSE        config         router
14
README.md      licenses.html  schema
15
/dist # exit

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

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] [<release>]
3
    -b build docker image from a repo, if not present build from a released tarball
4
    <release> a valid release. If [-b] is specified, this is optional
5
    Example 1: Building HEAD from the repo
6
        build_docker_image.sh -b
7
    Example 2: Building tag from the repo
8
        build_docker_image.sh -b v0.15.1
9
    Example 3: Building commit hash from the repo
10
        build_docker_image.sh -b 1c220d35acf9ad2537b8edc58c498390b6701d3d
11
    Example 4: Building tag v0.15.1 from the released tarball
12
        build_docker_image.sh v0.15.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 distroless images for the final image build. Feel free to modify the script to use images which better suit your own needs.