Skip to content

Running and Testing Guide

This guide explains how to run and test the Micro-Learning Platform API in local development and production environments. The API is deployed as multiple Supabase Edge Functions, each handling specific functionality.

Table of Contents

  1. Quick Start
  2. Architecture Overview
  3. Local Development
  4. Testing with api.http
  5. Production Usage
  6. Running All Services
  7. Running the API
  8. Viewing Logs
  9. End-to-End Testing
  10. Service Status Checks
  11. Troubleshooting

Quick Start

Local Development

For a complete end-to-end setup with all services running:

# Terminal 1: Start Supabase (includes PostgreSQL, Auth, Storage, etc.)
supabase start

# Terminal 2: Start the API server
deno task dev

# Terminal 3: Setup testing (optional)
deno task setup:e2e  # Creates test user and updates api.http

Access Points: - API Server: http://localhost:8000 - API Docs (Swagger): http://localhost:8000/doc - Supabase Studio: http://127.0.0.1:54323 - Supabase API: http://127.0.0.1:54321

Production Testing

# Get production JWT token and update api.http
deno task setup:production

Architecture Overview

The API is deployed as multiple independent Supabase Edge Functions, each handling specific functionality:

Function Purpose Endpoints
browse Content browsing /api/v1/domains, /api/v1/trails, /api/v1/concepts, /api/v1/sparks, /api/v1/beacons
search Search & autocomplete /api/v1/search, /api/v1/autocomplete
discovery Discovery/experience APIs /api/v1/discovery/domains, /api/v1/discovery/trails, /api/v1/discovery/concepts
graph Knowledge graph operations /api/v1/graph/*, /api/v1/path
user User profile & progress /api/v1/me/*, /api/v1/me/journeys, /api/v1/me/events
metadata Metadata enumerations /api/v1/metadata
snapshots Content versioning /api/v1/snapshots

Function URLs

Local Development: - Browse: http://127.0.0.1:54321/functions/v1/browse - Search: http://127.0.0.1:54321/functions/v1/search - Discovery: http://127.0.0.1:54321/functions/v1/discovery - User: http://127.0.0.1:54321/functions/v1/user - Graph: http://127.0.0.1:54321/functions/v1/graph - Metadata: http://127.0.0.1:54321/functions/v1/metadata - Snapshots: http://127.0.0.1:54321/functions/v1/snapshots

Production: - Browse: https://<project-ref>.supabase.co/functions/v1/browse - Search: https://<project-ref>.supabase.co/functions/v1/search - Discovery: https://<project-ref>.supabase.co/functions/v1/discovery - User: https://<project-ref>.supabase.co/functions/v1/user - Graph: https://<project-ref>.supabase.co/functions/v1/graph - Metadata: https://<project-ref>.supabase.co/functions/v1/metadata - Snapshots: https://<project-ref>.supabase.co/functions/v1/snapshots

Local Development

Best for: Development, debugging, hot reload, detailed logs

deno task dev

Advantages: - ✅ Hot reload on file changes - ✅ Structured JSON logs in terminal - ✅ Easy debugging - ✅ Faster startup - ✅ Single unified API at http://localhost:8000

Access: http://localhost:8000

API Structure: - All endpoints available at: http://localhost:8000/api/v1/* - Swagger UI: http://localhost:8000/doc - Health check: http://localhost:8000/health

Option 2: Edge Functions (Production-like Testing)

Best for: Testing production deployment, edge function behavior, Supabase integration

# Start Supabase first (if not already running)
supabase start

# Serve individual functions
supabase functions serve browse
supabase functions serve search
# ... etc for each function

# Or serve all functions at once (if you have a script)
deno task serve:functions all

Advantages: - ✅ Tests actual Edge Function runtime - ✅ Matches production environment - ✅ Validates Supabase function integration - ✅ Tests multi-function architecture

Access: Each function has its own URL: - Browse: http://127.0.0.1:54321/functions/v1/browse - Search: http://127.0.0.1:54321/functions/v1/search - etc.

Note: When serving as edge functions, the path structure is: - ✅ Correct: http://127.0.0.1:54321/functions/v1/browse/api/v1/domains - ❌ Wrong: http://127.0.0.1:54321/functions/v1/browse/domains

Testing with api.http

The api.http file provides a convenient way to test all API endpoints using VS Code's REST Client extension.

Setup

  1. Install REST Client Extension:
  2. Open VS Code
  3. Go to Extensions (Cmd+Shift+X)
  4. Search for "REST Client" by Huachao Mao

  5. Install it

  6. Get Authentication Token:

For Local Development: 

deno task setup:e2e
This will: - Create a test user (test@example.com / test123456) - Get a JWT token - Update api.http with the token

For Production: 

deno task setup:production
# Or with arguments:
deno task setup:production <email> <password> <project-ref>
This will: - Authenticate with production Supabase - Get a production JWT token - Update api.http with production URLs and token

  1. Refresh Token (when expired): 
    # Local
deno task api:token

# Production
deno task setup:production

Using api.http

  1. Open api.http in VS Code

  2. Configure Base URL:

  3. For local development: Uncomment @baseUrl = http://localhost:8000

  4. For production: Use the function-specific URLs (@browseUrl, @searchUrl, etc.)

  5. Send Requests:

  6. Click "Send Request" above any request

  7. Or use Cmd+Option+R (Mac) / Ctrl+Alt+R (Windows/Linux)

  8. Test Authenticated Endpoints:

  9. Ensure @authToken is set (run deno task setup:e2e or deno task setup:production)
  10. Requests with Authorization: Bearer {{authToken}} will automatically use the token

Function-Specific Testing

When testing production or edge functions, use function-specific URLs:

### Browse Function - List domains
GET {{browseUrl}}/api/v1/domains

### Search Function - Search content
GET {{searchUrl}}/api/v1/search?q=machine learning

### Discovery Function - Discover domains
GET {{discoveryUrl}}/api/v1/discovery/domains

### User Function - Get profile (requires auth)
GET {{userUrl}}/api/v1/me
Authorization: Bearer {{authToken}}

Health Checks

Each function has its own health endpoint:

### Health checks for all functions
GET {{browseUrl}}/health
GET {{searchUrl}}/health
GET {{discoveryUrl}}/health
GET {{userUrl}}/health
GET {{graphUrl}}/health
GET {{metadataUrl}}/health
GET {{snapshotsUrl}}/health

Production Usage

Getting Production Credentials

  1. Get Project Reference:
  2. Go to https://supabase.com/dashboard
  3. Select your project
  4. Go to Settings > General

  5. Copy the "Reference ID"

  6. Get API Keys:

  7. Go to Settings > API
  8. Copy the "anon" key (for client-side)
  9. Copy the "service_role" key (for server-side, keep secret!)

Setting Up Production Testing

  1. Get Production Token: 
    deno task setup:production
    Follow the prompts to enter:
  2. Email (of a user in production)
  3. Password

  4. Project reference ID (or Supabase URL)

  5. Or use environment variables: 

    export SUPABASE_URL=https://xxx.supabase.co
export SUPABASE_ANON_KEY=your-anon-key
export SUPABASE_PROJECT_REF=xxx
deno task setup:production <email> <password>

  6. Verify api.http is updated:

  7. Check that @authToken has a production token
  8. Check that function URLs point to production
  9. Test a health endpoint: GET {{browseUrl}}/health

Production Endpoints

All production endpoints follow this pattern: 

https://<project-ref>.supabase.co/functions/v1/<function-name>/api/v1/<endpoint>

Examples: - Browse domains: https://xxx.supabase.co/functions/v1/browse/api/v1/domains - Search: https://xxx.supabase.co/functions/v1/search/api/v1/search?q=test - User profile: https://xxx.supabase.co/functions/v1/user/api/v1/me

Authentication in Production

  1. For Public Endpoints:
  2. No authentication required

  3. Examples: /api/v1/domains, /api/v1/search, /api/v1/metadata

  4. For Authenticated Endpoints:

  5. Requires Authorization: Bearer <token> header
  6. Token must be a valid Supabase JWT
  7. Get token via deno task setup:production or Supabase Auth API

  8. Examples: /api/v1/me, /api/v1/me/journeys, /api/v1/me/events

  9. Token Expiration:

  10. Tokens expire after 1 hour
  11. Refresh by running deno task setup:production again
  12. Or implement token refresh in your application

Deploying Functions

# Deploy all functions
deno task deploy:all

# Deploy specific function
deno task deploy:browse
deno task deploy:search
# etc.

# Check deployment status
supabase functions list

# View function logs
supabase functions logs browse
supabase functions logs search
# etc.

For detailed deployment instructions, see DEPLOYMENT_GUIDE.md.

Running All Services

Starting Supabase Services

The supabase start command starts all necessary services:

supabase start

This starts: - ✅ PostgreSQL database on port 54322 - ✅ Supabase API (REST + PostgREST) on port 54321 - ✅ Supabase Studio (web UI) on port 54323 - ✅ Auth Service (JWT-based authentication) - ✅ Storage Service (file storage) - ✅ Realtime Service (WebSocket subscriptions) - ✅ Inbucket (local email testing) on port 54324 - ✅ GoTrue (authentication service) - ✅ PostgREST (auto-generated REST API)

Expected Output: 

Started supabase local development setup.

         API URL: http://127.0.0.1:54321
          DB URL: postgresql://postgres:postgres@127.0.0.1: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...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Verifying Services are Running

# Check status of all services
supabase status

# Check Docker containers (Supabase runs in Docker)
docker ps

# Expected containers:
# - supabase_db_*
# - supabase_auth_*
# - supabase_studio_*
# - supabase_storage_*
# - supabase_realtime_*
# - supabase_rest_*
# - supabase_inbucket_*

Stopping Services

# Stop all Supabase services
supabase stop

# Stop and remove all data (fresh start)
supabase stop --no-backup

Running the API

You have two options for running the API, depending on your testing needs:

Best for: Development, debugging, hot reload, detailed logs

deno task dev

Advantages: - ✅ Hot reload on file changes - ✅ Structured JSON logs in terminal - ✅ Easy debugging - ✅ Faster startup

Access: http://localhost:8000

Logs: Appear directly in terminal as structured JSON

Best for: Testing production deployment, edge function behavior, Supabase integration

# Start Supabase first (if not already running)
supabase start

# Serve the function locally
supabase functions serve browse

Advantages: - ✅ Tests actual Edge Function runtime - ✅ Matches production environment - ✅ Validates Supabase function integration

Access: http://127.0.0.1:54321/functions/v1/browse

Note: The function runs at /functions/v1/browse/* instead of /api/v1/* when served as an edge function.

Viewing Logs

API Server Logs (Development Mode)

When running deno task dev, logs appear in the terminal:

# View logs in real-time
deno task dev

# Save logs to file
deno task dev 2>&1 | tee api.log

# Filter errors only
deno task dev 2>&1 | jq 'select(.level == "error")'

# Filter by endpoint
deno task dev 2>&1 | jq 'select(.path == "/api/v1/domains")'

# View slow requests (>1000ms)
deno task dev 2>&1 | jq 'select(.type == "response" and .durationMs > 1000)'

Log Format: Structured JSON with request IDs for tracing

{
  "timestamp": "2024-01-15T10:30:00.123Z",
  "level": "info",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "request",
  "method": "GET",
  "path": "/api/v1/domains"
}

Supabase Edge Function Logs

Note: When running functions locally with supabase functions serve, logs appear directly in the terminal where the command is running. There is no separate logs command for local functions.

# When serving functions locally, logs appear in the terminal
supabase functions serve browse

# For production/deployed functions, view logs in Supabase Dashboard:
# 1. Go to https://supabase.com/dashboard
# 2. Select your project
# 3. Navigate to Edge Functions > Logs

# For local edge runtime container logs:
docker logs supabase_edge_runtime_core

# Follow edge runtime logs in real-time
docker logs -f supabase_edge_runtime_core

Supabase Service Logs (Docker Containers)

Note: Container names include your project directory name (e.g., _core). Replace with your actual project name if different. Use docker ps --filter "name=supabase" to see exact names.

# View logs for specific Supabase service containers
docker logs supabase_db_core          # PostgreSQL database logs
docker logs supabase_auth_core        # Auth service logs
docker logs supabase_rest_core        # PostgREST API logs
docker logs supabase_storage_core     # Storage service logs
docker logs supabase_realtime_core    # Realtime service logs
docker logs supabase_studio_core      # Studio UI logs
docker logs supabase_edge_runtime_core # Edge functions runtime logs

# Follow logs in real-time (add -f flag)
docker logs -f supabase_db_core

# View last N lines of logs
docker logs --tail 100 supabase_db_core

# View logs with timestamps
docker logs -t supabase_db_core

# List all Supabase containers
docker ps --filter "name=supabase" --format "{{.Names}}"

Database Logs

# View PostgreSQL database logs (using Docker)
docker logs supabase_db_core

# Follow database logs in real-time
docker logs -f supabase_db_core

# View last 100 lines of database logs
docker logs --tail 100 supabase_db_core

# View database logs with timestamps
docker logs -t supabase_db_core

# Connect directly to database for query execution
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres"

Docker Container Logs

For detailed container-level logs:

Note: Container names include your project directory name. For example, if your project is in a directory named "core", containers will be named like supabase_db_core. Replace _core with your project directory name if different.

# List all Supabase containers (to see exact names)
docker ps --filter "name=supabase" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# View logs for specific container (replace _core with your project name if different)
docker logs supabase_db_core

# Follow logs in real-time (use -f flag)
docker logs -f supabase_db_core

# View last N lines of logs
docker logs --tail 100 supabase_db_core

# View logs with timestamps
docker logs -t supabase_db_core

# View logs for all containers at once (requires a loop)
for container in $(docker ps --filter "name=supabase" --format "{{.Names}}"); do
  echo "=== Logs for $container ==="
  docker logs --tail 20 $container
done

End-to-End Testing

Complete Setup for E2E Testing

  1. Start all Supabase services:
# Terminal 1: Start Supabase
supabase start

# Wait for "Started supabase local development setup" message
# Copy the API keys for .env file
  1. Configure environment:
# Create .env file with values from supabase start output
cp env.example .env

# Edit .env:
# SUPABASE_URL=http://127.0.0.1:54321
# SUPABASE_ANON_KEY=<anon key from step 1>
# SUPABASE_SERVICE_ROLE_KEY=<service_role key from step 1>
  1. Initialize database:
# Apply migrations and seed data
supabase db reset

# Verify tables were created
# Option 1: Via Supabase Studio
open http://127.0.0.1:54323

# Option 2: Via psql
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres" -c "\dt"
  1. Start API server:
# Terminal 2: Start API (choose one method)

# Method A: Development server (recommended for testing)
deno task dev

# Method B: Edge function (production-like)
supabase functions serve browse
  1. Verify all services are running:
# Terminal 3: Check service status
supabase status

# Should show all services as "Running"
  1. Run test requests:
# Test health endpoint
curl http://localhost:8000/health

# Test API endpoint
curl http://localhost:8000/api/v1/domains

# Test with Swagger UI
open http://localhost:8000/doc

Testing Checklist

  • Supabase services are running (supabase status)
  • PostgreSQL is accessible (psql connection works)
  • Database schema is applied (supabase db reset completed)
  • Environment variables are set (.env file exists)
  • API server is running (deno task dev or supabase functions serve)
  • Health endpoint responds (curl http://localhost:8000/health)
  • API endpoints respond (curl http://localhost:8000/api/v1/domains)
  • Logs are visible (check terminal output)

Service Status Checks

Quick Status Check Script

#!/bin/bash
# Check all services in one command

echo "=== Checking Supabase Services ==="
supabase status

echo ""
echo "=== Checking Docker Containers ==="
docker ps --filter "name=supabase" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

echo ""
echo "=== Testing Database Connection ==="
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres" -c "SELECT version();" 2>&1

echo ""
echo "=== Testing API Endpoint ==="
curl -s http://localhost:8000/health 2>&1 | head -1

echo ""
echo "=== Testing Supabase API ==="
curl -s http://127.0.0.1:54321/rest/v1/ 2>&1 | head -1

Individual Service Checks

# Check if PostgreSQL is running
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres" -c "SELECT 1;"

# Check if Supabase API is running
curl http://127.0.0.1:54321/rest/v1/

# Check if Supabase Studio is running
curl http://127.0.0.1:54323

# Check if API server is running
curl http://localhost:8000/health

# Check if Edge Function is running (if using functions serve)
curl http://127.0.0.1:54321/functions/v1/browse/health

Troubleshooting

Services Won't Start

Problem: supabase start fails or hangs

Solutions:

# Check Docker is running
docker ps

# If Docker isn't running, start it:
# macOS: open -a Docker
# Colima: colima start

# Stop and restart Supabase
supabase stop
supabase start

# Check for port conflicts
lsof -i :54321  # Supabase API
lsof -i :54322  # PostgreSQL
lsof -i :54323  # Studio
lsof -i :8000   # Your API

# Free up ports if needed
kill -9 <PID>

Database Connection Errors

Problem: API can't connect to PostgreSQL

Solutions:

# Verify Supabase is running
supabase status

# Check .env file has correct values
cat .env

# Test database connection directly
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres"

# Check database logs
supabase db logs

API Returns 500 Errors

Problem: API server is running but endpoints fail

Solutions:

# Check API server logs
# Look at terminal running `deno task dev`

# Check Supabase is running
supabase status

# Verify database schema is applied
supabase db reset

# Test database directly
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres" -c "\dt"

# Check for migration errors
supabase migration list

Logs Not Appearing

Problem: No logs visible in terminal

Solutions:

# For development server (deno task dev)
# Logs should appear automatically - check terminal output

# For edge functions (logs appear in terminal when running serve)
# Or view edge runtime container logs:
docker logs -f supabase_edge_runtime_core

# For Supabase services (database, auth, etc.)
docker logs -f supabase_db_core      # Database logs
docker logs -f supabase_auth_core    # Auth logs

# List all containers to find the one you need
docker ps --filter "name=supabase" --format "{{.Names}}"

Edge Function Not Working

Problem: supabase functions serve doesn't work

Solutions:

# Ensure Supabase is started first
supabase start

# Check function exists
ls supabase/functions/browse/

# Serve with verbose logging
supabase functions serve browse --debug

# Function logs appear in terminal when running serve
# Or view edge runtime container logs:
docker logs supabase_edge_runtime_core

Useful Commands Reference

Supabase Management

supabase start              # Start all services
supabase stop               # Stop all services
supabase status             # Check service status
# Note: Use docker logs for viewing service logs (see Docker Container Logs section)

Database Management

supabase db reset           # Reset database (drop all, reapply migrations)
# Note: Use docker logs supabase_db_core to view database logs
supabase migration list # List all migrations supabase migration up # Apply pending migrations 
### Function Management

```bash
# Serve individual functions locally
supabase functions serve browse
supabase functions serve search
supabase functions serve discovery
supabase functions serve user
supabase functions serve graph
supabase functions serve metadata
supabase functions serve snapshots

# Or serve all at once (if using script)
deno task serve:functions all

# Deploy functions
deno task deploy:all              # Deploy all functions
deno task deploy:browse            # Deploy specific function
deno task deploy:search            # etc.

# List deployed functions
supabase functions list

# View function logs (production)
supabase functions logs browse
supabase functions logs search
# etc.

# Check function health
deno task check:functions --local  # Local
deno task check:functions --project-ref <ref>  # Production

Note: Function logs appear in terminal when running serve. For production, view logs in Supabase Dashboard or use supabase functions logs <name>.

Development

deno task dev               # Start dev server with hot reload
deno task check             # Type-check code
deno task lint              # Run linter
deno task seed              # Seed curriculum data

Testing

Development Server: 

# Health check
curl http://localhost:8000/health

# API endpoint test
curl http://localhost:8000/api/v1/domains

# Swagger UI
open http://localhost:8000/doc

Edge Functions (Local): 

# Health checks
curl http://127.0.0.1:54321/functions/v1/browse/health
curl http://127.0.0.1:54321/functions/v1/search/health
# etc.

# API endpoints
curl http://127.0.0.1:54321/functions/v1/browse/api/v1/domains
curl http://127.0.0.1:54321/functions/v1/search/api/v1/search?q=test

Production: 

# Health checks
curl https://<project-ref>.supabase.co/functions/v1/browse/health
curl https://<project-ref>.supabase.co/functions/v1/search/health

# API endpoints
curl https://<project-ref>.supabase.co/functions/v1/browse/api/v1/domains
curl https://<project-ref>.supabase.co/functions/v1/search/api/v1/search?q=test

# With authentication
curl -H "Authorization: Bearer <token>" \
  https://<project-ref>.supabase.co/functions/v1/user/api/v1/me

Database: 

# Database test
psql "postgresql://postgres:postgres@127.0.0.1:54322/postgres" -c "SELECT COUNT(*) FROM domains;"

# Supabase API test
curl http://127.0.0.1:54321/rest/v1/

Quick Reference

Local Development Workflow

  1. Start Services: 

    supabase start

  2. Setup Testing: 

    deno task setup:e2e  # Creates test user, updates api.http

  3. Start API: 

    deno task dev  # Development server
# OR
supabase functions serve browse  # Edge function

  4. Test:

  5. Open api.http in VS Code
  6. Click "Send Request" on any endpoint
  7. Or use Swagger UI: http://localhost:8000/doc

Production Workflow

  1. Get Production Token: 

    deno task setup:production

  2. Test Production Endpoints:

  3. Open api.http in VS Code
  4. Use function-specific URLs (@browseUrl, @searchUrl, etc.)

  5. Click "Send Request" to test

  6. Deploy Functions: 

    deno task deploy:all

  7. Monitor:

  8. View logs: supabase functions logs <name>
  9. Check health: deno task check:functions --project-ref <ref>

Next Steps

  • API Testing: Use the Swagger UI at http://localhost:8000/doc or api.http file
  • Database Exploration: Use Supabase Studio at http://127.0.0.1:54323
  • API Usage: See Developer Guide for integration examples
  • Deployment: See Deployment Guide for production deployment
  • Logging Details: See Logging Guide for log format and filtering
  • Troubleshooting: See Troubleshooting Guide for common issues