Skip to main content
Version: v2.x

Run Hasura GraphQL engine on Heroku

Introduction​

This guide shows how to deploy Hasura GraphQL engine on Heroku.

Deploying Hasura on Heroku​

Option 1: One-click deployment​

Click the below button to deploy Hasura on Heroku in a few seconds:

heroku_deploy_button

Note

If you don't have an account on Heroku, you need to sign up on Heroku. You won't need a credit card, and once you sign up you'll be redirected to your Heroku app creation page automatically.

Deploy to Heroku

Heroku's free Postgres add-on is automatically provisioned.

Once the deployment is complete, click on the View button to open the Hasura Console where you can connect a database.

Option 2: Deploy via Heroku CLI​

Follow these instructions to create a new Heroku app with a Postgres add-on using the Heroku CLI.

Step 1: Clone the Hasura GraphQL engine Heroku app​

The Hasura app with Heroku buildpack/configuration is available at:

https://github.com/hasura/graphql-engine-heroku

Step 2: Create an app with --stack=container​

Use the Heroku CLI to create a new Heroku app from inside the cloned directory. Let's call the app todo-hasura1.

# Replace todo-hasura1 with whatever you'd like your app to be called
$ heroku create todo-hasura1 --stack=container

Creating β¬’ todo-hasura1... done, stack is container
https://todo-hasura1.herokuapp.com/ | https://git.heroku.com/todo-hasura1.git

Note:

Step 3: Create the Heroku Postgres add-on​

Create the Postgres add-on in your Heroku app.

$ heroku addons:create heroku-postgresql:hobby-dev -a todo-hasura1

Creating heroku-postgresql:hobby-dev on β¬’ todo-hasura1... free
Database has been created and is available
! This database is empty. If upgrading, you can transfer
! data from another database with pg:copy
Created postgresql-angular-20334 as DATABASE_URL
Use heroku addons:docs heroku-postgresql to view documentation

Step 4: git push to deploy​

Remember to change HEROKU_GIT_REMOTE to your git remote below. In our case: https://git.heroku.com/todo-hasura1.git.

$ git init && git add .
$ git commit -m "first commit"
$ git remote add heroku <HEROKU_GIT_REMOTE>
$ git push heroku master

Visit https://todo-hasura1.herokuapp.com (replace todo-hasura1 with your app name) and you should see the Hasura console where you can connect a database.

Connecting a database​

Option 1: New database​

Head to the Data tab on the console to connect your database. You can connect to the Heroku Postgres database that was set up with your deployment using the DATABASE_URL env var.

Connect db on Heroku

Option 2: Existing database​

Let's say you have an existing Heroku Postgres database with data in it, and you'd like to add GraphQL to it.

Step 1: Configure environment variables​

Add an env var, say PG_DATABASE_URL with your existing Heroku Postgres database URL and a HASURA_GRAPHQL_ADMIN_SECRET if you want to secure your endpoint.

Configure environment variables
Note

The Hasura GraphQL engine needs access permissions to your Postgres database as described in Postgres permissions.

Step 2: Connect your database​

Wait for the GraphQL engine to restart then head to the Data tab on the console and connect your database using the env var added above.

Connect db on Heroku

Step 3: Track tables and relationships​

See Setting up a GraphQL schema using an existing Postgres database to enable GraphQL over the database.

Securing the GraphQL endpoint​

To make sure that your GraphQL endpoint and the Hasura console are not publicly accessible, you need to configure an admin secret key.

Add an admin secret​

Head to the config-vars URL on your Heroku dashboard and set the HASURA_GRAPHQL_ADMIN_SECRET environment variable.

Add an admin secret

Setting this environment variable will automatically restart the dyno. Now when you access your console, you'll be prompted for the admin secret key.

Prompt for the admin secret
Note

The HASURA_GRAPHQL_ADMIN_SECRET should never be passed from the client to Hasura GraphQL engine as it would give the client full admin rights to your Hasura instance. See Authentication & Authorization for information on setting up authentication.

(optional) Use the admin secret with the CLI​

In case you're using the CLI to open the Hasura console, use the admin-secret flag when you open the console:

hasura console --admin-secret=myadminsecretkey

GraphQL engine server logs​

You can use the Heroku CLI to check the logs of the Hasura GraphQL engine deployed on Heroku:

$ heroku logs --app <hasura-graphql-engine-app-name>

2018-10-09T11:18:21.306000+00:00 app[web.1]: {"timestamp":"2018-10-09T11:18:21.305+0000", "level":"info", "type":"http-log", "detail":{"status":200, "query_hash":"48c74f902b53a886f9ddc1b7dd12a4a6020d70c3", "http_version":"HTTP/1.1", "query_execution_time":9.477913e-3, "request_id":"b7bb6fb3-97b3-4c6f-a54a-1e0f71a190e9", "url":"/v1/graphql", "user":{"x-hasura-role":"admin"}, "ip":"171.61.77.16", "response_size":15290, "method":"POST", "detail":null}}
...

See:

Updating GraphQL engine​

This section will help you update the Hasura GraphQL engine running on Heroku.

The current latest version is:

hasura/graphql-engine:v2.3.0

Update to the latest version​

Step 1: Clone the Hasura GraphQL engine Heroku app​

The Hasura app with Heroku buildpack/configuration is available at: https://github.com/hasura/graphql-engine-heroku.

Clone the above repository.

git clone https://github.com/hasura/graphql-engine-heroku
cd graphql-engine-heroku

If you already have this, then pull the latest changes which will have the updated GraphQL engine Docker image.

Step 2: Attach your Heroku app​

Let's say your Heroku app is called hasura-heroku and is running on https://hasura-heroku.herokuapp.com.

From inside the graphql-engine-heroku directory, use the Heroku CLI to configure the git repo you cloned in Step 1 to be able to push to this app.

# Replace <hasura-heroku> with your Heroku app's name
heroku git:remote -a <hasura-heroku>
heroku stack:set container -a <hasura-heroku>

You can find your Heroku git repo in your Heroku - Settings - Info - Heroku Git URL

Step 3: git push to deploy the latest Hasura GraphQL engine​

When you git push to deploy, the Heroku app will get updated with the latest changes:

git push heroku master

Deploy a specific version​

Head to the Dockerfile in the git repo you cloned in step 1. Change the FROM line to the specific version you want. A list of all releases can be found at https://github.com/hasura/graphql-engine/releases.

FROM hasura/graphql-engine:v1.0.0

...
...

Change v1.0.0 to v1.1.0 for example, commit this and then git push heroku master to deploy.

Note

If you are downgrading to an older version of the GraphQL engine you might need to downgrade your metadata catalogue version as described in Downgrading Hasura GraphQL engine

Advanced​