Hasura GraphQL Engine DigitalOcean One-click App

Hasura GraphQL Engine is available as a One-click app on DigitalOcean. 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 on DigitalOcean using One-Click App. (Ctrl+Click to open in a new tab)

do_create_droplet_button

2. Open console

Once Hasura GraphQL Engine One-Click 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 access key. Anyone can read and write to your database using GraphQL. When deploying to production, you should secure the endpoint by adding an access key and then setting up permission rules on tables.

To add an access 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 access key. Also change it to some unique secret:

    vim docker-compose.yaml
    
    ...
    # un-comment next line to add an access key
    HASURA_GRAPHQL_ACCESS_KEY: mysecretaccesskey
    ...
    
    # 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 access key. Further API requests can be made by adding the following header:

X-Hasura-Access-Key: mysecretaccesskey

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 One-Click 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 a different database

  1. Connect to the Droplet via SSH:

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

    cd /etc/hasura
    
  3. Setup the database that you wish to use, preferably via Docker Compose

  4. 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: postgres://<new-database-url>/<new-database-name>
    ...
    
    # type ESC followed by :wq to save and quit
    

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.