Run Hasura GraphQL Engine using Docker

This guide assumes that you already have Postgres running and helps you set up the Hasura GraphQL engine using Docker and connect it to your Postgres database.

Prerequisites

Step 1: Get the docker run bash script

The hasura/graphql-engine/install-manifests repo contains all installation manifests required to deploy Hasura anywhere.

Get the docker run bash script from there:

$ wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-run/docker-run.sh

Step 2: Configure the docker-run.sh script

Check the sample docker run command in docker-run.sh.

Edit the HASURA_GRAPHQL_DATABASE_URL env var value, so that you can connect to your Postgres instance.

#! /bin/bash
docker run -d -p 8080:8080 \
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://username:password@hostname:port/dbname \
  -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
  hasura/graphql-engine:latest

Examples of HASURA_GRAPHQL_DATABASE_URL:

  • postgres://admin:password@localhost:5432/my-db
  • postgres://admin:@localhost:5432/my-db (if there is no password)

Postgres on localhost

If your Postgres database is running on localhost, add the --net=host flag to allow the Docker container to access the host’s network. This is what your command should look like:

#! /bin/bash
docker run -d --net=host \
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://username:password@hostname:port/dbname \
  -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
  hasura/graphql-engine:latest

If your Postgres database is running on localhost, use host.docker.internal as hostname to access the host’s Postgres service. This is what your command should look like:

#! /bin/bash
docker run -d -p 8080:8080 \
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://username:password@host.docker.internal:port/dbname \
  -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
  hasura/graphql-engine:latest

Step 3: Run the hasura docker container

Execute docker-run.sh & check if everything is running well:

$ ./docker-run.sh
$ docker ps

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

Step 3: Open the hasura console

Head to http://localhost:8080/console to open the Hasura console.

Step 4: Track existing tables and relationships

See Setting up GraphQL schema using an existing database to enable GraphQL over the database.