Local Development Setup

Set up a complete local Supabase development environment with automated scripts, pre-configured test users, multi-tenant organizations, and RLS-scoped sample data.

Overview

The local development environment gives you:

• Full Supabase stack running in Docker (database, auth, API, Studio)
• 5 pre-seeded test users with different roles and org memberships
• 3 organizations with proper RLS isolation
• Sample MCP servers, agent cards, tools, and resources
• One-command startup with ./scripts/start-local-supabase.sh --quick

Time required: ~5 minutes (first run downloads Docker images)

Prerequisites

Quick Start

Using A²D CLI (Recommended)

git clone <a2d-repo-url> && cd a2d
git submodule update --init --recursive
./a2d start

Using Direct Scripts (Alternative)

git clone <repo-url> && cd a2d-portal
 
npm install
 
chmod +x scripts/*.sh
 
./scripts/start-local-supabase.sh --quick
 
cp .env.supabase .env.local
 
npm run dev

Open your browser:

• App: http://localhost:3000
• Supabase Studio: http://127.0.0.1:54323

Log in with alpha-owner@test.local / password123.

Step-by-Step Setup

Step 1: Clone and Install

git clone <repo-url>
cd a2d-portal
npm install

Step 2: Make Scripts Executable

chmod +x scripts/*.sh

You only need to do this once.

Step 3: Start Local Supabase

./scripts/start-local-supabase.sh

The script will:

1. Check all prerequisites (Docker, Supabase CLI, psql, Node.js)
2. Ask if you want to pull data from a remote environment (optional)
3. Run supabase start (downloads Docker images on first run)
4. Apply all database migrations automatically
5. Seed the database with 5 test users, 3 organizations, and sample assets
6. Generate .env.supabase with local credentials and A2D_PLATFORM_ADMIN_EMAILS
7. Optionally start the Next.js dev server

Step 4: Set Up Next.js Environment

If you did not let the script start the dev server, do it manually:

cp .env.supabase .env.local
 
npm run dev

Step 5: Verify Everything Works

1. Open http://localhost:3000
2. Log in with alpha-owner@test.local / password123
3. You should see “Local Test Org Alpha” as your organization
4. You should see the “Weather Service” and “Calculator API” MCP servers

Test Users and Credentials

All users share the same password: password123

User UUIDs

Use these when debugging queries or inspecting RLS behavior:

Organizations

Membership Breakdown

RLS Visibility Matrix

Row-Level Security is organization-scoped. Each user only sees data belonging to their current_organization_id.

What Each User Can See

Key RLS Behaviors

• Organization isolation — alpha-owner CANNOT see Org Beta data, and vice versa
• Same-org members see same data — alpha-owner and alpha-member see identical assets
• Owner vs member — Both roles see the same data; owner can manage org settings and invite members
• Multi-org switching — multi-org’s visible data changes when they switch current_organization_id
• Platform admin — admin@test.local gets admin UI access via the A2D_PLATFORM_ADMIN_EMAILS env var, not via RLS

Testing RLS Isolation

To verify isolation is working:

1. As alpha-owner — See Weather Service + Calculator API. Do NOT see Inventory Service.
2. As beta-owner — See Inventory Service. Do NOT see Weather Service or Calculator API.
3. As multi-org — See Alpha data by default. After switching org to Beta, see only Beta data.
4. As alpha-member — See exact same data as alpha-owner (same org).

Seeded Test Data

MCP Servers

MCP Tools

Agent Cards

Environment Variables

The start script generates .env.supabase automatically. Copy it to .env.local for Next.js:

cp .env.supabase .env.local

Generated Variables

Additional Variables

These are NOT auto-generated. Add them to .env.local manually if needed:

NEXT_PUBLIC_APP_URL=http://localhost:3000

NEXT_PUBLIC_A2L_URL=http://a2l.localhost:3000

NEXT_PUBLIC_A2TF_URL=http://a2tf.localhost:3000

CREDENTIALS_ENCRYPTION_KEY=<run: openssl rand -hex 32>

LOG_LEVEL=debug

# Rate limiting configuration (optional)
MAX_PUBLIC_RATE_LIMIT=1000
PLATFORM_RATE_LIMIT=500

Rate Limiting Configuration

Rate limits are configurable via environment variables. In development mode, rate limiting is automatically disabled to make local testing easier.

Environment Variables:

Setting Custom Limits:

# Add to .env.local
MAX_PUBLIC_RATE_LIMIT=1000
PLATFORM_RATE_LIMIT=500

Per-Organization Overrides:

Public MCP endpoints support per-organization rate limit overrides via the database:

-- Set organization-specific limit
UPDATE organizations
SET max_public_rate_limit = 500
WHERE name = 'Premium Tier';
 
-- View current org limits
SELECT name, max_public_rate_limit
FROM organizations
WHERE max_public_rate_limit IS NOT NULL;
 
-- Remove override (use global MAX_PUBLIC_RATE_LIMIT)
UPDATE organizations
SET max_public_rate_limit = NULL
WHERE name = 'Premium Tier';

The actual limit applied is: min(org.max_public_rate_limit, MAX_PUBLIC_RATE_LIMIT)

Testing Different Rate Limit Scenarios:

By default, rate limiting is disabled in development. To test rate limits locally:

# Enable rate limiting in development
NODE_ENV=production npm run dev

Then make rapid requests to test the limits:

# Test public endpoint rate limiting
for i in {1..105}; do
  echo "Request $i"
  curl -X POST http://localhost:3000/api/platform/test-server/mcp \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"},"capabilities":{}}}' \
    -w "\nStatus: %{http_code}\n"
  sleep 0.5
done

Expected behavior:

• Requests 1-100: Status: 200 (within limit)
• Requests 101+: Status: 429 (rate limited)

Logging Configuration

Control logging verbosity with the LOG_LEVEL environment variable:

Example:

LOG_LEVEL=debug npm run dev

This enables detailed logging for MCP endpoints, rate limiting, and middleware operations.

Social Login (Google/GitHub)

The “Continue with Google” and “Continue with GitHub” buttons on the login and signup pages are not configured out of the box in local dev — each requires its own OAuth app registration and environment variables, and Google also needs a one-time supabase/config.toml change (which start-local-supabase.sh can apply automatically).

Local Endpoints

Common Workflows

Switching multi-org User’s Organization

In psql or Supabase Studio SQL editor:

UPDATE users
SET current_organization_id = '22222222-2222-2222-2222-222222222222'
WHERE email = 'multi-org@test.local';

Refresh the browser to see the new org’s data. Switch back with:

UPDATE users
SET current_organization_id = '11111111-1111-1111-1111-111111111111'
WHERE email = 'multi-org@test.local';

Creating a New Test User

INSERT INTO auth.users (id, instance_id, email, encrypted_password,
  email_confirmed_at, aud, role, raw_user_meta_data, created_at, updated_at)
VALUES (
  gen_random_uuid(), '00000000-0000-0000-0000-000000000000',
  'newuser@test.local', crypt('password123', gen_salt('bf')),
  now(), 'authenticated', 'authenticated',
  '{"full_name": "New User"}', now(), now()
);

Then get the UUID and create the public user and org membership:

SELECT id FROM auth.users WHERE email = 'newuser@test.local';
 
INSERT INTO users (id, email, full_name, organization_id, current_organization_id)
VALUES ('<uuid>', 'newuser@test.local', 'New User',
  '11111111-1111-1111-1111-111111111111',
  '11111111-1111-1111-1111-111111111111');
 
INSERT INTO organization_members (user_id, organization_id, role)
VALUES ('<uuid>', '11111111-1111-1111-1111-111111111111', 'member');

Inspecting RLS as a Specific User

SET LOCAL ROLE authenticated;
SELECT set_config('request.jwt.claims',
  '{"sub":"aaaa0001-0001-0001-0001-000000000001"}', true);
 
SELECT name FROM mcp_servers;
 
RESET ROLE;

Resetting the Database

supabase db reset
 
psql postgresql://postgres:postgres@127.0.0.1:54322/postgres -f scripts/seed-local.sql

Running Tests

supabase test db
 
npm test
 
npm run test:api
 
npm run test:actions

Script Reference

start-local-supabase.sh

./scripts/start-local-supabase.sh --quick
 
./scripts/start-local-supabase.sh --env staging
 
./scripts/start-local-supabase.sh --no-seed

stop-local-supabase.sh

./scripts/stop-local-supabase.sh
 
./scripts/stop-local-supabase.sh --clean

Pulling Remote Data

You can optionally pull data from production, staging, or dev environments.

One-Time Setup

supabase login
 
cp .supabase-projects.json.example .supabase-projects.json

Edit .supabase-projects.json with your project refs from the Supabase Dashboard:

{
  "production": "your-production-ref",
  "staging": "your-staging-ref",
  "dev": "your-dev-ref"
}

Then start with a specific environment:

./scripts/start-local-supabase.sh --env staging

Rate Limiting in Development

Rate limiting is automatically disabled in development mode to make local testing easier.

How It Works

Rate limiting is only enforced when NODE_ENV=production:

if (process.env.NODE_ENV !== 'production') {
  // Skip rate limiting
  return { allowed: true }
}

In Development:

• Unlimited requests to all MCP endpoints
• No rate limit headers in responses
• No 429 errors
• Logging shows “Rate limiting disabled (not production)”

In Production:

• Public endpoints: 100 requests/minute per IP
• Platform endpoints: 500 requests/minute per organization
• Rate limit headers included in all responses
• 429 errors when limits exceeded

Testing Rate Limits Locally

To test rate limiting in development, temporarily set NODE_ENV:

NODE_ENV=production npm run dev

Troubleshooting

Docker is not running

Start Docker Desktop and wait for it to fully initialize before retrying.

supabase start fails or hangs

supabase stop
 
docker system prune -f
 
supabase start

Port already in use

lsof -i :54321
 
supabase stop

Login fails with “Invalid login credentials”

Verify the seed ran successfully:

psql postgresql://postgres:postgres@127.0.0.1:54322/postgres \
  -c "SELECT email FROM auth.users;"

If empty, re-run the seed:

psql postgresql://postgres:postgres@127.0.0.1:54322/postgres \
  -f scripts/seed-local.sql

Admin UI not accessible for admin@test.local

Verify the env var is set:

grep A2D_PLATFORM_ADMIN_EMAILS .env.local

If missing, add it and restart the dev server:

echo "A2D_PLATFORM_ADMIN_EMAILS=admin@test.local" >> .env.local

Complete fresh start

./scripts/stop-local-supabase.sh --clean
 
docker system prune -af --volumes
 
./scripts/start-local-supabase.sh --quick
cp .env.supabase .env.local
npm run dev

Safety Rules

Deployed environments apply migrations automatically on deploy — never seed a deployed environment. See Migrations run automatically on deploy below.

Deployed schema is CLI-managed

The Supabase CLI is the source of truth for the deployed database schema. Schema changes go through supabase migration new + supabase db push only — never by applying SQL by hand in the Supabase Studio editor. Direct-in-editor changes create drift: the remote migration ledger (supabase_migrations.schema_migrations) stops matching the files in supabase/migrations/, and the next supabase db push either fails or silently skips a change.

The one-time recovery is codified in a2d-portal/scripts/recover-migration-state.sh (dry-run by default; pass --apply to execute):

# Preview what recovery would do (no changes):
./scripts/recover-migration-state.sh --env dev
./scripts/recover-migration-state.sh --env production
 
# Execute recovery (dev first, then production):
./scripts/recover-migration-state.sh --env dev --apply
./scripts/recover-migration-state.sh --env production --apply

The script picks its strategy per migration from the live database state rather than the environment name. It probes each migration’s marker object (its first CREATE TABLE or ADD COLUMN) against the live database and resolves to one of:

• reconcile — every migration’s object already exists (editor-built): mark each applied with supabase migration repair — no SQL is re-run.
• push — no application schema exists at all (a genuinely fresh target): execute the migrations for the first time.
• mixed — some migrations are applied (objects present) and some were never run (objects absent): reconcile the present ones, repair --status reverted any absent-but-recorded ones, then db push only the absent ones.

Recovery is complete when supabase db diff --linked is empty and supabase db push --linked --dry-run reports zero pending migrations on both environments.

Migrations run automatically on deploy

Once an environment is on a clean CLI baseline (see above), pending migrations are applied as part of every deploy — no manual supabase db push step. A single script, a2d-portal/scripts/deploy-migrate.sh, runs in both deploy contexts, distinguished only by environment-scoped secrets:

• Vercel (prod): the buildCommand in vercel.json runs the script before next build (bash scripts/deploy-migrate.sh && npm run build), applying pending migrations to the production Supabase project.
• Heroku (dev): the release: phase in Procfile runs the same script, applying pending migrations to the dev project.

The script runs supabase db push --db-url "$SUPABASE_DB_URL" — no link, no access token, no seeding — using the Supabase CLI pinned as a devDependency (invoked via npx, so Vercel, Heroku, and local all match). A migration failure returns a non-zero exit that fails the deploy, so code never ships against an un-migrated database.

Required secret (environment-scoped): set SUPABASE_DB_URL to the project’s direct connection string — the prod value in Vercel (Production scope), the dev value in Heroku config vars. Use the direct connection (db.<ref>.supabase.co:5432) or a session-mode pooler — not the :6543 transaction pooler, which cannot run migration DDL — and percent-encode the password. The NEXT_PUBLIC_SUPABASE_* keys and SUPABASE_SERVICE_ROLE_KEY cannot run migrations; they are PostgREST/Auth keys, not a Postgres connection.

Because the new schema is applied during the deploy window, migrations should be backward-compatible with the currently-running code (use an expand/contract sequence for breaking changes). Preview what a deploy would apply with:

npx supabase db push --db-url "$SUPABASE_DB_URL" --dry-run

Next Steps

• Database Setup — production Supabase setup
• MCP Servers — learn about creating MCP servers
• Agent Cards — learn about A2A agent cards
• Architecture: Multi-Tenancy — understand the RLS model

Ready to start? Run ./scripts/start-local-supabase.sh --quick and you are up in under 5 minutes.