2. Monolith graph setup
9m

Overview

In this lesson, we'll get our development environment set up and Airlock up and running as a monolith graph. By the end of this lesson, we will:

  • Learn how the backend GraphQL server is organized
  • Learn what services and data sources the server uses
  • Have both the server and client running on our local machine
  • Set up the graph on Apollo Studio
  • Set up the Rover CLI

Prerequisites

Our app uses Node.js on the backend and React on the frontend. You'll need to have at least Node version v16.9.1 and npm version 7.21.1.

Note: The examples in this course use npm, but you're welcome to use yarn if you prefer.

You'll also need to be comfortable with running commands in the terminal, such as navigating between directories and running scripts.

Additionally, we'll be working with files with the same name (schema.graphql, or index.js) but are located in different directories. Keep an eye on which file in which subgraph directory you're working on as we go through the course.

Airlock is split up into two different repos, one for the GraphQL server backend and another for the frontend web client.

Running the backend

Let's start with the backend server repo!

  1. Clone the repo.

    git clone https://github.com/apollographql/odyssey-voyage-II-server

There's a lot going on in this server, so let's take a deeper look at the folders and services we're working with.

The structure of the server looks like this:

📦 odyssey-voyage-II-server
┣ 📂 final
┣ 📂 monolith
┣ 📂 router
┣ 📂 services
┣ 📂 subgraph-template
┣ 📄 .gitignore
┗ 📄 README.md

We'll go over each directory and its purpose in the following sections!

  1. Navigate to the monolith directory, and install the required packages.

    monolith
    npm install

    This also triggers an install for the services packages.

Task!

Services

There are five different services required to run Airlock: accounts, listings, bookings, reviews and payments. These services are a mix of REST and direct database services. For the purposes of this course, most of these services will be run locally on your own computer (with the exception of the payments service). This means you'll be able to play around with Airlock features and data in a semi-isolated environment!

Note: For simplicity's sake, all locally-run services are located in the same repo. In a real-world scenario, each of these is more likely to be located in a different repo and owned and maintained by a different team.

ServiceDescriptionType of data sourceHosting
AccountsManages users, their roles, and their profiles.REST APIRun locally on port 4011
ListingsManages listing details, listing ownership, and amenities.REST APIRun locally on port 4010
BookingsManages bookings for listings.SQLite databaseAccessed locally
ReviewsManages reviews about hosts, guests, and listings.SQLite databaseAccessed locally
PaymentsManages user wallet amounts and payments.REST APIHosted for you

Running the services

To run our services, we can use a launch script that's available in monolith/utils/launch.js. This script takes care of starting up all the services hosted locally.

In a new terminal in the monolith directory, run:

monolith
npm run launch

We'll see a bunch of output come up in the terminal. Each message is prefixed with a color-coded label identifying which service or server the message belongs to. The accounts, listings, bookings, and reviews services should now be running!

Task!

We won't be modifying anything in the services directory!

Data sources

Our GraphQL server uses data sources to connect and communicate with each service. Here's a quick summary of each data source:

  • AccountsAPI: a RESTDataSource that connects to the accounts service
  • PaymentsAPI: a RESTDataSource that connects to the payments service
  • ListingsAPI: a RESTDataSource that connects to the listings service
  • BookingsDb: a custom DataSource class that connects to the bookings service using Sequelize
  • ReviewsDb: a custom DataSource class that connects to the reviews service using Sequelize

We'll be making use of each data source's methods in our resolvers, but we won't need to create any new methods!

Running the GraphQL server

We're using Apollo Server, which is initialized in monolith/index.js.

Our server uses two pieces that are important to our graph:

  • the schema (located in schema.graphql)
  • the resolvers (located in resolvers.js)

In a new terminal window in the monolith directory, run:

monolith
npm start

Our monolith server should now be running on http://localhost:4000! We're using nodemon for these start scripts so any changes we save to our code will also automatically restart the server.

If you need to manually stop the process for whatever reason, you can press CTRL+C to do so.

Task!

Testing a query with Sandbox

Let's test out our Airlock graph! When we open up http://localhost:4000 in the browser, we can query the graph using Apollo Sandbox.

In Sandbox, we'll build a query to retrieve all the amenities that a listing can provide. From the sidebar on the left, we can choose the listingAmenities field. Then for each amenity, we want to retrieve its category and name. Finally, let's rename the query to GetAllAmenities so it describes what it does.

Your query should look like this:

query GetAllAmenities {
listingAmenities {
category
name
}
}

When we run the query, we'll see the results populate on the right-hand section. We can see there are a number of different amenities available for categories like "Accommodation Details", "Space Survival", and "Outdoors".

http://localhost:4000
The Apollo Sandbox Explorer, showing a query for Amenities data

Task!

