GraphQL Hive on Ubuntu 24.04 on Azure User Guide

Overview

This image runs GraphQL Hive 11.6.0, The Guild's open source schema registry and observability platform for GraphQL, on Ubuntu 24.04 LTS. Hive stores every version of your GraphQL schema, checks proposed changes for breaking changes before they ship, composes federated or stitched schemas into one supergraph, and shows how each type and field is actually used through a web console.

Hive self hosts as the upstream community Docker Compose stack, managed by systemd. The stack is a web console (the app), a server that exposes the GraphQL registry API and handles authentication, and the supporting schema, policy, tokens, workflows, usage and usage ingestor services, backed by PostgreSQL, ClickHouse, Redis, a Redpanda broker and a MinIO object store. Only two ports reach the host: nginx on port 80 serves the console, and the registry API is published on port 8082 for the browser and the hive command line client. The datastores stay on the internal Compose network and are never exposed.

What is included:

• GraphQL Hive 11.6.0 self host stack (16 services) pinned by exact image tag and run under Docker Compose via a graphql-hive.service systemd unit
• The web console on :80 (nginx) and the registry GraphQL API on :8082
• A per-VM owner account whose password is generated on first boot and recorded in a root only file, plus a ready to use starter organization
• Every secret (PostgreSQL, ClickHouse, Redis and MinIO passwords, the encryption secret, the CDN signing key and both SuperTokens keys) generated fresh per-VM on first boot, so no upstream example secret survives into the image
• All registry data (PostgreSQL, ClickHouse, Redis, Redpanda and MinIO) on a dedicated Azure data disk at /var/lib/graphql-hive
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. This image runs sixteen services (the console, the registry and supporting services, and PostgreSQL, ClickHouse, Redis, Redpanda and MinIO), so Standard_D2s_v3 (2 vCPU / 8 GiB RAM) is the recommended size and is a comfortable fit; size up further for busy registries. Standard_B2s (4 GiB) is the minimum and runs the full stack, but leaves little headroom under load. NSG inbound: allow 22/tcp from your management network, 80/tcp for the web console, and 8082/tcp for the registry API used by your browser and the hive command line client. Hive serves plain HTTP; for production, terminate TLS in front of it with your own domain.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for GraphQL Hive by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22), HTTP (80) and a custom rule for 8082. Review the dedicated data disk on the Disks tab, then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name graphql-hive \
  --image <marketplace-image-urn> \
  --size Standard_D2s_v3 \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name graphql-hive --port 80  --priority 1010
az vm open-port --resource-group <your-rg> --name graphql-hive --port 8082 --priority 1020

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

On the very first boot, graphql-hive-firstboot.service generates every per-VM secret, brings the Compose stack up, creates the owner account and a starter organization. On a fresh VM this takes a minute or two.

Step 4 - Confirm the services are running

Hive runs as a Docker Compose stack behind nginx. Confirm the systemd units are active and the containers are up:

systemctl is-active docker nginx graphql-hive graphql-hive-firstboot
sudo docker compose -f /opt/graphql-hive/docker-compose.yml ps --format 'table {{.Service}}\t{{.Status}}'

Expected output:

active
active
active
active
SERVICE           STATUS
app               Up 3 minutes (healthy)
broker            Up 3 minutes (healthy)
clickhouse        Up 3 minutes (healthy)
db                Up 3 minutes (healthy)
policy            Up 3 minutes (healthy)
redis             Up 3 minutes (healthy)
s3                Up 3 minutes (healthy)
s3_reverse_proxy  Up 3 minutes
schema            Up 3 minutes (healthy)
server            Up 3 minutes (healthy)
tokens            Up 3 minutes (healthy)
usage             Up 3 minutes (healthy)
usage-ingestor    Up 3 minutes (healthy)
workflows         Up 3 minutes (healthy)

Only the console (via nginx on :80) and the registry API (:8082) are reachable from off the instance; PostgreSQL, ClickHouse, Redis, Redpanda and MinIO stay on the internal Compose network.

Step 5 - Retrieve your owner password

On the first boot of every VM, graphql-hive-firstboot.service generates a unique owner password, together with every other secret in the stack, and writes the owner email, password and console URL into a root only file. Read it with:

sudo cat /root/graphql-hive-credentials.txt

Expected output (your password will differ):

# GraphQL Hive self-host - generated on first boot by graphql-hive-firstboot.service.
# These credentials are unique to this VM. Store them somewhere safe.

