Docs
Launch GraphOS Studio

Set up a self-hosted supergraph

Host your supergraph in your own infrastructure


This tutorial gets you up and running with and a self-hosted , using the . While you can run the router regardless of your Apollo plan, connecting the router to GraphOS requires an Enterprise plan. If your organization doesn't currently have an , you can test out this functionality by signing up for a free Enterprise trial.

NOTE

This tutorial uses Docker for containerization of your 's .

Supergraph concepts

Before we get started, let's quickly cover what a self-hosted is.

A supergraph combines multiple APIs into a single unified GraphQL service. The individual APIs in a are called subgraphs:

Supergraph
Router
Subgraph A
Subgraph B
Subgraph C
Clients

A separate service called the router sits in front of your and provides the publicly accessible endpoint for your . Clients the , which distributes each query across the appropriate combination of subgraphs and returns the combined result.

The uses a special called the supergraph schema. This schema incorporates the types and in each , along with metadata that enables the to correctly distribute queries across subgraphs.

A self-hosted supergraph is a with a that you host and manage in your own infrastructure. This is in contrast to a cloud supergraph, which uses a that's hosted and managed by Apollo.

We'll cover these concepts in more detail as we proceed through the steps below.

1. Set up Apollo tools

This quickstart uses the following Apollo tools:

  • GraphOS Studio: This is the primary web interface for . Studio helps you monitor, manage, and collaborate on your .
  • The Rover CLI: This is the primary command-line interface for . helps you interact with your graphs and their schemas.

Let's set these up first.

Create an Apollo account

To manage our with , we need an Apollo account. Let's create one if you don't have one yet.

Complete the first step of Get started with GraphOS (Create your Apollo account), then return here.

Create a graph in GraphOS Studio

After you create your Apollo account, create your first in by following these steps:

  1. Go to your organization's Graphs tab in GraphOS Studio.

  2. Click Create New Graph in the top right. Studio displays the following dialog:

  1. Specify an Organization and Graph title for your .

  2. Leave the Graph Architecture as Supergraph (Default).

  3. Click Next. A modal like the following appears:

Schema registration options
  1. Leave the Supergraph Pipeline Track dropdown set to its default value.

Your has been created!

Install the Rover CLI

Rover is Apollo's CLI for managing all kinds of , including and . We'll use it throughout this quickstart.

NOTE

Even if you already have installed, you should update your version now by completing this step.

Install the latest release with the appropriate command for your system:

Mac/Unix
curl -sSL https://rover.apollo.dev/nix/latest | sh
Windows
iwr 'https://rover.apollo.dev/win/latest' | iex

