Run Cosmo Locally with Docker | GraphQL Federation by WunderGraph - WunderGraph

Run the complete Cosmo stack locally in minutes

Clone the repository, run one command, and have a fully functional GraphQL federation environment running on your machine. Perfect for evaluation, local development, and CI integration testing.

Not for production. For production, use Kubernetes with Helm or Cosmo Cloud.

The problem

Getting a federation platform running locally should not take half a day

Evaluating and developing against a federation platform requires the full stack. Setting up individual components manually is slow, inconsistent, and hard to reproduce.

Evaluating a federation platform takes too long

Setting up a control plane, schema registry, and router individually before running a single query discourages thorough evaluation. Teams need a faster path to hands-on testing.

Local development environments diverge from production

Without a consistent local stack, developers test against simplified setups that miss important behaviors. Bugs surface in staging rather than development.

CI integration tests need a real federation environment

Mocking a federation control plane in CI misses real composition and routing behavior. Full integration tests require the actual platform stack.

Our solution

One command, complete platform

The official Docker Compose configuration starts every Cosmo component with pre-configured networking and dependencies. Clone the repo and follow the Getting Started guide.

Getting started

  1. Clone the Cosmo repository from GitHub.
  2. Follow the Getting Started instructions to run the startup command.
  3. Docker Compose pulls all container images and starts every platform component.
  4. Access Cosmo Studio in your browser to create federated graphs and publish subgraph schemas.
  5. Connect your local subgraph services to the running federation environment.
  6. Use the full local stack for development, testing, and CI integration before deploying to production.

For evaluation, development, and CI. Not for production.

Before & After

Before Docker Compose With Docker Compose
Manual component installation and dependency management Single command starts the complete stack
Hours of setup time before first GraphQL query Running in minutes
Environment inconsistencies between team members Reproducible local environment from one repository
Difficulty evaluating the platform without infrastructure Hands-on exploration in under an hour

What's included

Full stack in containers

Control Plane, Cosmo Studio, Router, GraphQL Metrics, OTEL Collector, CDN, PostgreSQL, ClickHouse, Redis, Keycloak, Minio

All components pre-configured to communicate on a shared Docker network.

How Docker Compose works for Cosmo

01 One repository, everything included.

Clone

Clone the Cosmo repository from GitHub. The Docker Compose configuration and Getting Started script are included in the repository root.

02 All components start together.

Start

Follow the Getting Started instructions to run the startup command. Docker Compose pulls all images and starts every platform component on a shared Docker network.

03 Full Studio available locally.

Explore

Access Cosmo Studio in your browser. Create federated graphs, publish subgraph schemas, run queries in the playground, and inspect analytics.

04 Local subgraphs connect directly.

Develop

Connect local subgraph services to the running federation environment. Iterate on schema changes and test composition locally before pushing to production.

Use cases

When to use Docker Compose

The right tool for development, evaluation, and testing.

Platform evaluation

Try the complete Cosmo Platform hands-on before committing to a production deployment. Full Studio, schema registry, and router available locally.

Local development

Develop subgraph changes against a full local federation environment. Catch composition errors and routing issues before they reach staging.

CI integration testing

Spin up the full stack in CI environments that support Docker. Run integration tests against real federation behavior, not mocks.

Demos and proofs of concept

Show the platform to stakeholders without requiring cloud access. Every feature of Cosmo runs locally from the same Docker Compose configuration.

Run Cosmo on your machine

Clone the repository and follow the Getting Started guide. The full platform runs in minutes.

FAQ

Docker questions

Is the Docker Compose stack intended for production?

What components does the Docker Compose stack include?

Where can I find the Docker Compose file?

What are the system requirements?

Can I use the Docker stack in CI pipelines?

How do I connect my local subgraph to the stack?

Read the full guide in the Docker documentation.