Router Quickstart
Run the router with GraphOS and Apollo-hosted subgraphs
Hello! This tutorial walks you through installing the router (GraphOS Router or Apollo Router Core) and running it in with GraphOS and some example Apollo-hosted subgraphs.
This quickstart helps you run a self-hosted instance of the router. If you create a cloud supergraph with Apollo GraphOS, Apollo provisions and hosts your supergraph's GraphOS Router for you.
Cloud supergraphs are recommended for organizations that don't need to host their router in their own infrastructure.
1. Download and extract the router binary
ⓘ NOTE
The Apollo Router Core source code and all its distributions are made available under the Elastic License v2.0 (ELv2) license.
Download options
Automatic download (Linux, OSX, WSL)
If you have a bash-compatible terminal, you can download the latest version of the Apollo Router Core directly to your current directory with the following command:
curl -sSL https://router.apollo.dev/download/nix/latest | sh
Manual download
Go to the Apollo Router Core's GitHub Releases page and download the latest .tar.gz
file that matches your system. Currently, tarballs are available for the following:
- Linux (x86_64)
- Linux (aarch64)
- macOS (Apple Silicon)
- Windows (x86_64)
If a tarball for your system or architecture isn't available, you can build and run the router from source. You can also open an issue on GitHub to request the addition of new architectures.
After downloading, extract the file by running the following from a new project directory, substituting the path to the tarball:
tar -xf path/to/file.tar.gz --strip-components=1
If you omit the --strip-components=1
option, the router
executable is installed in a dist
subdirectory.
Running the binary
You can now run the router from your project's root directory with the following command:
./router
If you do, you'll get output similar to the following:
Apollo Router <version> // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)⚠️ The Apollo Router requires a composed supergraph schema at startup. ⚠️👉 DO ONE:* Pass a local schema file with the '--supergraph' option:$ ./router --supergraph <file_path>* Fetch a registered schema from GraphOS by settingthese environment variables:$ APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./routerFor details, see the Apollo docs:https://www.apollographql.com/docs/federation/managed-federation/setup🔬 TESTING THINGS OUT?1. Download an example supergraph schema with Apollo-hosted subgraphs:$ curl -L https://supergraph.demo.starstuff.dev/ > starstuff.graphql2. Run the router in development mode with the supergraph schema:$ ./router --dev --supergraph starstuff.graphql
This is because router requires a supergraph schema and we aren't providing it one! Let's fix that.
2. Download the example supergraph schema
For this quickstart, we're using example Apollo-hosted subgraphs, along with an example supergraph schema that's composed from those subgraph schemas.
From your project's root directory, run the following:
curl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql
This saves a supergraph-schema.graphql
file with the following contents:
This file is all that the router needs to communicate with our subgraphs!
3. Run the router in development mode with the default configuration
Now from your project root, run the following:
./router --dev --supergraph supergraph-schema.graphql
The console output should look like the following:
2022-06-29T22:23:24.266542Z INFO apollo_router::executable: Apollo Router v0.9.5 // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)2022-06-29T22:23:24.488286Z INFO apollo_router::router: starting Apollo Router2022-06-29T22:23:25.774334Z INFO apollo_router::axum_http_server_factory: GraphQL endpoint exposed at http://127.0.0.1:4000/ 🚀
That's it! Running the router with the --dev
flag enables a development mode that exposes Apollo Sandbox so you can run queries against the router.
⚠️ CAUTION
Do not use the --dev
flag in a non-development environment. It relaxes certain default configuration options to provide an improved local development experience (e.g., it exposes subgraph error messages to clients).
Visit http://127.0.0.1:4000
to open Apollo Sandbox, inspect your entire supergraph, and run your first queries!
Next steps
Now that you know how to run the router with a supergraph schema, you can: