Run Hasura GraphQL engine using Docker

Introduction

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.

In case you’d like to run Hasura with a fresh Postgres database, follow this guide to deploy the Hasura GraphQL engine along with a Postgres instance using Docker Compose.

Deploying Hasura using Docker

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/stable/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 changes have to be made to the command:

  • Database URL
  • Network config

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:

Linux
Docker for Mac
Docker for Windows

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 4: Open the Hasura console

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

Step 5: Track existing tables and relationships

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

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 command with an admin-secret env var

 #! /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 \
  -e HASURA_GRAPHQL_ADMIN_SECRET=<myadminsecretkey> \
  hasura/graphql-engine:latest

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                       ...
cdfbc6b94c70        hasura/graphql-engine..     ...

$ docker logs cdfbc6b94c70

{"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:

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:latest

All the versions can be found at: https://github.com/hasura/graphql-engine/releases

Step 2: Update the Docker image

In the docker run command or the docker-compose command that you’re running, update the image tag to this latest version.

For example, if you had:

docker run hasura/graphql-engine:v1.0.0-alpha01 ...

you should change it to:

docker run hasura/graphql-engine:latest ...

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

« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2021 Hasura.