HIVE_CONSOLE_URL=http://<vm-public-ip>/
HIVE_GRAPHQL_API=http://<vm-public-ip>:8082/graphql
HIVE_ADMIN_EMAIL=<HIVE_ADMIN_EMAIL>
HIVE_ADMIN_PASSWORD=<HIVE_ADMIN_PASSWORD>

Hive Community has no default login at all: the first account to sign up becomes the organization owner. cloudimg seeds exactly one owner account per-VM with this generated password, so no default or guessable login ever governs a running console. Every datastore password, the encryption secret, the CDN signing key and both SuperTokens keys are regenerated on the same first boot.

Step 6 - Confirm the health endpoint and versions

nginx serves an unauthenticated /healthz endpoint for load balancer probes. Confirm it answers, the console and registry API respond, and check the bundled component versions:

curl -sI http://127.0.0.1/healthz | head -1
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8082/_health
sudo docker --version
sudo docker exec hive-db-1 postgres --version

Expected output:

HTTP/1.1 200 OK
HTTP 200
HTTP 200
Docker version 29.6.2, build dfc4efb
postgres (PostgreSQL) 16.4

Step 7 - Sign in to the console

Browse to http://<vm-public-ip>/. Enter the owner email and the password from Step 5, and select Sign in.

Step 8 - Your organization

After signing in you land on your organization. cloudimg creates a starter organization named default on first boot, so you have a ready to use workspace immediately. The Overview tab lists the projects in the organization; Members and Settings manage access and organization configuration. You can create additional organizations at any time from the switcher in the top left.

Step 9 - Projects and targets

Open a project to see its targets. A project groups a single API or a federated graph; each target is an environment such as production, staging or development. Schemas are published per target, so you can validate a change against staging before promoting it to production. Select New target to add your own, or New project on the organization page to register another API.

Step 10 - Publish a schema to the registry

Schemas are published with the hive command line client, using a registry access token you create under Target then Settings then Registry Access Tokens in the console. From your own machine, point the client at this instance's registry API and publish your schema:

npx @graphql-hive/cli schema:publish \
  --registry.endpoint http://<vm-public-ip>:8082/graphql \
  --registry.accessToken <your-registry-access-token> \
  --author "your name" --commit "initial schema" \
  schema.graphql

Once published, the target's Schema tab shows the latest published SDL with syntax highlighting, and the Checks and History tabs record every check and version over time. Publishing a changed schema runs a breaking change check against the previous version first.

Step 11 - Explore the schema

The Explorer tab presents the published schema type by type, so you can browse every type, field and argument, filter by name, and, once your gateways report usage, see how often each field is actually queried. This is how Hive turns the registry into observability: unused and deprecated fields are flagged, and breaking change checks become smarter because they know what clients really use.

Step 12 - Confirm registry data lives on the dedicated disk

All PostgreSQL, ClickHouse, Redis, Redpanda and MinIO data, plus the pulled Hive images, live under /var/lib/graphql-hive, the Docker data root relocated onto a dedicated Azure data disk that is captured into the image and re-provisioned on every VM:

df -h /var/lib/graphql-hive | tail -1
findmnt -no SOURCE,TARGET,FSTYPE /var/lib/graphql-hive
sudo docker info --format '{{.DockerRootDir}}'

Expected output:

/dev/sdc         32G  4.3G   26G  15% /var/lib/graphql-hive
/dev/sdc /var/lib/graphql-hive ext4
/var/lib/graphql-hive/docker

The disk is mounted by UUID with nofail, so it survives Azure device name reordering across reboots.

Maintenance

• Back up your registry: every schema, check and version is in PostgreSQL, and usage data is in ClickHouse, both under /var/lib/graphql-hive. Snapshot the data disk, or use pg_dump against the hive-db-1 container for logical backups.
• Restart the stack: sudo systemctl restart graphql-hive brings the Compose stack down and back up; sudo docker compose -f /opt/graphql-hive/docker-compose.yml logs -f server tails the registry server logs.
• Report usage from your gateway: point a Hive enabled gateway or the Hive gateway at this instance's usage endpoint to populate the Explorer's usage insights. The usage service is part of the stack; expose port 8081 in your NSG if your gateways run outside the VM.
• Security updates: unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed.
• TLS: for production, front Hive with your own domain and a TLS terminating reverse proxy or Azure Application Gateway, and update the console and registry URLs accordingly.

Support

cloudimg provides 24/7/365 expert technical support for this image. Contact support@cloudimg.co.uk. GraphQL Hive is licensed under the MIT License. This image is provided by cloudimg; additional charges apply for build, maintenance and 24/7 support.