Hasura GraphQL Engine One-click App on DigitalOcean Marketplace

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.

Quickstart

1. Create a Hasura One-click Droplet

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

do_create_droplet_button

2. Open console

Once 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 Hasura console will be at:

http://<your_droplet_ip>/console

The GraphQL Endpoint will be:

http://<your_droplet_ip>/v1alpha1/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.

Hasura console

3. Create a table

Navigate to Data -> Create 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 Create button.

Hasura console - create table

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
Hasura console - insert data

5. Try out GraphQL

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

query {
  profile {
    id
    name
  }
}
Hasura console - GraphiQL

Secure 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 given below:

  1. Connect to the Droplet via SSH:

    ssh root@<your_droplet_ip>
    
  2. Goto /etc/hasura directory:

    cd /etc/hasura
    
  3. 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
    
  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.

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

  2. Connect to the Droplet via SSH:

    ssh root@<your_droplet_ip>
    
  3. Goto /etc/hasura directory:

    cd /etc/hasura
    
  4. Edit Caddyfile and change :80 to your domain:

    vim Caddyfile
    
    ...
    add_your-domain-here {
      proxy / graphql-engine:8080 {
        websocket
      }
    }
    ...
    
    # type ESC followed by :wq to save and quit
    
  5. Restart the container:

    docker-compose restart caddy
    

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

Updating to the latest version

When a new version of 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.

  1. Connect to the Droplet via SSH:

    ssh root@<your_droplet_ip>
    
  2. Goto /etc/hasura directory:

    cd /etc/hasura
    
  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
    
  4. Restart the container:

    docker-compose up -d
    

Using DigitalOcean Managed Postgres Database

  1. Create a new Postgres Database from DigitalOcean Console, preferably in the same region as the Droplet.

  2. Once the database is created, under the “Overview” tab, from the “Connection Details” section, choose “Connection string” from the dropdown.

  3. “Connection string” is the “Database URL” - copy it.

  4. Connect to the Droplet via SSH:

    ssh root@<your_droplet_ip>
    
  5. Goto /etc/hasura directory:

    cd /etc/hasura
    
  6. Edit docker-compose.yaml and change the database URL:

    vim docker-compose.yaml
    
    ...
    # change the url to use a different database
    HASURA_GRAPHQL_DATABASE_URL: <database-url>
    ...
    
    # type ESC followed by :wq to save and quit
    

Similarly, 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)

Logs

  1. Connect to the Droplet via SSH:

    ssh root@<your_droplet_ip>
    
  2. Goto /etc/hasura directory:

    cd /etc/hasura
    
  3. 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.