Open in app

Sign in

Write

Sign in

Building an Apollo Supergraph Locally

Cloud Journey
6 min readApr 9, 2023

--

Overview

We will use a Windows desktop as our local development environment and gain hands-on experience in administering Apollo federation through this blog post.

If you are brand new to Apollo GraphQL, please first go through Apollo GraphQL voyage tutorials.

Install Docker Desktop for Windows

Docker Desktop and Windows Subsystem for Linux

Install docker desktop from here https://docs.docker.com/desktop/install/windows-install/.

Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI.

After docker desktop installation, restart windows, and upgrade wsl.

C:\Users\rquan>wsl --update
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.

C:\Users\rquan>docker

Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Options:
      --config string      Location of client config files (default
                           "C:\\Users\\rquan\\.docker")
  ......
C:\Users\rquan>docker compose

Usage:  docker compose [OPTIONS] COMMAND

Docker Compose

Options:
      --ansi string                Control when to print ANSI control
                                   characters ("never"|"always"|"auto")
                                   (default "auto")
.....

Turn on Docker Desktop WSL 2

  • Start Docker Desktop from the Windows Start menu.
  • From the Docker menu, select Settings and then General.
  • Select the Use WSL 2 based engine check box.

Refer to Docker official doc at https://docs.docker.com/desktop/windows/wsl/ in case you require further details.

Info: Keep docker desktop up and running through out the lab！

Install Ubuntu

Open the Microsoft Store application and search “Ubuntu”.
Click on Ubuntu, hit get, and wait for it to install. Note: You can use any version, but the one without the version number will give you the latest version of Ubuntu.

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: nino
New password:
......
Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.90.1-microsoft-standard-WSL2 x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

This message is shown once a day. To disable it please create the
/home/nino/.hushlogin file.
nino@DESKTOP-TMK1GG5:~$

Install Apollo GraphQL Tools

Open Ubuntu app, install ‘make’, clone project from Github, install Apollo rover and router.

nino@DESKTOP-TMK1GG5:~$ sudo apt install make

nino@DESKTOP-TMK1GG5:/mnt/d/NewApollo$ make -help
Usage: make [options] [target] ...
Options:
  -b, -m                      Ignored for compatibility.
......

nino@DESKTOP-TMK1GG5:/mnt/d/NewApollo$git clone https://github.com/apollographql/supergraph-demo-fed2.git demo
$ cd demo

$ make deps
--------------------------------------------
curl -sSL https://rover.apollo.dev/nix/latest | sh
downloading rover from https://github.com/apollographql/rover/releases/download/v0.13.0/rover-v0.13.0-x86_64-unknown-linux-gnu.tar.gz

--------------------------------------------
curl -sSL https://router.apollo.dev/download/nix/latest | sh
Downloading router from https://github.com/apollographql/router/releases/download/v1.14.0/router-v1.14.0-x86_64-unknown-linux-gnu.tar.gz ...

Close Ubuntu app and re-open it in another terminal window.

nino@DESKTOP-TMK1GG5:/mnt/d/NewApollo/demo$ rover  --version
Rover 0.13.0
nino@DESKTOP-TMK1GG5:/mnt/d/NewApollo/demo$ ./router --version
1.14.0

Run Subgraph

Start Ubuntu app and proceed to build subgraphs. This step requires around 6G of disk space, so make sure that you have enough free space before proceeding.

nino@DESKTOP-TMK1GG5:/mnt/d/NewApollo/demo$ make up-subgraphs

docker compose \
 -f docker-compose.yaml \
 -f opentelemetry/docker-compose.otel.yaml \
 up -d --build
......

If the build succeeded, you should see a log similar to the one shown in the following screenshot.

Open Apollo sandbox https://studio.apollographql.com/sandbox/explorer. Then, browse the products subgraph on port 4001: http://localhost:4001/.

Schema Registry in GraphOS

Apollo GraphOS offers hosted schema registries for supergraph schema. The schema registry is a feature within Apollo GraphOS product and Apollo studio is the primary web interface for GraphOS.

The schema registry is not open-source and you won’t be able to install it locally.

Sign Up Apollo Studio

Apollo Studio is the primary web interface for interacting with the GraphOS platform. We’ll use Studio in every step of this tutorial, starting with creating an account.

Go to studio.apollographql.com and click Let’s get started.

Create Supergraph

After signing in to Apollo Studio, click on ‘Want to connect to a self-managed router’ on the welcome page.

On the ‘Let’s set up your graph’ pop-up:

  • Enter the name for your graph
  • Use the Supergraph architecture (default)
  • Click Next

On the ‘Publish your schema using Federation’ page, click the copy icon to keep a record of the service key.

Publish Subgraph

make publish-subgraphs will prompt you for an APOLLO_KEY and APOLLO_GRAPH_REF that you can obtain from the screen above.

make publish-subgraphs
.scripts/publish.sh
=======================================
PUBLISH SUBGRAPHS TO APOLLO REGISTRY
=======================================

Subgraphs will listen on different localhost ports (4001, 4002, ...)

---------------------------------------
Enter your APOLLO_KEY
---------------------------------------
Go to your graph settings in https://studio.apollographql.com/
then create a Graph API Key with Contributor permissions
(for metrics reporting) and enter it at the prompt below.
>
---------------------------------------
Enter your APOLLO_GRAPH_REF
---------------------------------------
Go to your graph settings in https://studio.apollographql.com/
then copy your Graph NAME and optionally @<VARIANT> and enter it at the prompt below.
@<VARIANT> will default to @current, if omitted.

