Skip to main content

​
Overview

ClassroomIO uses Supabase for its database and authentication. For local development, you’ll run Supabase locally using Docker instead of using the cloud version.

​
Prerequisites

Before starting, ensure you have:

​
Installing Supabase CLI

If you haven’t installed the Supabase CLI yet: 
npm install -g supabase

​
Starting Supabase Locally

​
1. Start Docker

Make sure Docker is running on your machine. You can verify by running: 
docker --version

​
2. Start Supabase

From the project root directory, start Supabase: 
supabase start
This command will:
  • Pull necessary Docker images (first time only)
  • Start all Supabase services locally
  • Run database migrations automatically
  • Set up authentication
  • Create seed data for testing

​
3. Get Your Credentials

Once Supabase starts successfully, you’ll see output like this: 
supabase local development setup is running.

     API URL: http://127.0.0.1:54321
 GraphQL URL: http://127.0.0.1:54321/graphql/v1
       DB URL: postgresql://postgres:[email protected]:54322/postgres
   Studio URL: http://127.0.0.1:54323
 Inbucket URL: http://127.0.0.1:54324
   JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
     anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU
Save these credentials - you’ll need them for the next step!

​
4. Configure Environment Variables

Add the Supabase credentials to your apps/dashboard/.env file: 
PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
PUBLIC_SUPABASE_ANON_KEY=<anon key from supabase start output>
PRIVATE_SUPABASE_SERVICE_ROLE=<service_role key from supabase start output>
Also add them to apps/api/.env: 
PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
PUBLIC_SUPABASE_ANON_KEY=<anon key from supabase start output>
PRIVATE_SUPABASE_SERVICE_ROLE=<service_role key from supabase start output>

​
Accessing Supabase Studio

Supabase Studio is a web-based interface for managing your local database.

​
Open Studio

Access the Studio interface at: 
http://127.0.0.1:54323

​
What You Can Do in Studio

  • Table Editor: View and edit database tables
  • SQL Editor: Run custom SQL queries
  • Authentication: Manage users and authentication settings
  • Storage: Manage file uploads
  • Database: View schema and relationships
  • API Docs: Auto-generated API documentation

​
Working with Migrations

​
Viewing Existing Migrations

Migrations are located in the supabase/migrations/ directory. These are automatically applied when you run supabase start.

​
Creating a New Migration

If you need to make database changes: 
supabase migration new migration_name
This creates a new migration file in supabase/migrations/.

​
Applying Migrations

Migrations are automatically applied on supabase start. To manually apply migrations: 
supabase db reset
This will reset your local database and re-run all migrations, deleting any test data you’ve created.

​
Pushing Migrations to Cloud

If you’re working with Supabase Cloud, you can push local migrations: 
pnpm supabase:push
Or manually: 
supabase link --project-ref YOUR_PROJECT_ID
supabase db push --include-all

​
Database Access

​
Using the PostgreSQL Connection

You can connect to the local database directly using the DB URL: 
postgresql://postgres:[email protected]:54322/postgres
Use this with tools like:
  • pgAdmin
  • DBeaver
  • DataGrip
  • VS Code PostgreSQL extensions

​
Using the GraphQL API

Supabase also provides a GraphQL endpoint: 
http://127.0.0.1:54321/graphql/v1

​
Testing Email Features

​
Inbucket Email Testing

Local Supabase includes Inbucket for testing email functionality: 
http://127.0.0.1:54324
All emails sent by the application will be captured here, including:
  • Email verification
  • Password resets
  • Invitation emails

​
Managing Supabase Services

​
Check Status

To view the status of all Supabase services: 
supabase status

​
Stop Supabase

To stop all Supabase services: 
supabase stop

​
Stop and Reset

To stop Supabase and remove all data: 
supabase stop --no-backup

​
Common Issues

​
Docker Not Running

If you get an error about Docker not running:
  1. Start Docker Desktop
  2. Wait for Docker to fully start
  3. Run supabase start again

​
Port Already in Use

If ports 54321-54324 are already in use:
  1. Stop other services using these ports
  2. Or stop Supabase with supabase stop and restart

​
Migrations Not Applying

If migrations aren’t applying correctly: 
supabase db reset
This will reset the database and re-run all migrations.

​
Cannot Connect to Database

Ensure:
  1. Docker is running
  2. Supabase services are started (supabase status)
  3. Your .env files have the correct credentials
  4. The API URL uses 127.0.0.1 not localhost

​
Seed Data

The local Supabase instance comes with seed data that includes:
  • Demo admin account
  • Demo student accounts
  • Sample courses and lessons
  • Test organizations
See the Demo Accounts guide for login credentials.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us