Getting Started

Set up your development environment and run Rolebase locally.

Prerequisites

Before you begin, make sure you have the following installed:

Node.js (v18 or later)
npm (comes with Node.js)
Docker and Docker Compose (required for Nhost local development)
Nhost CLI (installed globally)

Docker Required

Nhost runs its backend services (PostgreSQL, Hasura, Auth, Storage) inside Docker containers. Make sure Docker Desktop is running before proceeding.

Clone the Repository

git clone https://github.com/Godefroy/rolebase.git
cd rolebase.io

Install Dependencies

Rolebase uses npm workspaces. Install all dependencies from the root:

npm install

This installs dependencies for all packages: webapp, backend, shared, and more.

Set Up Nhost

Rolebase uses Nhost for authentication, database (PostgreSQL via Hasura), and storage. For local development you run Nhost locally with the CLI.

Log in to Nhost

nhost login

Start the Nhost Backend

nhost up

This spins up local instances of PostgreSQL, Hasura, Nhost Auth, and Nhost Storage via Docker. The first run may take a few minutes to pull images.

Hasura Console

Once Nhost is running, you can access the Hasura Console at http://localhost:9695 to inspect the database schema and run GraphQL queries.

Configure Secrets

Create a .secrets file at the root of the Nhost configuration if one does not already exist. This file holds environment-specific secrets (SMTP credentials, API keys, etc.) that are required by certain backend functions.

Do not commit secrets

The .secrets file is git-ignored. Never commit credentials or API keys to the repository.

Run the Development Server

Start the webapp in development mode:

npm run dev

Then open your browser at http://localhost:3000.

Project Structure

The repository is organized as an npm workspace monorepo:

Package	Description
`packages/webapp`	React frontend (Vite, Chakra UI)
`packages/backend`	tRPC backend and serverless functions
`packages/shared`	Shared types and utilities
`packages/website`	Documentation site (Astro)

Next Steps

Explore the Custom Integrations guide to learn about the GraphQL API.
Browse the API Reference for the full entity schema.