From Zero to Federation in 5 Steps using Cosmo
This guide offers a hands-on introduction to Cosmo using a sample demo repository. You’ll set up the demo subgraphs and Cosmo Router locally, allowing you to start querying right away.
Prerequisites
Node.js (>= 20 LTS)
Docker
Project setup
Clone the example project, which includes two subgraphs (Posts
and Users
) as well as a Router.
The example project is available here: https://github.com/wundergraph/cosmo-demo, or you can clone it with the following command:
Step 1: Install the Cosmo CLI tool
Install the latest version of the Cosmo CLI.
Step 2: Set Up and Run the Subgraphs
The cloned project contains preconfigured subgraphs and a script to run them.
Ensure the script is executable
In the project’s root directory, run this to ensure the start-subgraphs.sh
script is executable:
Start the subgraphs
Run the following command to install dependencies and start the subgraphs in the background:
Verify the subgraphs are running
Once the script finishes, check the subgraphs are running by visiting:
If both load correctly, the servers are running.
Test Queries
You can run the following queries to confirm the subgraphs are functioning correctly.
Posts Subgraph (localhost:4001)
To retrieve all posts, run the following query:
Expected Output:
To retrieve a single post using its id
, run the following query:
Expected Output:
Users Subgraph (localhost:4002)
To retrieve all users, run the following query:
Expected Output:
To retrieve a single user with their id
, run the following query:
Expected Output:
Stop the Subgraphs
You will need to keep the script running in the background for this tutorial, but if it is necessary to stop it, run:
Step 3: Generate the Router Configuration
The repository includes a graph.localhost.yaml
configuration file for the wgc
CLI tool to introspect and generate a router configuration.
Setup Considerations
-
For Docker-based subgraphs, use
graph.yaml
instead ofgraph.localhost.yaml
. -
For custom subgraphs, update the configuration file to match your setup.
Generate the Router Configuration
Open a new terminal and run the following command to navigate to the router
directory.
Then, generate the router configuration by running:
Expected Output:
Step 4: Run the router
While still in the router
directory, start the router using Docker. Make sure Docker is running on your machine before proceeding.
We recommend using Docker to prevent dependency conflicts and maintain a consistent environment.
The router will now be running in a Docker container.
Step 5: Query Against Your Router
Now that the router is running, you can test it by running queries on your federated graph at http://localhost:3002.
Get All Posts with Author Details
Expected Output:
Get a Single Post with Author Details
Expected Output:
All done!
Congrats! You’ve deployed two subgraphs, composed them into a federated Graph, and deployed a Router.
Next, consider deploying to the cloud to enable features like metrics, tracing, and monitoring in Cosmo Studio.