Create a Supergraph

What's about to happen?

We're going to create a supergraph.

Your supergraph is the composite of all your subgraphs, their various data sources and business logic, and when we "build" a supergraph, we create a GraphQL API.

Steps

Required

• The DDN CLI, VS Code extension, and Docker installed

Step 1. Initialize your supergraph

To initialize your supergraph, from an empty directory, run:

ddn supergraph init --dir .

Specifying a directory

Instead of passing a . (the "this" directory specifier) you can pass a directory name to the --dir flag of the supergraph init command to create your supergraph in a specific directory. If it doesn't exist it will be created.

Step 2. Start your supergraph

With the Docker daemon running on your machine, you can immediately start the Hasura Engine, your supergraph and its accompanying services. The following command will take control of the terminal tab in which it's executed and will output log information from the Hasura Engine, and any other services — such as data connectors — that are included in your project's compose file. As such, for subsequent commands, you'll need to open a new terminal tab.

From the project's root, run:

HASURA_DDN_PAT=$(ddn auth print-pat) docker compose up --build --watch

The CLI and the build directory; click here to read how these work.

The CLI automatically creates a build directory for you when running the ddn supergraph init command. This directory contains all of the JSON necessary to configure and serve your supergraph. The JSON files within it are already referenced for you in the docker compose.yaml file, allowing you to start your services straight away.

The docker compose up command sets the HASURA_DDN_PAT environment variable using a value retrieved from the command ddn auth print-pat and then uses Docker Compose to start and monitor the Hasura services defined in the compose.yaml file. Your PAT is your personal access token generated by Hasura DDN and used by the CLI.

You should see your various services returned as Running or Started in the terminal. We also use the --watch flag which will allow us to iteratively modify and test our API locally with blazing-fast feedback loops.

Running the Docker daemon as a non-root user

If you're running the Docker daemon as a non-root user (rootless mode), v26.0 now allows you to disable the default host-loopback-isolation which prevents communication back to the host machine.

To disable this feature, set the environment variable DOCKERD_ROOTLESS_ROOTLESSKIT_DISABLE_HOST_LOOPBACK to false before starting the daemon.

This will now allow container-to-host communication via 10.0.2.2 address.

You should also amend this line in your compose.yaml files for both the main services and connectors to reflect this change:

extra_hosts:
  - local.hasura.dev=host-gateway

to:

extra_hosts:
  - local.hasura.dev=10.0.2.2

Step 3. View your supergraph API

You can now navigate to: https://console.hasura.io/local/graphql?url=http://localhost:3000 and view your (still empty) API running on your own machine using the Hasura Console!

Privacy settings in some browsers

Your browser settings, privacy tools or browser extensions may prevent the Console from accessing your local Hasura instance. This could be due to features designed to protect your privacy and security. Should you encounter one of these issues, we recommend disabling these settings for the console.hasura.io domain.

Chrome and Firefox are the recommended browsers for the best experience with the Hasura Console including for local development.

Step 4. Set the supergraph context

As a feature of convenience, we'll set the context in the CLI which removes the need to set frequently used default values (such as the flag --supergraph or --subgraph) when running CLI commands. This command will save the path of your supergraph.local.yaml to a context file in your .hasura directory.

You could do the same with a subgraph too. But we're going to keep it explicit for now for clarity in this guide.

You can learn more about using context here.

In the project's root directory, run:

ddn context set supergraph ./supergraph.local.yaml

Step 5. Create a new build of your supergraph

Hasura utilizes a system of immutable builds which provide a stable snapshot of your API at any point in your development process. Let's create a new one:

From the project's root, run:

ddn supergraph build local --output-dir engine

The above command regenerates all the JSON for our supergraph. As we passed the local subcommand, and an output directory of engine this will output the files to our local ./engine directory which is referenced in our Docker compose.yaml. We won't see any difference to our deployed API from running this now, but once we start to add subgraphs and data sources we'll need to run this command to update our API.

What did this do?

The CLI created all the files needed for local and cloud development in your local build directory, including a docker compose file for local development and helper files for VS Code. We then started the Hasura Engine and all the services needed to run your supergraph locally and viewed the Hasura Console to see our empty API. Finally, we set the context for our supergraph and created a new build of our supergraph.

Starting a new supergraph or joining an existing one

ddn supergraph init will always be the first command you run when starting a new project. However, you may have arrived here after being invited to join an existing project. In that case, your supergraph will already exist; you can simply clone the repository containing your supergraph and pick up with the next section.

Regardless of how you've arrived at your supergraph, you'll have needed to create a build and then run it using Docker. This is the typical workflow when starting a new project or picking up with an existing one.

Next steps

The most common next step from here is to add a new subgraph.