Quickstart with Docker

Available on: Self-Hosted Enterprise

Introduction

This guide will help you get the Enterprise Edition of Hasura GraphQL Engine, a Postgres database to store its metadata, and a Redis database running as Docker containers using Docker Compose. This is the easiest way to set up Hasura Enterprise Edition on your local environment.

This guide requires HGE versions v2.12.0 and above. Installation instructions are below.

Deploying Hasura Enterprise Edition using Docker

Prerequisites

You have Docker and Docker Compose version 2.0 or higher working on your machine.

Step 1: Get the docker-compose file

The install manifests repo contains all installation manifests required to deploy Hasura anywhere. Get the docker compose file from there:

# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/enterprise/docker-compose/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/enterprise/docker-compose/docker-compose.yaml -o docker-compose.yml

Step 2: Set the admin secret

To make sure that your GraphQL endpoint and the Hasura Console are not publicly accessible, you need to configure an admin secret key.

Edit the downloaded docker-compose.yml and set the admin secret as an environment variable.

graphql-engine:
  image: hasura/graphql-engine:v2.12.0
  environment:
    HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
    HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
  ...

Note

The HASURA_GRAPHQL_ADMIN_SECRET should never be passed from the client to the Hasura GraphQL Engine as it would give the client full admin rights to your Hasura instance. See Authentication & Authorization for information on setting up authentication.

Step 3: Set up a license key

If you don't have a license key, you can skip this step and proceed with this guide to set up Hasura. Once you have Hasura up and running, you can sign up for a free 30 day Enterprise Edition trial from the Hasura console.

If you have been provided a license key by the Hasura team, add it as an environment variable to Hasura. Edit the docker-compose.yaml to set the license key as the value for the HASURA_GRAPHQL_EE_LICENSE_KEY environment variable.

graphql-engine:
  image: hasura/graphql-engine:v2.12.0
  environment:
    HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
    HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
    HASURA_GRAPHQL_EE_LICENSE_KEY: '<license key>'
  ...

Step 4: Run Hasura GraphQL Engine

The following command will run Hasura GraphQL Engine along with a Postgres database to store its metadata.

docker compose up -d

Check if the containers are running:

docker ps

CONTAINER ID IMAGE                 ... CREATED STATUS PORTS          ...
097f58433a2b hasura/graphql-engine ... 1m ago  Up 1m  8080->8080/tcp ...
b0b1aac0508d postgres              ... 1m ago  Up 1m  5432/tcp       ...

Step 5 (optional): Use your PostgreSQL and Redis instances

The Hasura Enterprise Edition Docker compose files come with containerized open-source versions of PostgreSQL and Redis. Note that these are not managed by Hasura.

We highly recommend using managed PostgreSQL and Redis instances in production.

To switch to using your PostgreSQL or Redis instances, set the following environment variables:

graphql-engine:
  image: hasura/graphql-engine:v2.12.0
  environment:
    HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
    HASURA_GRAPHQL_REDIS_URL: "redis://redis:6379"
    HASURA_GRAPHQL_RATE_LIMIT_REDIS_URL: "redis://redis:6379"
  ...

Step 6: Start using Hasura

Congratulations! You have successfully set up Hasura Enterprise Edition on Docker. Start using Hasura Enterprise Edition now.

Hasura GraphQL Engine server logs

You can check the logs of the Hasura GraphQL Engine deployed using Docker by checking the logs of the GraphQL Engine container:

docker ps

CONTAINER ID IMAGE                 ... CREATED STATUS PORTS          ...
097f58433a2b hasura/graphql-engine ... 1m ago  Up 1m  8080->8080/tcp ...
b0b1aac0508d postgres              ... 1m ago  Up 1m  5432/tcp       ...


docker logs 097f58433a2b

{"timestamp":"2018-10-09T11:20:32.054+0000", "level":"info", "type":"http-log", "detail":{"status":200, "query_hash":"01640c6dd131826cff44308111ed40d7fbd1cbed", "http_version":"HTTP/1.1", "query_execution_time":3.0177627e-2, "request_id":null, "url":"/v1/graphql", "user":{"x-hasura-role":"admin"}, "ip":"127.0.0.1", "response_size":209329, "method":"POST", "detail":null}}
...

See:

• Docker logs for more details on logging in Docker.
• Hasura GraphQL Engine logs for more details on Hasura logs.

Updating Hasura GraphQL Engine

This guide will help you update the Hasura GraphQL Engine running with Docker. This guide assumes that you already have Hasura GraphQL Engine running with Docker.

Step 1: Check the latest release version

The current latest version is:

hasura/graphql-engine:v2.3.0

All the versions can be found here.

Step 2: Update the Docker image

In the docker compose command that you're running, update the image tag to this latest version.

For example, if you had:

graphql-engine:
  image: hasura/graphql-engine:v2.9.0

you should change it to:

graphql-engine:
  image: hasura/graphql-engine:v2.3.0

Note

If you are downgrading to an older version of the GraphQL Engine, you might need to downgrade your Metadata catalogue version as described in Downgrading Hasura GraphQL Engine.