LOCAL_SUPABASE_SETUP.md

Step-by-Step Setup Guide

This guide will walk you through setting up the local development environment from scratch.

Prerequisites

Before starting, ensure you have:

1. Docker Desktop installed and running

   • Download: https://www.docker.com/products/docker-desktop
   • Make sure Docker Desktop is started (green icon in system tray)

2. Node.js 18+ installed

   • Download: https://nodejs.org/
   • Verify: node --version (should show v18 or higher)

3. npm (comes with Node.js)

   • Verify: npm --version

Step-by-Step Instructions

Step 1: Open Terminal

Open your terminal/command prompt and navigate to the project directory:

cd /Users/fashad/fashad/projects/SymposAI_backend

Step 2: Verify Docker is Running

docker info

Expected output: Docker information (not an error)

If error: Start Docker Desktop application

Step 3: Run the Setup Script

Run the automated setup script:

./scripts/setup-local.sh

What this does:

• ✅ Checks if Docker, Node.js, and npm are installed
• ✅ Installs project dependencies (npm install)
• ✅ Installs Supabase CLI globally (if needed)
• ✅ Starts Supabase with Docker
• ✅ Updates your .env.development.local with Supabase credentials

Expected output:

╔════════════════════════════════════════╗
║  SymposAI Local Development Setup    づ
╚════════════════════════════════════════╝

🔍 Checking prerequisites...
✓ Docker is running
✓ Node.js is installed (v18.x.x)
✓ npm is installed (9.x.x)
✓ Supabase CLI is installed

📦 Installing npm dependencies...
...

🐳 Starting Supabase with Docker...
...

📋 Supabase Status:
API URL: http://localhost:54321
Studio URL: http://localhost:54323
...

✓ .env.development.local found
✓ Updated SUPABASE_URL
✓ Updated SUPABASE_ANON_KEY
✓ Updated SUPABASE_SERVICE_ROLE_KEY
✓ Updated JWT_SECRET

✅ Setup complete!

Step 4: Verify Supabase is Running

supabase status

Expected output:

         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
      anon key: eyJhbGc... (long string)
service_role key: eyJhbGc... (long string)

Step 5: Verify Environment File

Check that your .env.development.local has been updated:

# On Mac/Linux:
cat .env.development.local | grep SUPABASE

# Or open in your editor:
code .env.development.local

You should see:

• SUPABASE_URL=http://localhost:54321
• SUPABASE_ANON_KEY=eyJhbG... (long key)
• SUPABASE_SERVICE_ROLE_KEY=eyJhbG... (long key)
• JWT_SECRET=... (secret key)

Step 6: Add Your API Keys

Edit .env.development.local and add your LLM API keys:

# Open in your favorite editor:
code .env.development.local
# or
nano .env.development.local
# or
vim .env.development.local

Required keys (minimum for testing):

OPENAI_API_KEY=sk-your-actual-openai-key-here
GROK_API_KEY=your-actual-grok-key-here

Optional keys (only if testing those models):

ANTHROPIC_API_KEY=sk-ant-your-key
DEEPSEEK_API_KEY=your-deepseek-key
GOOGLE_API_KEY=your-google-key

Save the file after adding your keys.

Step 7: Start the Backend Server

npm run start:dev

Expected output:

> [email protected] start:dev
> cross-env NODE_ENV=development.local nest start --watch

[Nest] 12345  - 01/01/2024, 12:00:00 PM     LOG [NestFactory] Starting Nest application...
[Nest] 12345  - 01/01/2024, 12:00:00 PM     LOG [InstanceLoader] AppModule dependencies initialized
...
Application is running on: http://0.0.0.0:3000

The server is now running! 🎉

Step 8: Test the API

Open a new terminal window (keep the server running) and test:

# Test health endpoint
curl http://localhost:3000/api/v1/health

# Or use the test script
./scripts/test-api.sh

Step 9: Access Supabase Studio (Optional)

Open your browser and go to:

http://localhost:54323

This gives you a visual interface to:

• View database tables
• Run SQL queries
• Manage data
• Test authentication

Testing with Postman

Step 1: Configure Postman

1. Open Postman
2. Go to Settings (gear icon in top right)
3. Click General tab
4. Enable:
   • ✅ "Send cookies"
   • ✅ "Follow redirects"
5. Click Save

Step 2: Create a Collection

1. Click New → Collection
2. Name it "SymposAI Local"

Step 3: Add Endpoints

Register/Login:

POST http://localhost:3000/api/v1/auth/register
POST http://localhost:3000/api/v1/auth/login

User:

GET http://localhost:3000/api/v1/user/me

Debate:

POST http://localhost:3000/api/v1/debate/start
GET http://localhost:3000/api/v1/debate/:id

Step 4: Test Authentication

1. Login:

   • Select POST /auth/login
   • Body (raw JSON):

     {
       "email": "[email protected]",
       "password": "TestPass123!"
     }

   • Click Send
   • Cookies are automatically saved! ✅

2. Get User:

   • Select GET /user/me
   • Click Send
   • Cookies are automatically included! ✅

Troubleshooting

Issue: "Docker is not running"

Solution:

1. Open Docker Desktop application
2. Wait for it to start (whale icon should be stable)
3. Try again: docker info

Issue: "Port already in use"

Solution:

# Check what's using the port
lsof -i :3000
lsof -i :54321

# Kill the process (replace PID with actual process ID)
kill -9 PID

# Or restart Supabase
supabase stop
supabase start

Issue: "Cannot connect to Supabase"

Solution:

# Check Supabase status
supabase status

# If not running, restart
supabase stop
supabase start

# Verify .env.development.local has correct URL
cat .env.development.local | grep SUPABASE_URL

Issue: "Environment validation failed"

Solution:

• Check that all required fields in .env.development.local are filled
• Make sure there are no extra spaces or quotes around values
• Verify file is named exactly: .env.development.local

Issue: "Cookies not working in Postman"

Solution:

1. Postman Settings → General → Ensure "Send cookies" is enabled
2. Click Cookies link below address bar to view/manage cookies
3. Clear cookies: Manage Cookies → Select domain → Clear

Quick Reference Commands

# Start everything
./scripts/setup-local.sh

# Start Supabase only
supabase start

# Start backend only
npm run start:dev

# Stop Supabase
supabase stop

# Stop backend
Ctrl+C (in terminal running server)

# View Supabase status
supabase status

# View Supabase logs
supabase logs

# Reset database
supabase db reset

# Test API
./scripts/test-api.sh

Service URLs

Once everything is running:

• Backend API: http://localhost:3000
• API Base: http://localhost:3000/api/v1
• Supabase Studio: http://localhost:54323
• Email Testing: http://localhost:54324
• Database: localhost:54322

Next Steps

1. ✅ Setup complete
2. ✅ Backend running
3. ✅ Supabase running
4. 📝 Test endpoints in Postman
5. 🧪 Try creating a debate
6. 🎉 Start developing!

Need Help?

• Check DOCKER_SETUP.md for detailed Docker setup
• Check LOCAL_SETUP.md for comprehensive local setup guide
• Check QUICK_START.md for quick reference