Comment on page
Cosmo Cloud Onboarding
Learn how to deploy your first federated graph and integrate it with your Cosmo Router.
Head over to cosmo.wundergraph.com and create an account. Once you are in, your free trial period begins.
To better understand your use case and ensure that the onboarding process is as smooth as possible, please prepare the following information:
- Send us your Subgraphs. If this information is confidential, you can simply provide us with the names of the federation features you rely on.
- Do you have to migrate from an existing platform like Apollo?
In order to complete this tutorial you need to have Node.js 16 (or higher), npm, and docker installed. This tutorial doesn't provide demo subgraphs. Prepare one before you continue.
Run the following command to install our CLI.
npm install -g wgc@latest
Before you can run any command you need to export the following environment variables to authenticate against Cosmo Cloud. You can obtain an API key from the studio. (You would also have gotten one if you were onboarded)
# You can put this in your .bashrc or .zshrc
export COSMO_API_KEY=${api_key}
# Validate if the key is read correctly
wgc --version
You should see the following output without any warnings:
❯ wgc --version
0.6.1
Run the following command to create your first federated graph:
wgc federated-graph create <graph_name> \
--label-matcher team=A,team=B \
--label-matcher env=production \
--routing-url http://localhost:3002/graphql
I refer to the CLI documentation to explain the parameters in detail but they should be very self-descriptive. Critical is the
routing-url that should point to your deployed router. Don't worry all parameters can be changed later.A federated graph without any subgraph is kind of useless. Let's create a subgraph:
wgc subgraph create <subgraph_name> \
--label team=A env=production \
--routing-url http://localhost:4001/graphql
The last step is to publish the initial schema of your subgraph so we have something to federate.
wgc subgraph publish <subgraph_name> --schema ./schema.graphqls
Before we can start the Cosmo Router, we need to issue a Router token that gives the router permission to communicate with the controlplane. Please run the following command:
wgc router token create <token_name> --graph-name <graph_name>
Keep the token secure and store it permanently.
The following configuration is a minimal working example:
docker run \
--name cosmo-router \
--rm \
-p 3002:3002 \
--add-host=host.docker.internal:host-gateway \
--platform=linux/amd64 \
-e FEDERATED_GRAPH_NAME=$GRAPH_NAME \
-e DEV_MODE=true \
-e LISTEN_ADDR=0.0.0.0:3002 \
-e GRAPH_API_TOKEN=$TOKEN \
ghcr.io/wundergraph/cosmo/router:latest
We don't recommend the latest tag in production because it doesn't point to a fixed version and can introduce breaking changes anytime. You can find all releases here.
Listening on 0.0.0.0 is required in a container network like docker or Kubernetes to expose the application. This is not necessary on bare metal or VM.
Open http://localhost:3002/graphql and issue your first GraphQL operation with WunderGraph Cosmo! 🚀
Let's introduce a change e.g. remove a field in one of your subgraphs to validate that no breaking changes are accidentally released. In order to do so we use the check command:
wgc subgraph check <subgraph_name> --schema ./subgraph.graphql
wgc subgraph check will not update your production router but it creates a check in the Cosmo Cloud Dashboard. This is very useful in PR-based workflows. Test your changes before you release them to production.If you are sure about the change run:
wgc subgraph publish <subgraph_name> --schema ./subgraph.graphql
This will update the subgraph and propagate the federated graph to your routers. It takes around 10s until your Router fetches and serves the latest valid schema composition.
You have successfully connected your Admin Account to Cosmo Cloud. Now it is time to invite your colleagues. Login to cosmo.wundergraph.com and click on Members. You can invite as many people as you wish, and each member will receive an invitation email. Upon accepting this invitation, they must set a secure password to finish the process. After that, they can issue custom API Keys in the API Keys section to connect to Cosmo Cloud as well (See above).
In this tutorial, you have learned how to run your router with a federated graph. I hope you enjoyed it. Now, it's the perfect moment to visit your Dashboard to get meaningful insights into your usage.
Last modified 5d ago