• Self Hosting
  • Get Started

Self-Hosting GraphQL Hive

If you can not use the GraphQL Hive SaaS service, you can self-host it. The self-hosted version is free and open-source. You can find the full source code on GitHub.

💡

Self-hosting GraphQL Hive does currently not support all of the features as the SaaS version.

The following features are currently unavailable when self-hosting:

  • CDN (high availability integration)
  • Billing (payment integration)
  • Usage rate-limiting

Pre-Requisites

The easiest way of running GraphQL Hive is using Docker and docker-compose.

All the services required for running GraphQL Hive are published to the GitHub container registry (GraphQL Hive Docker Images).

Please make sure to install the Docker daemon as well as docker-compose on your machine before proceeding.

Running GraphQL Hive

First download the docker-compose.community.yml file from the GitHub repository using wget.

wget https://raw.githubusercontent.com/kamilkisiela/graphql-hive/main/docker-compose.community.yml

After downloading the file, you need to set some environment variables.

💡

Docker Tag. Docker images are built and published for each single commit within the GraphQL Hive repository and tagged with the corresponding commit sha. You can also find all available images on the Hive Docker Registry Overview. We recommend using one of the latest versions. Right now we do not have a stable release strategy yet. However, every commit on the main branch can be considered as stable as it is the version we are running in production. After picking a version set the DOCKER_TAG environment variable to that value (e.g. export DOCKER_TAG=":3b635063294a4636ee89579f57e531de04ef087f"). We do not recommend using the tag latest. Instead use an exact commit from the main branch.

export DOCKER_REGISTRY="ghcr.io/kamilkisiela/graphql-hive/"
export DOCKER_TAG=":latest"
export HIVE_ENCRYPTION_SECRET=$(openssl rand -hex 16)
export HIVE_APP_BASE_URL="http://localhost:8080"
export HIVE_EMAIL_FROM="[email protected]"
export SUPERTOKENS_API_KEY=$(openssl rand -hex 16)
export CLICKHOUSE_USER="clickhouse"
export CLICKHOUSE_PASSWORD=$(openssl rand -hex 16)
export REDIS_PASSWORD=$(openssl rand -hex 16)
export POSTGRES_USER="postgres"
export POSTGRES_PASSWORD=$(openssl rand -hex 16)
export POSTGRES_DB="registry"
export MINIO_ROOT_USER="minioadmin"
export MINIO_ROOT_PASSWORD="minioadmin"

We recommend saving the environment variables in a file that you can reuse later. E.g. a .env file that you can later on expand using source .env. We are using openssl here for generating passwords on the fly.

You can also embed the values within a new docker-compose file by running docker-compose -f docker-compose.community.yml config > docker-compose.with-env.yml after setting the environment variables.

After setting the environment variables, you can start the GraphQL Hive services using docker-compose.

docker-compose -f docker-compose.community.yml up
# or of you embedded the environment variables
docker-compose -f docker-compose.with-env.yml up

Wait until all the services are up and running.

Congratulations 🥳, you just started your own GraphQL Hive instance.

Visit http://localhost:8080 in your browser and start using GraphQL Hive! The usage reporting endpoint is bound to http://localhost:8081. The GraphQL API is bound to http://localhost:8082. The artifacts bucket is bound to http://localhost:8083.

Next Steps

After doing your first testing with GraphQL Hive you should consider the following steps:

  • Evaluate whether you want to run Databases yourself within Docker or instead use a managed database service.
  • Set up backups for your data.
  • Set up a CD pipeline for deploying GraphQL Hive to your Cloud Provider or bare-metal server of choice (e.g. a Kubernetes cluster or Docker Swarm)
  • Set up a monitoring solution for your GraphQL Hive instance (leverage healthchecks, sentry error reporting, prometheus metrics, etc.).
  • Configure the emails service to use a real email provider (by default it uses sendmail).
  • Watch and follow the GraphQL Hive GitHub repository for new releases and updates.
  • Set up a weekly reminder for updating your GraphQL Hive instance to the latest version and applying maintenance.
  • Get yourself familiar with SuperTokens and follow their changelogs in order to keep your SuperTokens instance up-to-date.

You can review the configuration options of all the services in the corresponding Readme files.