How to Install Hasura GraphQL Engine

Hasura is an open-source engine based on the GraphQL query language for API. It allows you to create a connection, manage, and configure event triggers for the PostgreSQL database in minutes. Hasura helps you build GraphQL applications backed by PostgreSQL or incrementally move your existing projects.

In this tutorial, we’ll overview two examples of the Hasura GraphQL engine installation at the platform:

• Automatic Deployment with Local PostgreSQL Database
• Manual Deployment with External PostgreSQL Database

Automatic Deployment with Local PostgreSQL Database

1. Log in the dashboard and click Marketplace at the top-left corner.

2. Search for the Docker Engine CE package and initiate its installation.

3. To automatically create Hasura and PostgreSQL database in the same container, choose the Deploy containers from compose.yml option, and provide the default config from the Hasura on Docker repository:

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

Configure the remaining Environment, Display Name, Region (if available) fields up to your needs, and click Install.

4. After a successful installation, you can access the Hasura console to ensure that everything works properly.

http://{envDomain}:8080/console

That’s it! Now, you can provide Data for your database via the same-named tab at the top and try out GraphQL queries afterward.

Manual Deployment with External PostgreSQL Database

In case you already have a database, you can connect to it with the Hasura GraphQL engine.

1. Create a clean standalone Docker Engine CE via platform Marketplace.

2. After creation connect to the container via Web SSH and create a file with the following content (e.g. nano docker-run.sh):

1
2
3
4
5

docker run -d --restart=always -p 80:8080 \
-e HASURA_GRAPHQL_DATABASE_URL=postgres://{username}:{password}@{host}/{dbname} \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
-e HASURA_GRAPHQL_ADMIN_SECRET=myadminsecretkey \
hasura/graphql-engine:v1.0.0

For the detailed information on the docker run command, refer to the official documentation. In our case, the parameters are the following:

• -d - runs your services in the background
• –restart=always - to always start the daemon (e.g. after container restart)
• -p 80:8080 - configures port redirect from the 80 port of the Docker Engine container to the 8080 one of the Hasura image running inside
• -e - sets environment variables (refer to the full list for additional details)
  • HASURA_GRAPHQL_DATABASE_URL - connection link to your PostgreSQL database with special characters being URL encoded (if located at the platform, the required details can be viewed in the PostgreSQL after-creation email)
  • HASURA_GRAPHQL_ENABLE_CONSOLE - enables Hasura console
  • HASURA_GRAPHQL_ADMIN_SECRET - configures admin secret key to access console, myadminsecretkey in our case
• hasura/graphql-engine:v1.0.0 - Docker image to be installed

3. Make this file executable and run it to create Hasura Docker container.

1
2

chmod +x docker-run.sh
./docker-run.sh

You can additionally run the docker ps command to ensure that the Hasura service is up and running.

4. In our case, the application console is on the port 80 so that you can click Open in Browser next to your environment for an automatic redirect. Otherwise, the required port should be added to the environment URL.

According to our settings, admin secret key should be provided to access console (myadminsecretkey in our case).

5. Now, you can start working with your database via GraphQL API. For example, from the GraphiQL tab.

Alternatively, you can use GraphQL Endpoint (specified at the top of the page) to create your POST request to the database via any preferred tool or script.

What’s next?

• Marketplace
• Docker Engine CE
• Building Docker Image