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

The docker-run.sh script has a sample docker run command in it. The following are the changes needed to be made to the command:

Database url

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)

Note

  • If your password contains special characters (e.g. #, %, $, @, etc.), you need to URL encode them in the HASURA_GRAPHQL_DATABASE_URL env var (e.g. %40 for @).

    You can check the logs to see if the database credentials are proper and if Hasura is able to connect to the database.

  • Hasura GraphQL engine needs access permissions to your Postgres database as described in Postgres permissions

Network config

If your Postgres instance is running on localhost the following changes will be needed to the docker run command to allow the Docker container to access the host’s network:

Add the --net=host flag to access the host’s Postgres service.

This is what your command should look like:

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

Use host.docker.internal as hostname to access the host’s Postgres service.

This is what your command should look like:

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

Use docker.for.win.localhost as hostname to access the host’s Postgres service.

This is what your command should look like:

docker run -d -p 8080:8080 \
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://username:password@docker.for.win.localhost: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.