2. Monolith graph setup


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

  • Learn how the backend is organized
  • Learn what services and the server uses
  • Have both the server and client running on our local machine
  • Set up the on
  • Set up the


Our app uses Node.js on the backend and React on the frontend. We recommend using the latest LTS version of Node. To check your Node version, run node -v.

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 directory you're working on as we go through the course.

Airlock is split up into two different repos, one for the 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
┣ πŸ“‚ 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.

    npm install

    This also triggers an install for the services packages.



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:

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!


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

Data sources

Our uses 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 's methods in our , but we won't need to create any new methods!

Running the GraphQL server

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

Our server uses two pieces that are important to our :

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

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

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.


Testing a query with Sandbox

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

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

Your should look like this:

query GetAllAmenities {
listingAmenities {

When we run the , 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".

The Apollo Sandbox Explorer, showing a query for Amenities data

Feel free to play around with other queries, but note that not all of them may work! Some 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 GraphOS

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

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

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


Creating a new graph in Apollo Studio

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


Creating a new graph in Apollo Studio

Note: If you don't see the modal above, you may be on the wrong plan.

Check your plan: Part of this course covers the self-hosted router, which requires a GraphOS Enterprise plan. You can still follow along if your organization is on a different plan, but you won’t be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free Enterprise trial.

From here, we have a few ways to register our schema. First, let's take note of two environment variables shown in the modal, APOLLO_KEY and APOLLO_GRAPH_REF:


The Publish your schema modal, showing our graph's environment variables

Let's create a .env file in the monolith directory to store these.

πŸ“‚ 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 , 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.


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! 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.


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.


Schema reference page

To test things out, head over to Explorer and run the previous again!

query GetAllAmenities {
listingAmenities {

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


Connection settings endpoint

And we should get data back!


Connection settings endpoint

Graph setup

Setting up the Rover CLI

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

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

is Apollo's command line interface (CLI) tool that helps developers work with and interact with .


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:

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

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 !


Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.