Install Hasura GraphQL Engine on Ubuntu 18.04 / CentOS 7

This guide will help you setup Hasura GraphQL engine and Postgres database on Ubuntu 18.04 / CentOS 7. Hasura GraphQL Engine is a high performance GraphQL server that enables you to setup GraphQL server and event triggers over a Postgres database in no atime. GraphQL Engine will automatically generate a GraphQL schema and process GraphQL queries, subscriptions and mutations.

Building GraphQL apps or moving to existing apps to GraphQL backed by Postgres will become easy with Hasura GraphQL Engine. You’ll get nstant realtime GraphQL APIs over Postgres.

Step 1: Install PostgreSQL Database Server

You have two options of running PostgreSQL database server when working with Hasura GraphQL engine.

1. Running it on Virtual Machine / Physical host
2. Running it inside a container

I recommend running your Database server in the host system if you’re not comfortable with Docker containers administration. Follow our guides below to have a Working installation of Postgres on Ubuntu 18.04 / CentOS 7.

How to install PostgreSQL on CentOS 7

Install PostgreSQL on Ubuntu 18.04 / Ubuntu 16.04

Step 2: Install Docker on Ubuntu 18.04 / CentOS 7

Hasura GraphQL Engine will be running in a Docker Container. This means you need to have an installation of Docker Engine on your host system. The following guides will be helpful.

How to install Docker CE on Ubuntu / Debian / Fedora / Arch / CentOS

Once Docker is installed, proceed to step 3.

Step 3: Deploy Hasura GraphQL Engine on Ubuntu 18.04 / CentOS 7

Download the docker-run.sh bash script:

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

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 variable value, so that you can connect to your Postgres instance. See examples below:

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

Examples of HASURA_GRAPHQL_DATABASE_URL:

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

Network config

If your Postgres instance is running on localhost the following changes will be needed to the dockerrun 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

To check if container is started and running, run the docker ps command.

$ sudo docker ps
CONTAINER ID        IMAGE                                  COMMAND                  CREATED             STATUS              PORTS               NAMES
5fa940fa91ad        hasura/graphql-engine:v1.0.0-alpha40   "graphql-engine serve"   9 seconds ago       Up 8 seconds                            nostalgic_hypatia

The service should bind to host network on port 8080.

~# ss -tunelp | grep 8080
tcp    LISTEN   0  128  0.0.0.0:8080  0.0.0.0:*   users:(("graphql-engine",pid=12999,fd=17)) ino:83522 sk:a <-> 

Access GraphQL console on Server IP and port 8080.

Securing the GraphQL endpoint

By default, GraphQL console is publicly accessible. To secure GraphQL endpoint and the Hasura console, you need to configure an admin secret key. You docker run command will look something like below.

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

On accessing GraphQL console, you’ll be asked to to provide Admin secret.

Running Hasura GraphQL Engine and Postgres in Docker

If you need a simple and quicker setup of GraphQL environment, you can run both Postgres and GraphQL in docker.

Step 1: Install Docker Compose

Please check the latest release of Docker Compose on the Official Compose releases page before downloading. As of this writing, the latest release is “1.23.2”.

export VER="1.23.2"

Download latest stable version saved to variable VER.

sudo curl -L "https://github.com/docker/compose/releases/download/${VER}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

The command above will save the file to /usr/local/bin/docker-compose. Apply executable permissions to the binary:

sudo chmod +x /usr/local/bin/docker-compose

Display Docker compose version.

$ docker-compose --version
docker-compose version 1.23.2, build 1110ad01

Set Configure Compose Command-line completion

Compose has command completion for the bash and zsh shell.

For Bash users

Place the completion script in /etc/bash_completion.d/.

sudo curl -L https://raw.githubusercontent.com/docker/compose/${VER}/contrib/completion/bash/docker-compose -o /etc/bash_completion.d/docker-compose

Source the file or re-login to enjoy completion feature.

source /etc/bash_completion.d/docker-compose

For Zsh users

Download the completion script in your ~/.zsh/completion/

mkdir -p ~/.zsh/completion
curl -L https://raw.githubusercontent.com/docker/compose/${VER}/contrib/completion/zsh/_docker-compose > ~/.zsh/completion/_docker-compose

Include the directory in your $fpath by adding in ~/.zshrc:

fpath=(~/.zsh/completion $fpath)

Make sure compinit is loaded or do it by adding in ~/.zshrc:

autoload -Uz compinit && compinit -i

Then reload your shell:

exec $SHELL -l

Step 2: Download docker-compose file

Run the command below to download docker compose file for Hasura.

mkdir graphql
cd graphql
wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose/docker-compose.yaml

You can edit the environment section to add Admin secret.

version: '3.6'
services:
  postgres:
    image: postgres
    restart: always
    volumes:
    - db_data:/var/lib/postgresql/data
  graphql-engine:
    image: hasura/graphql-engine:v1.0.0-alpha40
    ports:
    - "8080:8080"
    depends_on:
    - "postgres"
    restart: always
    environment:
      HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:@postgres:5432/postgres
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true" # set to "false" to disable console
      ASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
volumes:
  db_data:

Step 3: Run Hasura GraphQL engine & Postgres

Start the using:

$ docker-compose up -d
.....
Creating graphql_postgres_1 … done
Creating graphql_graphql-engine_1 … done

Check if the containers are running:

$ docker ps
CONTAINER ID        IMAGE                                  COMMAND                  CREATED             STATUS              PORTS                    NAMES
ac0063626d8a        hasura/graphql-engine:v1.0.0-alpha40   "graphql-engine serve"   3 minutes ago       Up 3 minutes        0.0.0.0:8080->8080/tcp   graphql_graphql-engine_1
2928f0f1537e        postgres                               "docker-entrypoint.s…"   3 minutes ago       Up 3 minutes        5432/tcp                 graphql_postgres_1

When a change is made on the docker-compose file, restart your containers.

$ docker-compose restart 
Restarting graphql_graphql-engine_1 … done
Restarting graphql_postgres_1       … done

Step 4: Access Hasura console

Open the Hasura console server IP port 8080.

You are now ready to make your first graphql queryor set up your first event trigger. Learn more from Hasura GraphQL Engine documentation.