One of the best parts of my job is helping Cycle users explore self-hosting options on the platform.

This time, I had the pleasure of working with Dgraph (now a part of Hypermode). If you haven't heard of it, Dgraph is a distributed, horizontally scalable graph database that gives you a native graph storage/compute engine with distributed ACID transactions (via Raft and snapshot isolation) and first-class GraphQL. You define a GraphQL schema, Dgraph generates the API and uses its graph engine under the hood; it also exposes its native DQL query language when you need low-level power.

Basic Dgraph Use Cases

• Real-time app backends with GraphQL
  When your team wants to ship a GraphQL API without writing resolvers or an extra service layer. Dgraph generates queries/mutations directly from your schema and serves them at scale. This is great for product teams that want to iterate quickly while keeping a strong graph core.

• Knowledge graphs & entity resolution
  Dgraph’s native graph model (triples, facets, and predicates) works well for richly connected data, letting you model entities and relationships (plus relationship attributes) without join explosions. Useful for catalogs, customer 360, and identity graphs.

• ReBAC/authorization graphs and access control
  Relationship-based access models map naturally to graphs; Dgraph’s low-latency traversals + transactions help when permissions change frequently and must be enforced in reads.

• Connected User Insights and Personalization
  Multi-hop traversals (friends-of-friends, “users similar to X”) are first-class in a graph engine and avoid complex JOINs or application-side stitching. Dgraph is designed for real-time user-facing queries over large datasets.

Today, we'll start with a simple deployment and move all the way through deploying a full 6-container cluster on Cycle.

Dgraph Building Blocks

The two main pieces of Dgraph are zero and alpha nodes. You'll need a minimum of 1 of each to actually get things working. Alpha nodes act as the data plane and zero nodes as the control plane. Outside of these two primary building blocks, Dgraph offers a web UI and a CLI.

Initial Setup

Ok, so we know what the zero and alpha nodes are, how do we get this up and running with single nodes, and then how do we cluster?

For the initial setup, we'll need:

1. A couple of servers networked together to mimic a semi-real-world scenario.
2. A way to deploy containers to those nodes.
3. Control over the container's startup command that can override the default.

And then for clustering:

4. A way to provide the containers with individual configuration files at runtime.
5. A way to check the status of the cluster.
6. A tool to create an as-code artifact for the cluster so that it can be replicated in new environments and the configuration can be codified.

1. Networked Servers

If you haven't worked with Cycle before or you're new to the platform, let me quickly introduce how we'd get from a brand new hub to networked servers.

First, we would add a provider under the hub integrations section of the hub. This gives us the ability to provision infrastructure through Cycle using that provider's API. When provisioning the servers, you'll be asked to select a cluster , which is how the platform provides logical groups to separate infrastructure. Deploy a few servers to the same cluster (technically, you can do just one, but it might be more fun to do 2-3), and when those servers come online, we can network them together through Cycle environments .

Once you create the environment, your networking job is done. Want to put things to the test? Deploy servers from multiple providers, or if you don't have access, use multiple regions within your provider. Cycle doesn't care where the nodes are - what provider, if they're on prem or in a colo, etc - the networking happens the same way due to platform layer compute standardization.

Today I'll be working out of an environment with servers at three different providers.

2. A Way to Deploy Containers

With the environment created and the network available, we need a quick way to test out our MVP deployment of 1 alpha and 1 zero container.

First, create a DockerHub image source and then import a copy of the dgraph:v25.0.0 official container. From there, we can use the deploy container to get these two containers online, quick and dirty style. When we move to clustering, I'll introduce stacks and show a more granular configuration pattern.

The way I've configured deploying both alpha and zero is almost identical outside of the hostnames.

Two quick notes:

1. If you want to make sure zero and alpha end up on different nodes, feel free to use server tags .
2. In order for the nodes to talk, the discovery service needs to be running. If you haven't used Cycle before, you can manually start through the management modal or by using "Start All" at the top of the environment.

3. Override and Use Proper Startup

The image that Dgraph provides is nice in the fact that it's a single image that you can start both alpha and zero from. The way it's set up means that we'll have to provide it with a startup command so it knows what we want it to do. The way to do this on Cycle is through the override configuration settings .

Override supports both a path and an args field. The path is meant to be the path to the binary or executable to run with the startup, and the args are… the arguments. In this case, we will use the following:

Zero Override