Enter the <NAME>@<VARIANT> of a federated graph in Apollo Studio:
> very-first-supergraph@current

subgraph: products
---------------------------------------
+ rover subgraph publish very-first-supergraph@current --routing-url http://localhost:4001/graphql --schema subgraphs/products/products.graphql --name products --convert
Publishing SDL to very-first-supergraph@current (subgraph: products) using credentials from the default profile.
A new subgraph called 'products' was created in 'very-first-supergraph@current'
The supergraph schema for 'very-first-supergraph@current' was updated, composed from the updated 'products' subgraph
Monitor your schema delivery progression on studio: https://studio.apollographql.com/graph/very-first-supergraph/launches/7b2efb4d-df8b-4de3-bb8a-588ff2456da1?variant=current
......

Schema is published successfully.

You can view the supergraph build result by clicking on ‘see schema changes’.

You can view the supergraph schema at https://studio.apollographql.com/graph/very-first-supergraph/variant/current/schema/sdl.

Run Supergraph

Start Supergraph Runtime

make run-router

+ ./router --version
1.14.0
+ ./router --dev -c ./supergraph/router.yaml --log info
2023-04-12T03:41:09.158335Z  INFO Apollo Router v1.14.0 // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)
2023-04-12T03:41:09.160933Z  INFO Anonymous usage data is gathered to inform Apollo product development.  See https://go.apollo.dev/o/privacy for details.
2023-04-12T03:41:09.847086Z  INFO Running with *development* mode settings which facilitate development experience (e.g., introspection enabled)
2023-04-12T03:41:10.994704Z  INFO Apollo Studio usage reporting is enabled. See https://go.apollo.dev/o/data for details
2023-04-12T03:41:10.995368Z  INFO Configuring Otlp tracing: BatchConfig { scheduled_delay=5s, max_queue_size=2048, max_export_batch_size=512, max_export_timeout=42s, max_concurrent_exports=1 }
2023-04-12T03:41:11.023307Z  INFO Health check endpoint exposed at http://127.0.0.1:8088/health
2023-04-12T03:41:11.027993Z  INFO GraphQL endpoint exposed at http://0.0.0.0:4000/ 🚀

Query Supergraph from Sandbox

Apollo router has an embedded sandbox. To run following query using the sandbox, open http://localhost:4000/ in a browser.

query Query {
  allProducts {
    id
    name
    sku
    createdBy {
      email
    }
  }
  allPandas {
    favoriteFood
    name
  }
}

Query through API Call

make query

nino@DESKTOP-TMK1GG5:/mnt/d/NewApollo/demo$ make query
-------------------------------------------------------------------------------------------
+ curl -i -X POST http://localhost:4000 -H 'Content-Type: application/json' --data-raw '{ "query": "{allProducts{id,name,sku,createdBy{email}}}" }'
HTTP/1.1 200 OK
apollo-trace-id: 4ef0839e0de77ab755a84601175462f2
content-type: application/json
vary: origin
content-length: 237
access-control-allow-origin: *
date: Wed, 12 Apr 2023 04:00:59 GMT

{"data":{"allProducts":[{"id":"converse-1","name":"Converse Chuck Taylor","sku":"converse-1","createdBy":{"email":"info@converse.com"}},{"id":"vans-1","name":"Vans Classic Sneaker","sku":"vans-1","createdBy":{"email":"info@vans.com"}}]}}
-------------------------------------------------------------------------------------------

Shutdown

use ctrl-c to exit the router.

run docker compose down to shutdown subgraphs

make down

nino@DESKTOP-TMK1GG5:/mnt/d/OldDellXP/NewApollo/demo$ make down
docker compose down --remove-orphans
[+] Running 9/9
 ✔ Container users                       Removed                                                                                                                                                                                                                                                0.8s
 ✔ Container inventory                   Removed                                                                                                                                                                                                                                                1.3s
 ✔ Container reviews                     Removed                                                                                                                                                                                                                                                1.7s
 ✔ Container pandas                      Removed                                                                                                                                                                                                                                                1.2s
 ✔ Container products                    Removed                                                                                                                                                                                                                                                1.1s
 ✔ Container zipkin                      Removed                                                                                                                                                                                                                                                2.9s
 ✔ Container prometheus                  Removed                                                                                                                                                                                                                                                0.7s
 ✔ Container collector                   Removed                                                                                                                                                                                                                                                0.9s
 ✔ Network supergraph-demo-fed2_default  Removed

Conclusion

Congratulations! We have completed our first hands-on tutorial. We enabled Docker and Ubuntu WSL2, installed Subgraph’s Docker containers, created a Supergraph in Apollo GraphOS through the Apollo Studio UI, published the Subgraphs to Apollo GraphOS using the Apollo Rover utility, and executed a query against the Supergraph schema.

We will explore more about composition, telemetry, and router in future blogs.

References

“https://www.apollographql.com/tutorials/voyage-part1”

“https://www.apollographql.com/docs/federation/quickstart/setup”

“https://www.apollographql.com/docs/graphos/quickstart/cloud/”

“https://github.com/apollographql/supergraph-demo-fed2”

“https://www.cyberciti.biz/faq/turn-off-color-in-linux-terminal-bash-session/”

“https://www.youtube.com/watch?v=2ezNqqaSjq8”

Apollo Graphql
GraphQL
Apollo Federation
Docker
Supergraph

--

--

Cloud Journey

Written by Cloud Journey

150 Followers

All blogs are strictly personal and do not reflect the views of my employer. https://github.com/Ronnie-personal

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams