# Running Supamode Locally

> Start Supamode's development servers and Supabase, seed demo data, and configure your own database tables.

*Canonical: https://makerkit.dev/docs/supamode/installation/running-project*

---

This guide covers starting Supamode locally, seeding demo data to explore the interface, and connecting your own Supabase project.

## Quick Start

Start both servers in parallel (requires two terminal windows):

**Terminal 1: Start Supabase**
```bash
pnpm run supabase:web:start
```

**Terminal 2: Start development servers**
```bash
pnpm dev
```

Open `http://localhost:5173` and sign in with:
- **Email**: `root@supamode.com`
- **Password**: `testingpassword`

{% alert type="default" title="Demo Data Required" %}
The demo credentials only work after seeding the database. See [Step 3](#3-seed-demo-data) below.
{% /alert %}

## Step-by-Step Setup

### 1. Start the Development Servers

Run the `dev` command to start both the frontend and backend:

```bash
pnpm dev
```

This starts:

| Service | URL | Technology |
|---------|-----|------------|
| **Frontend** | `http://localhost:5173` | Vite + React Router 7 |
| **API** | `http://localhost:3000` | Hono.js |

Vite proxies all `/api/*` requests to the Hono backend automatically, so the frontend can make API calls without CORS configuration.

### 2. Start Supabase

Ensure Docker is running, then start the Supabase containers:

```bash
pnpm run supabase:web:start
```

Supamode uses non-standard ports to avoid conflicts with your main application's Supabase instance:

| Service | URL | Purpose |
|---------|-----|---------|
| **Supabase API** | `http://localhost:54331` | REST and Realtime APIs |
| **PostgreSQL** | `localhost:54332` | Direct database access |
| **Supabase Studio** | `http://localhost:54333` | Database admin UI |
| **InBucket** | `http://localhost:54334` | Email testing |

### 3. Seed Demo Data

To explore Supamode with sample data, run the demo schema installation. Open Supabase Studio at `http://localhost:54333`, go to the SQL Editor, and run:

```sql
call supamode.install_demo_schema();
```

This creates:
- Sample tables (`posts`, `categories`, `tags`, etc.)
- Four user accounts with different permission levels
- Pre-configured roles and permissions
- Sample data to browse and edit

### 4. Sign In

After seeding, sign in at `http://localhost:5173` with one of these accounts:

| Role | Email | Password | Permissions |
|------|-------|----------|-------------|
| **Root** | `root@supamode.com` | `testingpassword` | Full access to everything |
| **Admin** | `admin@supamode.com` | `testingpassword` | System administration |
| **Member** | `member@supamode.com` | `testingpassword` | Data read/write |
| **Read-only** | `readonly@supamode.com` | `testingpassword` | View only |

Try signing in with different roles to see how the RBAC system restricts access. The read-only user, for example, cannot edit records or access settings.

## Using Your Own Data

Once you've explored the demo, connect Supamode to your own Supabase project.

### Option A: Local Development (Supabase Emulator)

If your project also uses the Supabase emulator locally, point Supamode to your project's ports.

**In `apps/app/.env`:**
```bash
VITE_SUPABASE_URL=http://localhost:54321
```

**In `apps/api/.env`:**
```bash
SUPABASE_URL=http://localhost:54321
SUPABASE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
```

Then add your migrations to `apps/app/supabase/seeds/` so they run when Supamode's database resets.

### Option B: Remote Supabase Project

To connect to a hosted Supabase project:

**In `apps/app/.env`:**
```bash
VITE_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
```

**In `apps/api/.env`:**
```bash
SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_DATABASE_URL=postgresql://postgres:PASSWORD@db.YOUR_PROJECT.supabase.co:5432/postgres
```

### Sync Your Tables

After connecting to your database, sync your tables into Supamode's metadata system:

```sql
-- Sync all tables in a schema
select supamode.sync_managed_tables('public');

-- Or sync specific tables
select supamode.sync_managed_tables('public', 'users');
select supamode.sync_managed_tables('public', 'orders');
select supamode.sync_managed_tables('public', 'products');

-- Sync tables from custom schemas
select supamode.sync_managed_tables('billing', 'invoices');
select supamode.sync_managed_tables('billing', 'subscriptions');
```

{% alert type="warning" title="Permissions Required" %}
The demo seed only grants permissions to the `public` schema. For custom schemas, [configure permissions](../configuration/permissions) before your team can access them.
{% /alert %}

### Reset the Database

After adding your migrations and sync commands, reset to apply them:

```bash
pnpm run supabase:web:reset
```

This drops and recreates the database, runs all migrations, and executes seed files in order.

## Development Commands

Common commands for local development:

| Command | Purpose |
|---------|---------|
| `pnpm dev` | Start frontend and API servers |
| `pnpm supabase:web:start` | Start Supabase containers |
| `pnpm supabase:web:stop` | Stop Supabase containers |
| `pnpm supabase:web:reset` | Reset database and run seeds |
| `pnpm supabase:web:typegen` | Generate TypeScript types from schema |
| `pnpm lint:fix` | Fix linting issues |
| `pnpm typecheck` | Run TypeScript compiler checks |
| `pnpm test:unit` | Run unit tests |

## Troubleshooting

### "Invalid login credentials"

The demo accounts only exist after running the seed. Ensure you ran:

```sql
call supamode.install_demo_schema();
```

### Port Already in Use

If port 5173 or 3000 is busy, check for running processes:

```bash
lsof -i :5173
lsof -i :3000
```

Kill the process or change Supamode's ports in the Vite and Hono configs.

### Supabase Won't Start

Docker must be running. On macOS/Windows, ensure Docker Desktop is open. On Linux:

```bash
sudo systemctl start docker
```

If containers are stuck, try a fresh start:

```bash
pnpm supabase:web:stop
docker system prune -f
pnpm supabase:web:start
```

### Changes Not Reflecting

Vite uses hot module replacement, but some changes (especially to API routes) require a restart:

```bash
# Stop servers with Ctrl+C, then restart
pnpm dev
```

For database schema changes, reset the database:

```bash
pnpm supabase:web:reset
```

## Next Steps

- **[Configure tables](../configuration/tables)** to customize display names and formats
- **[Set up RBAC](../configuration/rbac)** to define roles and permissions
- **[Explore the Data Explorer](../features/data-explorer)** to learn navigation and filtering
- **[Deploy to production](../deployment/overview)** when ready