Path: dgraph
Args: zero --my=zero:5080

Alpha

Path: dgraph
Args: alpha --my=alpha:7080 --zero=zero:5080 --security=whitelist=::/0

The zero instance must be started first. The zero in my=zero:5080 refers to the hostname of the zero instance, and this pattern is used in both the alpha and the zero. The same applies to the alpha instance my field and the corresponding zero entry for that container. The security whitelist simply allows all IPv4/IPv6. This guide doesn't get into setting this up with tight constraints, but the Dgraph docs do dive into this pretty well. The docs also cover setting up TLS, etc.

After starting the zero instance, go to the containers instance console to make sure everything has started correctly, and do the same for the alpha instance.

That's all you need for a basic setup of Dgraph. Next, we'll talk about setting up a cluster.

4. Providing Config Files at Runtime

Modifying startup commands manually is great for individual containers, but when you get a bit closer to the real-world setup, you'll want something that can be easily applied to an environment and artifacted "as-code". For this, we will use Cycle stacks .

I've gone through the process of creating a ready-to-use stack here that is publicly available. If you open the stack and look through it, you'll see some very distinct changes from the 2-container basic setup we just walked through. The first and arguably most important change is the inclusion of the configuration files as scoped variables . Cycle exposes scoped variables as a flexible way to associate environment variables and files with one or more containers. In this case, we'll be using the file type scoped variable to mount the configuration file for each container.

You may also notice that the override command has changed to facilitate the config file start instead of relying on inline configuration. Technically, either is fine, but with clustering stateful workloads, I try to keep configs either as part of the container or add them in through scoped variables, as it's a much cleaner workflow to update and manage them.

To dive deeper into the configs provided or learn more about the "6-node cluster" check out this page from Dgraph .

Quick Cycle Stack Refresher and Resources

If you haven't used Cycle stacks before, here are the steps to go from the git repo through deploying to an environment.

1. Create the stack using the git repo option .
2. Generate a build of the stack.
3. Deploy the stack to your environment.
   1. Make sure to click the "Add New" option on the deploy form for scoped variables.

Feel free to remove the containers we created earlier before deploying. This will be a must-do if you have used the hostname zero-1 or alpha-1, unless you have experience and can navigate the deployment changes needed to make that work.

5. Checking Cluster Status and Success

After deploying the stack, make sure to manually start the discovery service if it's not already running. The zero and alpha containers will need to resolve IP's from each other using DNS, and discovery facilitates this.

Once discovery is running, the first container to start is zero-1. You can check this and future instances by checking the console output from the container instance console . Once zero-1 is up, you can start the other two zero containers. When all three have been successfully started and you see a message in the console about the zero containers learning of each other and electing leaders, etc, you can start the alpha nodes. Follow the same process of checks for the alpha, and if successful, you'll have a cluster.

I've also included a CLI container in the stack. If you'd like to interact with the cluster directly, start this container and log into it through the two-way console . This will give you a proxied terminal session on the CLI container where you can run Dgraph queries directly through their tooling or using HTTP requests. When I was playing around with this, I had ChatGPT give me some seed scripts and a few calls, which it was able to do rather neatly, so if you're looking to save time, that's a good place to start.

6. As Code Artifacts

The nice part of this whole thing is that if you wanted to just grab the stack file from the demo repo and host it yourself on GitHub, Bitbucket, GitLab, etc… you can create a repo with a living, as-code representation of that cluster.

Builds of that stack can then be deployed to really any environment, and the cluster can be set up over and over again using this toolset.

This is a specific pattern on Cycle that I really enjoy. The way Cycle abstracts, compute, and standardizes networks means there are no special cases for one provider or another (or even on-prem). Just set up the compute, create an environment, and deploy the stack.

Next Steps

Thanks for working through this Dgraph clustering guide. If there's a service you're looking to self-host, let us know in the public Slack, and we'll see if it fits for making a guide, or, at the very least, we can provide some assistance on how it would work on Cycle.

There's still a lot to do to make this Dgraph cluster production-ready. Backups, DR scenarios, and more. If you find yourself creating a really great cluster based on this blog or already have a cluster like this on Cycle, we'd love to hear about it in our Community , where others can learn and we can all share ideas on making these apps run better.

If you've read through this and haven't had a chance to use Cycle yet but are looking to learn more, come chat with us on Slack . We'd love to hear more about what you're building!