After installing, run rover in your terminal with no to confirm that it installed successfully. Verify that the printed version number matches the latest full release (if it doesn't, you might need to manually delete a previous outdated installation).

Authenticate Rover with GraphOS

We'll use to publish our to . To do that, we first need to authenticate Rover with GraphOS.

Complete the first two steps of Configuring Rover (Obtain an API key and Provide the API key to Rover), then return here.

2. Clone the router project template

For this quickstart, we'll use some Apollo-hosted example services as our , and we'll set up the in front of them. The Apollo Router is a high-performance, precompiled Rust executable that acts as the router for a .

First, let's create a project directory for your :

  1. Open this GitHub template. It provides out-of-the box configuration for deploying and running the via a Dockerfile.
  2. On the template page, click Use this template > Create a new repository to copy the template into a new repository in your GitHub account.
    • If you don't use GitHub, you can instead clone the template directly via the Code menu.
  3. Clone your new repository to your local machine.

3. Start the router with Docker

To run the locally, you need a way to build and run containers. Here are some popular options:

NOTE

This tutorial uses the docker command. Alternative commands usually look similar.

Try building and running your container:

docker build -t router .
docker run -it -p4000:4000 router

When you do, you'll get a startup error message like the following:

That's because we aren't currently providing a to the ! We'll fix that soon.

4. Obtain your subgraph schemas

NOTE

This quickstart uses two Apollo-hosted (named locations and reviews) from an imaginary space tourism application called FlyBy. Here are their URLs and schemas for reference:

If you have your own existing that you want to use instead of these examples, feel free! Provide their names and URLs wherever you see the example subgraphs used in the steps below.

To compose a for our , needs the following information about each of our :

  • The 's schema
  • The URL of the 's endpoint (which must be accessible by the )

Fortunately, we have all this information! Let's send it to .

5. Publish your subgraph schemas

Because we've already configured the , we can now use its subgraph publish command to publish our to .

In GraphOS Studio, click the you created back in the first step. Because we haven't published any schemas to it yet, the following dialog appears:

Schema registration options

To publish our , we'll first use to introspect the running subgraph, then pass the obtained schema to subgraph publish.

  1. Paste the following multi-line command into your terminal, but don't run it—you need to modify it first.

    rover subgraph introspect https://flyby-locations-sub.herokuapp.com/ | \
    rover subgraph publish --name locations \
    --routing-url https://flyby-locations-sub.herokuapp.com/ \
    --schema - <GRAPH_REF>
  2. In your terminal, replace the final value <GRAPH_REF> with the appropriate value for your . In the screenshot above, this value is MyGraph-1ncyus@current, but your value will be different.

  3. Run the modified command.

    • If the command is successful, you'll see output like the following:

      A new subgraph called 'locations' was created in 'docs-example-graph@main'
      The supergraph schema for 'docs-example-graph@main' was updated, composed from the updated 'locations' subgraph
    • If the command fails, make sure you've authenticated Rover with GraphOS. All commands that interact with require a valid API key.

    If you open your 's details in Studio now, you'll see types and from the locations listed on the Schema page:

    locations subgraph schema in Studio
  4. Do the same thing for the reviews , again substituting your :

    rover subgraph introspect https://flyby-reviews-sub.herokuapp.com/ | \
    rover subgraph publish --name reviews \
    --routing-url https://flyby-reviews-sub.herokuapp.com/ \
    --schema - <GRAPH_REF>

    You only need to provide a 's --routing-url the first time you publish that 's schema to a particular (unless you need to change that URL later).

    If you refresh the Schema page in Studio, you'll now see types and from the reviews as well.

Every time we publish a , automatically composes all our subgraph schemas into a ! However, our isn't yet fetching that schema from Apollo. We'll tackle that next.

6. Connect the router to GraphOS

It's time to enable our to fetch its from . To do that, we need a graph API key that we set as the value of an environment variable.

💡 TIP

We recommend that you create a separate API key for each system that communicates with . This reduces the impact whenever you need to replace an API key that might be compromised.

  1. Obtain a API key for your Studio graph by following these steps:

    If you have an , set the API key's role according to the following:

    • If your will use a protected variant, choose Graph Admin.
    • Otherwise, choose Contributor.

    💡 TIP

    Make sure to copy and paste the API key's value somewhere so you can reference it. For security, API keys are not visible in Studio after creation.

  2. Create a file called .env in your project and paste in the following (replace <API_KEY> with your API key and <GRAPH_REF> with your ):

    APOLLO_KEY=<API_KEY>
    APOLLO_GRAPH_REF=<GRAPH_REF>

    ⚠️ CAUTION

    API keys are secret credentials. Never share them outside your organization or commit them to version control. Delete and replace API keys that you believe are compromised. Make sure always to add .env files to your .gitignore file. The template project already does this.

  3. Paste this command into your terminal and run it:

    docker run -it --env-file .env -p4000:4000 router

    This time there's no error, and you'll see output similar to the following (timestamps omitted for brevity):

    By providing an API key to the , you also automatically enable metrics reporting to , enabling you visualize your graph's performance. Learn more about metrics.

Now that our is running, we can quickly open our browser to localhost:4000 to explore our composed schema in :

Schema view in Apollo Sandbox

Let's execute some test queries against the . We'll look at metrics for those test queries in the next step.

7. View operation and field metrics

Because our is connected to , it automatically collects and reports metrics on incoming and their . You can then visualize those metrics in Studio.

Return to GraphOS Studio and go to your 's Insights page, which looks like this:

The Insights page in GraphOS Studio, showing metrics for operations and their fields

Within a few minutes, the test queries you executed in the previous step should be represented on this page. The Insights page is vital to monitoring your 's performance across all your clients that the .

Learn more about the available metrics in the metrics documentation. Expand the summary table below to learn more about the other pages in Studio.

Variant pages in Studio

8. Deploy your router and connect clients

Now that our is running successfully in our development environment, we can deploy it to our preferred platform (AWS, Google Cloud, etc.) so clients can begin it!

The exact details for deploying the depend on which platform you use, but these high-level steps hold true for most platforms:

  1. Build the Docker image in CI and push it to a container registry (some providers let you skip this step).

  2. Deploy the image to your preferred platform (there are additional resources for Kubernetes deployments).

  3. Set the APOLLO_KEY and APOLLO_GRAPH_REF environment variables in the 's deployment environment, as we did locally in this step.

    • Keep in mind that APOLLO_KEY is a secret, so use an appropriate mechanism for storing it in your deployment environment.
  4. If your platform expects the to listen on a particular port, set this port in the router.yaml file included with the template:

    router.yaml
    supergraph:
    # The socket address and port to listen on
    listen: 127.0.0.1:4000
    # OR if the port is specified via environment variable
    listen: 127.0.0.1:${env.PORT}

    💡 TIP

    Learn more about router configuration options.

After you successfully deploy your , it's ready to start receiving client ! If you have any existing client applications that connect directly to your API, you can update their GraphQL endpoint URL to your router's URL.

Similarly, any new client applications should use your 's URL.

NOTE

  • For browser-based clients, make sure their origin is allowed in your 's CORS rules, which you can set in the router's YAML configuration file.
  • Only update clients that communicate with the correct instance of your API! For example, if your API has staging and production instances, only update clients that communicate with the instance used by this .

Next steps

Nice work! We've registered two with , and we've set up a that fetches its composed so it can execute across subgraphs.

If we now publish changes to one of our , our running automatically fetches the corresponding changes to the (assuming succeeds).

Next, we'll cover some of the most common and important actions to perform on your new , including:

  • Updating s
  • Adding another
  • Setting up

Go to next steps.

Previous
Cloud setup
Next
Next steps
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company