Deployment guide

GraphQL Hive

Overview

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

This image runs GraphQL Hive 11.6.0 on Ubuntu 24.04 LTS. Hive is self-hosted as the upstream community Docker Compose stack, managed by systemd. The stack consists of:

A web console (the app)
A server that exposes the GraphQL registry API and handles authentication
The supporting schema, policy, tokens, workflows, usage and usage ingestor services
Backing stores: 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 you get:

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 SecureAnyCloud support

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a subnet in the target region.

This image runs sixteen services: the console, the registry and supporting services, and PostgreSQL, ClickHouse, Redis, Redpanda and MinIO. Standard_D2s_v3 (2 vCPU / 8 GiB RAM) is the recommended size and fits comfortably. Choose a larger size for busy registries. Standard_B2s (4 GiB) is the minimum and runs the full stack, but leaves little headroom under load.

Configure the network security group (NSG) to allow inbound 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, so 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 SecureAnyCloud, and select Create.

On the Basics tab, 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) and HTTP (80), and add a custom rule for 8082.

Review the dedicated data disk on the Disks tab, then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:graphql-hive-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name graphql-hive \
  --image sac1647283583153:graphql-hive-ubuntu-24-04:default:latest \
  --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

Connect over SSH:

ssh azureuser@<vm-public-ip>

On the very first boot, graphql-hive-firstboot.service generates every per-VM secret, brings the Compose stack up, and 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 that 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 outside 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. It writes the owner email, password and console URL into a root-only file. Read the file with:

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

Your password will differ from the one shown here:

# 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. SecureAnyCloud 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 that it answers and that the console and registry API respond. Then 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 - Find your organization

After you sign in, your organization opens. SecureAnyCloud 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. To create additional organizations, use the switcher in the top left at any time.

Step 9 - Open 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

Publish schemas with the hive command-line client. It needs a registry access token, which you create in the console under Target, Settings, Registry Access Tokens. 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. The Checks and History tabs record every check and version over time. Publishing a changed schema first runs a breaking-change check against the previous version.

Step 11 - Explore the schema

The Explorer tab presents the published schema type by type. Browse every type, field and argument, and filter by name. Once your gateways report usage, you can also 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. This is the Docker data root, relocated onto a dedicated Azure data disk that is captured into the image and re-provisioned on every VM. Confirm the mount:

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 the mount 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.
Apply security updates. Unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed.
Add 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

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

Deploy on Azure

Launch GraphQL Hive on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

This image runs GraphQL Hive 11.6.0, The Guild's open-source (MIT) 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. The console and the registry API are both served from a single origin by nginx on port 80; the datastores stay on the internal Compose network and are never exposed.

The image is secure by default. GraphQL Hive Community has no default login at all, and the upstream project ships example passwords and signing keys for its datastores and sessions - SecureAnyCloud bakes none of them. On the first boot of every instance a fresh set of database, cache, object-store, encryption and session secrets is generated, a single owner account is created with a unique random password, and the credentials are written to a root-only file, so no two instances share a login and no upstream default ever governs a running console.

Prerequisites

Before you deploy this image you need:

An Amazon Web Services account where you can launch EC2 instances

IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products

An EC2 key pair in the target Region for SSH access to the instance

A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound port 80 from the networks your users will reach the console on

The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Instance Sizing

GraphQL Hive runs a sixteen-service stack (the console, the registry and supporting services, and PostgreSQL, ClickHouse, Redis, a Redpanda broker and a MinIO object store). The image is tuned to fit a small instance, but the stack is memory-hungry, so m5.large (2 vCPU / 8 GB RAM) is the minimum and m5.xlarge or larger is recommended for busy registries. A persistent swap file gives the cold start headroom. Registry data (PostgreSQL, ClickHouse and the object store) lives on a dedicated 40 GB EBS data volume captured into the image; grow it as your schema history and usage data accumulate.

Connecting to Your Instance

SSH in as the default login user for your OS variant, using your EC2 key pair. The console is served on port 80, so you do not need an SSH tunnel to use it - you connect over SSH only for administration.

OS variant SSH login user Example

Ubuntu 24.04 ubuntu ssh -i your-key.pem ubuntu@<instance-public-ip>

Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for GraphQL Hive. Select the SecureAnyCloud listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger (see Instance Sizing above). Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound port 80 from the networks your users use. Then Launch instance.

Launch from the AWS CLI (optional)

You can launch the same AMI from the command line. Replace the AMI id with the one shown on the listing for your Region, and use your own key pair, security group and subnet ids.

