Run Hasura GraphQL engine using Docker

Introduction

This guide will help you deploy the Hasura GraphQL engine and a Postgres database to store its metadata using Docker Compose.

Deploying Hasura using Docker

Prerequisites

• Docker
• Docker Compose

Step 1: Get the docker-compose file

The hasura/graphql-engine/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/docker-compose/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml -o docker-compose.yml

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

Securing the GraphQL endpoint

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

Run the Docker container with an admin-secret env var

graphql-engine:
  image: hasura/graphql-engine:v2.0.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.

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:

• https://docs.docker.com/config/containers/logging 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 at: https://github.com/hasura/graphql-engine/releases

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:v1.2.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

Docker networking

Sometimes you might want to connect Hasura running in Docker with APIs (e.g. auth webhooks, event triggers, remote schemas) that are either running outside of Docker or in a different Docker container. Depending on the setting, the network config is different. This section shows how to connect in each of these use cases.

Network config

Linux

Connection	Config	Comment
Hasura to API (outside Docker)	With --net=host, localhost:3000 Otherwise, <docker-bridge-ip>:3000, e.g. 172.17.0.1:3000	Assuming the API is running on port 3000 The Docker bridge IP can be found via ifconfig
API (outside Docker) to Hasura	localhost:8080	Hasura runs on port 8080 by default
Hasura to API (both in docker-compose)	service name, e.g.: api:3000	Assuming the API is running on port 3000
API to Hasura (both in docker-compose)	service name, e.g.: hasura:8080	Hasura runs on port 8080 by default
Hasura to API (both running with separate docker run)	Docker internal IP address	Can be obtained with docker inspect
API to Hasura (both running with separate docker run)	Docker internal IP address	Can be obtained with docker inspect

Mac

Connection	Config	Comment
Hasura to API (outside Docker)	host.docker.internal:3000	Assuming the API is running on port 3000
API (outside Docker) to Hasura	localhost:8080	Hasura runs on port 8080 by default
Hasura to API (both in docker-compose)	service name, e.g.: api:3000	Assuming the API is running on port 3000
API to Hasura (both in docker-compose)	service name, e.g.: hasura:8080	Hasura runs on port 8080 by default
Hasura to API (both running with separate docker run)	Docker internal IP address	Can be obtained with docker inspect
API to Hasura (both running with separate docker run)	Docker internal IP address	Can be obtained with docker inspect

Windows

Connection	Config	Comment
Hasura to API (outside Docker)	host.docker.internal:3000	Assuming the API is running on port 3000
API (outside Docker) to Hasura	localhost:8080	Hasura runs on port 8080 by default
Hasura to API (both in docker-compose)	service name, e.g.: api:3000	Assuming the API is running on port 3000
API to Hasura (both in docker-compose)	service name, e.g.: hasura:8080	Hasura runs on port 8080 by default
Hasura to API (both running with separate docker run)	Docker internal IP address	Can be obtained with docker inspect
API to Hasura (both running with separate docker run)	Docker internal IP address	Can be obtained with docker inspect

Advanced

Learn more about Docker specific networking in the Docker documentation.