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.
- Running it on Virtual Machine / Physical host
- 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
docker-run.sh bash script:
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
HASURA_GRAPHQL_DATABASE_URL env variable value, so that you can connect to your Postgres instance. See examples below:
postgres://admin:[email protected]:5432/my-db postgres://admin:@localhost:5432/my-db (if there is no password)
postgres://admin:@localhost:5432/my-db(if there is no password)
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:
--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:[email protected]: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
~# 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:[email protected]: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”.
Download latest stable version saved to variable
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
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.
For Zsh users
Download the completion script in your
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
compinit is loaded or do it by adding in
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.