aws ec2 run-instances \
  --image-id <ami-id-from-listing> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <your-sg-id> \
  --subnet-id <your-subnet-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=graphql-hive}]'

Retrieve Your Per-Instance Owner Credentials

GraphQL Hive Community has no default login: the first account to sign up becomes the organization owner. SecureAnyCloud seeds exactly one owner account per instance on first boot, with a unique generated password, and writes the console URL, the owner email and the password to a root-only file. SSH in and read it:

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

You will see the resolved URLs and the generated owner login:

HIVE_CONSOLE_URL=http://<instance-public-ip>/ HIVE_GRAPHQL_API=http://<instance-public-ip>/graphql HIVE_ADMIN_EMAIL=admin@graphql-hive.local HIVE_ADMIN_PASSWORD=<generated-on-first-boot>

Every datastore password, the encryption secret, the CDN signing key and both SuperTokens keys are regenerated on the same first boot, so no default or guessable credential ever governs a running instance.

Verify the Stack

Confirm that Docker, nginx and the Hive Compose stack are up. The systemd units should all be active:

systemctl is-active docker.service nginx.service graphql-hive.service

active active active

nginx serves an unauthenticated /healthz endpoint for load-balancer probes, and fronts both the console and the GraphQL registry API on port 80. Confirm they answer:

curl -fsS http://127.0.0.1/healthz
curl -s -o /dev/null -w 'console: %{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'graphql: %{http_code}\n' -X POST http://127.0.0.1/graphql -H 'content-type: application/json' -d '{"query":"{__typename}"}'

ok console: 200 graphql: 200

You can list every service in the stack and its state:

cd /opt/graphql-hive && docker compose ps --format '{{.Service}}\t{{.State}}'

The db, clickhouse, redis, broker, s3, server, app and the schema, policy, tokens, workflows, usage and usage-ingestor services all report running; the migrations and s3_provision_buckets services are one-shot jobs that complete during start-up.

Sign in to the Console

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

The console and the registry API are served from the same origin (port 80), so the session works over plain HTTP out of the box. For production, terminate TLS in front of the instance (see TLS below).

Create a Project and Targets

After signing in you land in your organization. A project groups the schemas for one GraphQL API; each project has separate targets (typically production, staging and development) that are independent registry environments.

Select Create Project, give it a name and choose a project type - Single for one schema, or Federation or Stitching to compose several subgraphs into one supergraph. Hive creates the default targets for you.

Open a target to reach its Schema, Checks, Explorer, History, Insights, Apps and Laboratory tabs, where you browse the published schema, review breaking-change checks and explore how each type and field is used.

Publish a Schema with the hive CLI

Schemas are published with the hive command-line client, using a registry access token you create under Project then Settings then Access Tokens in the console. Grant it schema-registry write permission. From your own machine, point the client at this instance's registry API on port 80 and publish your schema:

npx @graphql-hive/cli schema:publish \
  --registry.endpoint http://<public-ip>/graphql \
  --registry.accessToken <your-token> \
  schema.graphql

Once published, the target's Schema tab shows the SDL, the Explorer lets you browse every type and field, and subsequent schema:check runs in CI compare a proposed change against the registered schema and fail on breaking changes.

Security and Secrets

Only the console and the registry API are reachable off the instance, both on port 80 through nginx; PostgreSQL, ClickHouse, Redis, Redpanda and MinIO stay on the internal Compose network. On first boot the instance rotates every secret and creates exactly one owner account with a unique password written to /root/graphql-hive-credentials.txt (mode 600). To add more users, invite them from Organization then Members in the console.

TLS

The image serves plain HTTP on port 80 for a working console out of the box. For production, put a TLS-terminating reverse proxy or load balancer in front of the instance with your own domain and certificate on port 443, forwarding to port 80, and update your bookmarks and the hive CLI --registry.endpoint to the https:// URL.

Updating and Maintenance

The stack is defined in /opt/graphql-hive/docker-compose.yml with image tags pinned to Hive 11.6.0. To restart the stack:

sudo systemctl restart graphql-hive.service

Registry data persists on the dedicated EBS data volume mounted at /var/lib/graphql-hive (PostgreSQL for the schema registry, ClickHouse for usage analytics, and the MinIO object store), so it survives restarts. Back it up with an EBS snapshot, and keep the base OS patched with sudo apt update && sudo apt upgrade.

Support

This image is supported by SecureAnyCloud. If you need help with deployment, configuration, the Docker Compose stack, the schema registry, the hive CLI, federation or usage analytics, contact sales@secureanycloud.com or use the 24/7 live chat on the SecureAnyCloud support portal.

Deploy on AWS

Launch GraphQL Hive on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS