Hasura GraphQL Engine One-click App on DigitalOcean Marketplace

Introduction

The Hasura GraphQL Engine is available as a One-click app on the DigitalOcean Marketplace. It is packed with a Postgres database and Caddy webserver for easy and automatic HTTPS using Let's Encrypt.

Deploying Hasura on DigitalOcean

Step 1: Create a Hasura One-click Droplet

Click the button below to create a new Hasura GraphQL Engine Droplet through the DigitalOcean Marketplace. For first time users, the link also contains a referral code which gives you $100 over days. A $5 droplet is good enough to support most workloads. (Ctrl+Click to open in a new tab)

Step 2: Open the Console

Once the Hasura GraphQL Engine Droplet is ready, you can visit the Droplet IP to open the Hasura Console, where you can create tables, explore GraphQL APIs etc. Note that it might take 1 or 2 minutes for everything to start running.

The Droplet IP is highlighted in the image below:

The Hasura Console will be at:

http://<your_droplet_ip>/console

The GraphQL endpoint will be:

http://<your_droplet_ip>/v1/graphql

A Postgres database is also provisioned on the Droplet. Using the Console, you can create a table on this Postgres instance and make your first GraphQL query.

Step 3: Create a table

Navigate to Data -> Add table on the Console and create a table called profile with the following columns:

profile

column name	type
id	Integer (auto-increment)
name	Text

Choose id as the Primary key and click the Add Table button.

Step 4: Insert sample data

Once the table is created, go to the Insert Row tab and insert some sample rows:

Thor
Iron Man
Hulk
Captain America
Black Widow

Step 5: Try out GraphQL

Switch to the API tab on top and execute the following GraphQL query:

query {
  profile {
    id
    name
  }
}

Securing the GraphQL endpoint

By default Hasura is exposed without any admin secret. Anyone can read and write to your database using GraphQL. When deploying to production, you should secure the endpoint by adding an admin secret key and then setting up permission rules on tables.

To add an admin secret key, follow the steps described below:

Step 1: Connect to the Droplet via SSH

ssh root@<your_droplet_ip>

Step 2: Go to the /etc/hasura directory

cd /etc/hasura

Step 3: Set an admin secret

Edit docker-compose.yaml and un-comment the line that mentions admin secret key. Also change it to some unique secret:

vim docker-compose.yaml

...
# un-comment next line to add an admin secret key
HASURA_GRAPHQL_ADMIN_SECRET: <myadminsecretkey>
...

# type ESC followed by :wq to save and quit

Step 4: Update the container

docker compose up -d

That's it. Visit the Console at http://<your_droplet_ip>/console and it should prompt for the admin secret key. Further API requests can be made by adding the following header:

X-Hasura-Admin-Secret: <myadminsecretkey>

Adding a domain & enabling HTTPS

If you own a domain, you can enable HTTPS on this Droplet by mapping the domain to the Droplet's IP. The Hasura GraphQL Droplet is configured with Caddy which is an HTTP/2 web server with automatic HTTPS using Let's Encrypt.

Step 1: Add a record mapping

Go to your domain's DNS dashboard and add an A record mapping the domain to the Droplet IP.

Step 2: Connect to the Droplet via SSH

ssh root@<your_droplet_ip>

Step 3: Go to the /etc/hasura directory

cd /etc/hasura

Step 4: Edit the Caddyfile and change :80 to your domain

vim Caddyfile

...

 https://you.domain.example.com {
  reverse_proxy * graphql-engine:8080 {
      header_up Host {http.request.host}
      header_up X-Real-IP {http.request.remote}
      header_up X-Forwarded-For {http.request.remote}
      header_up X-Forwarded-Port {http.request.port}
      header_up X-Forwarded-Proto {http.request.scheme}
  }
}
...

# type ESC followed by :wq to save and quit

Step 5: Restart the container

docker compose restart caddy

Go to https://<your_domain>/console to visit the Hasura Console.

Updating to the latest version

When a new version of the GraphQL Engine is released, you can upgrade to it by just changing the version tag in docker-compose.yaml. You can find the latest releases on the GitHub releases page.

Step 1: Connect to the Droplet via SSH

ssh root@<your_droplet_ip>

Step 2: Go to the /etc/hasura directory

cd /etc/hasura

Step 3: Edit docker-compose.yaml and change the image tag to the latest one

vim docker-compose.yaml

...
graphql-engine:
   image: hasura/graphql-engine:latest_tag_here
...

# type ESC followed by :wq to save and quit

Step 4: Restart the container

docker compose up -d

Using DigitalOcean Managed Postgres Database

Step 1: Create a Postgres database

Create a new Postgres database from the DigitalOcean console, preferably in the same region as the Droplet.

Step 2: Get the database URL

Once the database is created, under the "Overview" tab, from the "Connection Details" section, choose "Connection string" from the dropdown. "Connection string" is the "Database URL". Copy it.

Step 3: Connect to the Droplet via SSH

ssh root@<your_droplet_ip>

Step 4: Go to the /etc/hasura directory

cd /etc/hasura

Step 5: Edit docker-compose.yaml and change the database URL

vim docker-compose.yaml

...
# change the url to use a different database for your metadata
HASURA_METADATA_DATABASE_URL: <database-url>
# and here for your data using the same or different database as above
PG_DATABASE_URL: <database-url>
...

# type ESC followed by :wq to save and quit

Similarly, the database URL can be changed to connect to any other Postgres database.

Note

If you're using Hasura with a restricted database user, make sure you go through Postgres permissions to configure all required permissions (not applicable with the default connection string with DO Managed Postgres).

Connection pooling

Connection pooling is a built-in feature of graphql-engine. The default connection pool size is 50. If you need to configure the pool size or the timeout, you can use the below environment variables.

• HASURA_GRAPHQL_PG_CONNECTIONS: Maximum number of Postgres connections that can be opened per stripe (default: 50).
• HASURA_GRAPHQL_PG_TIMEOUT: Each connection’s idle time before it is closed (default: 180 sec)

Note

If you still want to enable connection pooling on your managed database on DigitalOcean, you should do so in the session mode.

Access database via psql

To access the Postgres database via psql, you can use the following command via the terminal:

docker exec -it hasura_postgres_1 psql -U postgres

If you are using a hosted database as outlined above, it's a little different:

docker exec -it hasura_postgres_1 psql -h <your database url> -p <your port> -d <your database> -U <your database user>

Note

Different hosted Postgres providers may have different requirements for connection, e.g. setting sslmode. Please refer to your provider's documentation for generating the proper psql command flags.

Logs

Step 1: Connect to the Droplet via SSH

ssh root@<your_droplet_ip>

Step 2: Go to the /etc/hasura directory

cd /etc/hasura

Step 3: Check logs

To checks logs for any container, use the following command:

docker compose logs <container_name>

Where <container_name> is one of graphql-engine, postgres or caddy.

Troubleshooting

Logs should be able to help you in most scenarios. If it doesn't, feel free to talk to us on Discord.