Hasura GraphQL engine on Azure with Container Instances and Postgres¶

Table of contents

Introduction
One-click deploy using ARM Template
Pre-requisites
Create a new Resource Group
Provision a PostgreSQL server
Create a new database
Allow access to Azure Services
Create a Container Instance
Open the Hasura Console
Troubleshooting
Tearing down
References

Introduction¶

This guide talks about how to deploy the Hasura GraphQL engine on Azure using Container Instances with Azure Database for PostgreSQL server.

One-click deploy using ARM Template¶

All resources mentioned in this guide can be deployed using the one-click button below.

(This button takes you to the Azure Portal, you might want to Ctrl+Click to open it in a new tab. Read more about this Resource Manager Template here).

(This button takes you to the Azure Portal, you might want to Ctrl+Click to open it in a new tab. Read more about this Resource Manager Template here).

Pre-requisites¶

Valid Azure Subscription with billing enabled or credits (click here for a free trial).
Azure CLI.

The actions mentioned below can be executed using the Azure Portal and the Azure CLI. But, for the sake of simplicity in documentation, we are going to use Azure CLI, so that commands can be easily copy-pasted and executed.

Once the CLI is installed, login to your Azure account:

az login

Create a new Resource Group¶

As the name suggestes, Resource Groups are used to group together various resources on Azure. We’ll create a resource group called hasura at the westus location.

az group create --name hasura --location westus

Provision a PostgreSQL server¶

Note

If you already have a database setup, you can skip these steps and jump directly to Allow access to Azure Services.

Once the resource group is created, we create a Postgres server instance:

az postgres server create --resource-group hasura \
   --name "<server_name>" \
   --location westus \
   --admin-user hasura \
   --admin-password "<server_admin_password>" \
   --sku-name GP_Gen5_2 \
   --version 10

Note

Choose a unique name for <server_name>. Also choose a strong password for <server_admin_password>, including uppercase, lowercase and numeric characters. This will be required later to connect to the database (make sure you escape the special characters depending on your shell).

Note down the hostname. It will be shown as below in the output:

...
"fullyQualifiedDomainName": "<server_name>.postgres.database.azure.com",
...

<server_name>.postgres.database.azure.com is the hostname here.

Note

If you get an error saying Specified server name is already used, change the value of --name (<server_name>) to something else.

Create a new database¶

Create a new database on the server:

az postgres db create --resource-group hasura \
   --server-name "<server_name>" \
   --name hasura

Allow access to Azure Services¶

Create a firewall rule allowing acess from Azure internal services:

az postgres server firewall-rule create --resource-group hasura \
   --server-name "<server_name>" \
   --name "allow-azure-internal" \
   --start-ip-address 0.0.0.0 \
   --end-ip-address 0.0.0.0

Create a Container Instance¶

Launch Hasura using a container instance:

az container create --resource-group hasura \
   --name hasura-graphql-engine \
   --image hasura/graphql-engine \
   --dns-name-label "<dns-name-label>" \
   --ports 80 \
   --environment-variables "HASURA_GRAPHQL_SERVER_PORT"="80" "HASURA_GRAPHQL_ENABLE_CONSOLE"="true" \
   --secure-environment-variables "HASURA_GRAPHQL_DATABASE_URL"="<database-url>"

<database-url> should be replaced by the following format:

postgres://hasura%40<server_name>:<server_admin_password>@<hostname>:5432/hasura

If you’d like to connect to an existing database, use that server’s database url.

Note

%40 is used in the username because Azure creates usernames as admin-user@server-name and since the database url uses @ to separate username-password from hostname, we need to url-escape it in the username. Any other special character should be url-encoded.

If the <dns-name-label> is not available, choose another unique name and execute the command again.

Open the Hasura Console¶

That’s it! Once the deployment is complete, navigate to the container instance’s IP or hostname to open the Hasura console:

az container show --resource-group hasura \
   --name hasura-graphql-engine \
   --query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" \
   --out table

The output will contain the FQDN in the format <dns-name-label>.westus.azurecontainer.io.

Visit the following URL for the Hasura console:

http://<dns-name-label>.westus.azurecontainer.io/console

Replace <dns-name-label> with the label given earlier.

You can create tables and test your GraphQL queries here.

Troubleshooting¶

If your password contains special characters, check if they were URL encoded and given as environment variables. Also check for proper escaping of these characters based on your shell.

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

If you’re using an existing/external database, make sure the firewall rules for the database allow connection for Azure services.

Checking logs¶

If the console is not loading, you might want to check the logs and see if something is wrong:

az container logs --resource-group hasura \
   --name hasura-graphql-engine \
   --container-name hasura-graphql-engine
# use --follow flag to stream logs

Tearing down¶

To clean-up, just delete the resource group:

az group delete --resource-group hasura

References¶

« previous | next »