In this workshop, we'll explore how to implement real-time use cases with federated GraphQL subscriptions in GraphOS. You'll gain hands-on experience running subscription operations in a federated graph and learn different techniques for scaling and optimizing performance.

What you'll learn

• How to enrich real-time data experiences with federated subscription operations
• Architecture recommendations for scaling and improving performance
• How to observe subscription operations and their performance impacts

Who this workshop is for

• Backend developers with hands-on experience of GraphQL. Knowledge of federation is recommended but not required.

Workshop resources

• Workshop slides PDF
• Workshop project repo
• Workshop companion

⚠️ Before the workshop...

If you have any questions or run into any issues with the workshop prep below, scroll to the end of this page to leave a comment or send us an email at summit@apollographql.com. We're here to help!

You will need to complete the following:

Please make sure to complete the above steps before continuing on.

You'll also need to do the following:

• Clone the course repository
• Download the router binary
• Create a graph in GraphOS Studio
• Publish the subgraph schemas for the messages and accounts subgraphs

Let's walk through those steps now.

Clone the repo locally

1. Clone the repo.

   https://github.com/apollographql-education/federated-subscriptions-workshop-2024.git

   Copy

2. Open it up in your code editor (we recommend VS Code).

   📦 federated-subscriptions-workshop-2024
   ┣ 📂 accounts
   ┣ 📂 messages
   ┣ 📂 router
   ┣ 📄 .gitignore
   ┗ 📄 README.md

This repository contains two GraphQL servers—messages and accounts—which will become the first subgraphs in our federated graph. We'll spend most of our time in the messages directory, however we'll still need accounts up and running as well.

Set up accounts

1. Navigate to the accounts directory.

2. Install the dependencies.

   accounts

   npm install

   Copy

3. You should see some output in the terminal:

   > npx prisma migrate dev
   
   Prisma schema loaded from datasources/prisma/schema.prisma
   Datasource "db": SQLite database "dev.db" at "file:./dev.db"
   
   Already in sync, no schema change or pending migration was found.
   
   ✔ Generated Prisma Client (v5.19.1) to ./node_modules/@prisma/client in 90ms

   By default, our database is pre-seeded and ready to go. If anything goes wrong along the way, look for the datasources/prisma/dev.db file and delete it. Then, in the terminal, run npx prisma migrate dev to reset the database.

4. Run the accounts subgraph.

   accounts

   npm run start

   Copy

5. You'll see some output that our accounts server is running on port 4002.

   accounts

   🚀 Subgraph accounts running at http://localhost:4002/

Set up messages

We'll follow the same process for messages.

1. Navigate to the messages directory.

2. Install the dependencies.

   messages

   npm install

   Copy

3. As part of the postinstall process, our Prisma database gets seeded with starter data. You'll see some output in the terminal to that effect:

   Running seed command `ts-node src/datasources/prisma/seed.ts` ...
   {
     captain: { username: 'dallas', name: 'Captain Dallas', role: 'guest' },
     xenomorph: { username: 'xeno', name: 'Xeno', role: 'host' },
     ripley: { username: 'ripley', name: 'Ellen Ripley', role: 'guest' },
     kane: { username: 'kane', name: 'Gilbert Kane', role: 'guest' },
     confrontation: { id: 'xeno-ripley-chat', openedTime: 2024-09-27T21:09:20.387Z }
   }
   
   🌱  The seed command has been executed.

   In the messages/src/datasources/prisma directory, there should now a dev.db file.

4. Run the messages subgraph.

   npm run dev

   Copy

5. You'll see some output that the messages server is running on port 4001.

   messages

   🚀  Subgraph airlock-messages-subgraph ready at http://localhost:4001/

Set up the router

1. Create a new file called .env in the router directory. We'll use this file to store values we need to run the router.

   📂 router
   ┣ 📄 .env
   ┗ 📄 router-config.yaml

2. Open up a new terminal and navigate to the router directory.

3. Install the router binary.

   router

   curl -sSL https://router.apollo.dev/download/nix/latest | sh

   Copy

   Note: For alternate methods of downloading the router, please check out the official Apollo documentation.

4. You'll now have the router binary file in the directory.

   📂 router
   ┣ 📄 .env
   ┣ 📄 router
   ┗ 📄 router-config.yaml

Set up your graph

If you haven't already, please join the GraphOS Studio organization to complete this step.

• Don't have an Apollo account yet? You'll be prompted to create one when clicking the link.
• Are you an existing Apollo customer? You will need to join with an email address not associated with your company's SSO login.

1. Go to our workshop's Studio organization.

2. Click + Create new graph.

3. For the graph title, we recommend typing in your full name (or GitHub username) so you can easily find it later. This organization is shared between all workshop participants so you'll want a graph title that's easily searchable and identifiable for yourself.

   Keep the architecture as Supergraph, then click Next.

   https://studio.apollographql.com

   

4. Next, we'll see a modal for publishing our schema. Keep the federation version as 2.7!

   https://studio.apollographql.com

   

5. Scrolling down, in the codeblock at the bottom of the modal, take note of two pieces of data: the APOLLO_KEY (you can toggle the whole value on and off using the eye icon at the top of the codeblock) and the value that follows rover subgraph publish. This is your APOLLO_GRAPH_REF.

   https://studio.apollographql.com

   

6. Store both of those values in the router/.env. It should look something like this.

   router/.env

   APOLLO_KEY=service:your-graph-details:random-string
   APOLLO_GRAPH_REF=federated-subscriptions@current

   Copy

Publish subgraph schemas

1. Navigate to the messages directory in the terminal.

2. Run the rover subgraph publish command below, substituting in your own values for APOLLO_GRAPH_REF.

   Publishing the messages subgraph

   rover subgraph publish <APOLLO_GRAPH_REF> --name messages --schema ./src/schema.graphql --routing-url http://localhost:4001

   Copy

3. You'll see the following message: The host localhost is not routable via the public internet. Continuing the publish will make this subgraph reachable in local environments only. Would you still like to publish? [y/N]. Type y then hit Enter.

1. Navigate to the accounts directory in the terminal.

2. Run the rover subgraph publish command below, substituting in your own values for APOLLO_GRAPH_REF.

   Publishing the accounts subgraph

   rover subgraph publish <APOLLO_GRAPH_REF> --name accounts --schema ./accounts.graphql --routing-url http://localhost:4002

   Copy

Running the router

Before continuing on, make sure both messages and accounts subgraphs are still running.

1. Navigate to the router directory in the terminal.

2. Run the command below, substituting in your own values for APOLLO_GRAPH_REF and APOLLO_KEY.

   router

   APOLLO_KEY=your-apollo-key \
   APOLLO_GRAPH_REF=your-apollo-graph-ref \
   ./router \
   --config ./router-config.yaml

   Copy

You'll see some output in the terminal - then a confirmation that the router is running on http://127.0.0.1:4000!

Quickstart on Workshop Day

To get everything running on the day of the workshop, here's a quickstart.

First, start up messages.

Next, accounts.

Finally, boot up the router, substituting in your own values for APOLLO_GRAPH_REF and APOLLO_KEY.

And that's all you need! We'll see you at Summit!