
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.
Table of Contents
Toggle1. 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 id
, email
, 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.