Back to Blog

Deploying a Hasura GraphQL Engine With One Command

By Cameron Gray -

GraphQL has become an extremely popular way to create APIs that can be consumed by a wide variety of clients. With GraphQL, you are saved a lot of the boilerplate work that comes with building a standard backend application that serves up a RESTful API. One of the more popular open source GraphQL engines is Hasura. Hasura is an engine that sits directly on top of a Postgres Database and provides a realtime GraphQL API.

Recently we had a customer ask how hard it would be to stand up scalable Hasura engine on ECS using Convox. Having not deployed Hasura before I took a look at this very helpful blog post that the Hasura team published last year.

While the blog post is fairly straightforward, there are still a lot of steps to get everything setup and I felt like given Hasura’s Docker native architecture, Convox could make the installation even easier.

In order to deploy a Hasura Engine we need a Postgres Database and a Docker container running the engine. Fortunately with Convox we can define all of this in a single file and deploy it to ECS with one command. The core of any app deployed with Convox is the convox.yml file. Similar to a docker-compose.yml, convox.yml describes everything your application needs to run. To deploy a Hasura GraphQL Engine, all we need to do is simply create a convox.yml that looks like this:

resources:
  database:
    type: postgres
services:
  engine:
    image: hasura/graphql-engine:latest
    command: graphql-engine serve --enable-console
    port: 8080
    resources:
      - database:HASURA_GRAPHQL_DATABASE_URL
    environment:
      - HASURA_GRAPHQL_ACCESS_KEY=mylongsecretaccesskey

Digging into the details you can see that it’s pretty simple. First we define a Postgres resource. One of the great things about Convox-defined resources is that not only will Convox automatically spin up your database in a container, but Convox will also inject an environment variable containing the database connection URL into your running containers. Convox names the environment variable using the following pattern [RESOURCE_NAME]_URL but allows you to override the variable name. Hasura expects an environment variable called HASURA_GRAPHQL_DATABASE_URL containing the URL connection string so we override our default name of DATABASE_URL with HASURA_GRAPHQL_DATABASE_URL.

The next thing we have defined is the service that will run the engine itself. Since Convox allows you to define a service using an external docker image we have done just that. Next we define the startup command and port for the engine. Finally, we link the Postgres resource and define the secret key environment variable. We have given the secret key a default value which is handy for testing locally, but in production we will use Convox’s built in secrets management and override the default value with convox env set.

Assuming we already have a Convox Rack, we can simply create a new app with convox apps create --wait and once the app is ready we can deploy with convox apps deploy --wait.

$ convox deploy --wait
Packaging source... OK
Uploading source... OK
Starting build... OK
Authenticating 149765177331.dkr.ecr.us-east-1.amazonaws.com: Login Succeeded
Running: docker pull hasura/graphql-engine:latest
Running: docker tag hasura/graphql-engine:latest convox/hasura:engine.BBJKFKZTICT
Injecting: convox-env
Running: docker tag convox/hasura:engine.BBJKFKZTICT 
Running: docker push dkr.ecr.us-east-1.amazonaws.com
Promoting RWTRRDIDYUN... 
prod-demo-hasura-ServiceEngine-42CSVZV5JS2R UPDATE_COMPLETE 
prod-demo-hasura UPDATE_COMPLETE ServiceEngine 
prod-demo-hasura UPDATE_IN_PROGRESS ResourceHasuraGraphqlDatabase 
prod-demo-hasura UPDATE_COMPLETE ResourceHasuraGraphqlDatabase 
prod-demo-hasura UPDATE_COMPLETE prod-demo-hasura 
OK
$

Once the deployment is finished we can find the url of our Hasura Engine with convox services

$ convox services
SERVICE  DOMAIN                                                 PORTS           
engine   hasura-engine.prod-Route-123456.us-east-1.convox.site  80:8080 443:8080

Finally we can open a browser to the Engine URL and enter our secret key to see our fully operational Hasura GraphQL Engine!

Hasura Dashboard

Since Convox Racks are now cloud-portable you could easily deploy this service to AWS, GCP, Digital Ocean and Azure. To install a Convox Rack in one of these clouds just follow the instructions here.