Feel free to play around with other queries, but note that not all of them may work! Some fields are protected and can only be accessed with the correct authorization permissions. We'll take a look at how to set those later on in the course.

Publishing the graph to Studio

Let's make sure this graph and our schema are published to the registry on Apollo Studio. While Sandbox is great for quickly running queries against our local graph, we're going to want the full Studio experience to explore our supergraph, using managed federation.

First, let's get our graph set up in Apollo Studio with a monolith architecture. This is Airlock's starting point, after all!

We can create a new graph by clicking the + New Graph button in the upper right corner of the dashboard.

Note: Depending on when you created your account and what plan you're on, your Studio account might look a bit different than what we're showing in the video or lesson instructions.


Before continuing with the lesson, expand the section below to find your specific steps on how to create a graph.


We'll publish our schemas to the graph we create here, so give it a helpful name. Change the Graph Architecture to Monolith. Then click Next to move to the next step.

studio.apollographql.com
Creating a new graph in Apollo Studio

From here, we have a few ways to register our schema. We're going to upload our schema to Studio in just a moment, but we first need to take note of two environment variables shown in the modal, APOLLO_KEY and APOLLO_GRAPH_REF:

studio.apollographql.com
The Publish your schema modal, showing our graph's environment variables

Let's create a .env file in the monolith directory for just this purpose.

📂 monolith
┣ 📂 datasources
┣ 📂 node_modules
┣ 📂 utils
┣ 📄 .env
┣ 📄 index.js
┣ 📄 package.json
┣ 📄 resolvers.js
┗ 📄 schema.graphql

Copy your APOLLO_KEY and paste it in monolith/.env. Because it's an API key to your graph, it'll disappear from this page once we've finished setting up our schema. You can also jot down your APOLLO_GRAPH_REF in the .env file for later use.

monolith/.env
APOLLO_KEY=your-graphs-apollo-key
APOLLO_GRAPH_REF=your-graph-name@current

Warning: For security, environment variables should never be committed to version control. For this reason, this project includes a .gitignore file which specifies that the .env file should be ignored when committing code changes to a repository.

With our environment variables saved, we're ready to share our schema with Apollo Studio. Click the Local Schema button in the modal. This opens up a text area where we can paste in our existing monolith schema.

Navigate to the schema.graphql file inside of the monolith directory, and copy the entire schema. Back in Studio, paste the copied schema into the text area.

studio.apollographql.com
The Publish your schema modal, showing the Local Schema text area where we can copy and paste our monolith schema

Click Upload to submit your schema. When the page refreshes, we should see an overview of all of our types on the Schema Reference page. To test things out, head over to Explorer and run the previous query again!

Note: The first time you try to run the query, Explorer will prompt you for the URL of your production server! We'll set the Endpoint value to http://localhost:4000.

query GetAllAmenities {
listingAmenities {
category
name
}
}

Studio graph setup

Setting up the Rover CLI

Rover is Apollo's official command line interface, and plays a central role in every supergraph. We'll use Rover commands to publish our subgraph schemas to the Apollo registry.

If you haven't installed Rover from the previous course, refer to the instructions below!

Since this is a new graph we're working on, make sure you re-authenticate Rover with the correct APOLLO_KEY.

In a terminal in the root of the project, run the following command:

rover config auth

This command prompts us to enter the value of APOLLO_KEY. Paste the value from the .env file. (The terminal won't show the actual value when you paste it. It is a secret, after all!)

Note: If you ever lose your API key, don't worry! You can generate a new key from your graph's Settings tab. You will have to reauthenticate with the new key by running rover config auth again.

The message "Successfully saved API key." in our terminal output tells us that authentication was a success! Now that Rover has been authenticated with our graph in Studio, we can register our subgraph schemas.

Task!

Running the frontend

Time to get the web app up and running!

  1. In a new terminal window, outside of the server repo we set up previously, clone the frontend client repo.

    git clone https://github.com/apollographql/odyssey-voyage-II-client
  2. Navigate to the root of the project directory, and install the packages.

    npm install
  3. Run the app.

    npm start

This should open up http://localhost:3000 in the browser. You'll see something that looks like this:

http://localhost:3000
Screenshot of Airlock homepage running in the browser at localhost:3000, showing the check-in and check-out date inputs and a dropdown for number of beds

Task!

You can use Airlock as either a guest or a host by clicking Log In on the top right and selecting the appropriate option. We also have additional account login options for you to choose from, but generally we'll stick with the main Guest or Host buttons.

To switch to a different account after logging in, click the profile picture on the top right of the page and "Log out".

Screenshot of the Airlock login page showing the login options

Up next

And we're all set! Note that we'll be working primarily in the server repo for the course. Now with our development environment running, we can start federating our monolith graph!

Previous
Next