Hasura + GoTrue

Self-Hosted Hasura + GoTrue

Self-Hosted Hasura + GoTrue: A Comprehensive Guide

Introduction

In the world of application development, speed and flexibility are crucial. Combining Hasura, a powerful GraphQL engine, with GoTrue, an authentication service, allows developers to build scalable applications rapidly with user authentication capabilities. This guide will take you through the process of self-hosting Hasura and integrating it with GoTrue, covering everything from the initial setup to advanced configurations.


1. Understanding Hasura and GoTrue

1.1. What is Hasura?

Hasura is an open-source engine that provides a real-time GraphQL API over your PostgreSQL database. It allows developers to build applications quickly without worrying about the backend infrastructure. With Hasura, you can:

  • Automatically generate GraphQL endpoints.
  • Execute real-time queries.
  • Manage permissions dynamically.

1.2. What is GoTrue?

GoTrue is an open-source API for managing user authentication and issuing JSON Web Tokens (JWT). It provides a simple and secure means to handle user registration, login, and session management. Key features include:

  • Email and password authentication.
  • JWT-based session management.
  • Integration with third-party OAuth providers.

2. Setting Up the Environment

2.1. Prerequisites

Before starting, ensure you have the following:

  • A modern web browser.
  • Basic knowledge of Docker and command-line interfaces.
  • A PostgreSQL database (Can be hosted or local).
  • Access to a VPS or a local machine to host Hasura and GoTrue.

2.2. Choosing a Hosting Platform

You can host Hasura and GoTrue on various platforms, including:

  • Cloud Providers: AWS, Google Cloud, Azure, DigitalOcean.
  • Local Machine: For development purposes, you can run everything locally.

3. Self-Hosting Hasura

3.1. Installing Docker

To deploy Hasura using Docker, first install Docker on your machine. Follow Docker’s official installation guide to set it up for your OS.

Verify the installation by running:

docker --version

3.2. Deploying Hasura on Docker

Create a docker-compose.yml file for Hasura:

version: '3.6'
services:
  postgres:
    image: postgres:13  
    restart: always  
    environment:
      POSTGRES_DB: hasura  
      POSTGRES_USER: admin  
      POSTGRES_PASSWORD: password  
    ports:
      - "5432:5432"

  hasura:
    image: hasura/graphql-engine:v2.0.10  
    restart: always  
    ports:
      - "8080:8080"
    environment:
      HASURA_GRAPHQL_DATABASE_URL: postgres://admin:password@postgres:5432/hasura  
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey  
    depends_on:
      - postgres

Run the following commands to start Hasura:

docker-compose up -d

3.3. Configuring Hasura

Access the Hasura Console by navigating to http://localhost:8080 in your web browser. Set the admin secret as myadminsecretkey when prompted.

To create tables, click on “Data” in the console and use the UI to create your desired tables. For example, create a simple users table with fields like idemail, and created_at.

4. Setting Up GoTrue

4.1. Deploying GoTrue

To deploy GoTrue, you can also use Docker. Create another docker-compose.yml file:

version: '3.6'
services:
  gotrue:
    image: netlify/gotrue  
    restart: always  
    environment:
      GOTRUE_DATABASE_URL: postgres://admin:password@postgres:5432/hasura  
      GOTRUE_JWT_SECRET: your_jwt_secret  
      GOTRUE_SITE_URL: http://localhost:8080  
    ports:
      - "9999:9999"

Run the following commands to start GoTrue:

docker-compose up -d

4.2. Configuring GoTrue

Once GoTrue is running, you can access it on http://localhost:9999. You can use the REST API to manage users. For example, to register a user, send a POST request to:

POST http://localhost:9999/signup  
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "password"
}

5. Integrating Hasura with GoTrue

5.1. Setting Up Webhook for Authentication

Hasura can use GoTrue to manage authentication by setting up a webhook. Use the Hasura console to navigate to “Actions” and add a new action for user authentication.

5.2. Configuring Hasura Permissions

In the Hasura console, set up permissions for your tables. For the users table, configure permissions for authenticated users to select their own data. This can be done in the “Permissions” tab by setting up roles and their respective permissions.

6. Testing the Setup

6.1. Creating Users with GoTrue

Create a user through the GoTrue API using the method described earlier. Verify the user exists by querying the database or checking through the GoTrue API.

6.2. Accessing Hasura with JWT

Once a user is created, you can log in and obtain a JWT. Use this token to access Hasura:

POST http://localhost:9999/token  
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "password"
}

You’ll receive a JWT that can be used in the Authorization header when making requests to Hasura:

Authorization: Bearer <your_jwt>

7. Advanced Configurations

7.1. Custom Domains

To set up custom domains for Hasura and GoTrue, you’ll need to adjust your DNS settings and configure the server to recognize the domain names.

7.2. SSL Configuration

For secure connections, consider using Let’s Encrypt to obtain SSL certificates for your custom domain. Use certbot to automate this process.

8. Troubleshooting Common Issues

  • Docker Issues: Ensure that Docker is running and correctly installed.
  • Database Connection Errors: Verify your database URL and credentials in the Docker Compose files.
  • Authentication Failures: Check the JWT secret and ensure that GoTrue is correctly issuing tokens.

9. FAQ

Q1: What is the benefit of self-hosting Hasura and GoTrue?

A: Self-hosting allows for greater customization, control over data, and integration with existing systems.

Q2: Can I use Hasura with other authentication methods?

A: Yes, Hasura supports various authentication methods through webhooks and JWT.

Q3: How do I scale this setup for production?

A: Consider using a load balancer, multiple instances of Hasura, and database replication.

Q4: What are some alternatives to GoTrue?

A: Alternatives include Auth0, Firebase Authentication, and AWS Cognito.

Q5: Can I deploy this on a local machine?

A: Yes, this setup can be run locally for development purposes using Docker.

10. Conclusion

Combining Hasura and GoTrue creates a powerful and flexible environment for developing applications with efficient GraphQL APIs and robust user authentication. By following this guide, you’ll be well on your way to building scalable applications with ease. As you navigate through the configurations and optimizations, remember to explore the extensive documentation provided by both Hasura and GoTrue for advanced features and best practices.


 

Index