GraphQL Hive on AWS User Guide

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 - cloudimg 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.

Step 1: 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 cloudimg 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.

Step 2: 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}]'

Step 3: Retrieve Your Per-Instance Owner Credentials

GraphQL Hive Community has no default login: the first account to sign up becomes the organization owner. cloudimg 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.

Step 4: 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.

Step 5: 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).

Step 6: 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.

Step 7: 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 cloudimg. If you need help with deployment, configuration, the Docker Compose stack, the schema registry, the hive CLI, federation or usage analytics, contact support@cloudimg.co.uk or use the 24/7 live chat on the cloudimg support portal.