Deployment Guide¶

This guide provides step-by-step instructions for deploying the platform's APIs and database to production.

Architecture Note: This platform uses a hybrid architecture with Domain APIs on Supabase Edge Functions and Experience APIs on Vercel. For a detailed overview of the architecture, communication patterns, and API classification, see the Hybrid Architecture Guide.

Table of Contents¶

Part 1: Supabase Deployment¶

Prerequisites
Overview
Pre-Deployment Checklist
Step 1: Install and Configure Supabase CLI
Step 2: Link to Supabase Project
Step 3: Deploy Database Migrations (Postgres Functions)
Step 4: Deploy Edge Functions
Step 5: Configure Environment Variables
Step 6: Verify Deployment
Troubleshooting
Rollback Procedures

Prerequisites¶

Before deploying, ensure you have:

Supabase Account: A Supabase account with a project created
Sign up at supabase.com
Create a new project (or use an existing one)

Supabase CLI: Installed and authenticated

# Check if CLI is installed
supabase --version

# If not installed:
# macOS
brew install supabase/tap/supabase

# Or using npm
npm install -g supabase

Project Reference ID: Your Supabase project reference ID
Found in your project URL: https://supabase.com/dashboard/project/<project-ref>
Or in Settings > General > Reference ID
Access Token: Authenticated with Supabase CLI
```
# Login to Supabase
supabase login
```
Local Project Setup: Ensure your local project is ready
All migrations are in supabase/migrations/
Edge functions are in supabase/functions/
supabase/config.toml is configured

Overview¶

This deployment process involves:

Database Migrations: Deploying Postgres schema, tables, functions, and triggers
Located in: supabase/migrations/*.sql
Includes Postgres functions like:
- get_current_snapshot_id()
- set_current_snapshot()
- archive_snapshot()
- sparks_search_trigger()
- update_updated_at_column()
Edge Functions: Deploying Deno-based serverless functions (multiple functions)
Located in: supabase/functions/
Functions: browse, search, graph, discovery, user, metadata, snapshots
Authentication: Most functions require JWT verification; discovery and metadata are public

Pre-Deployment Checklist¶

Supabase CLI installed and authenticated
Project reference ID obtained
Local migrations tested (supabase db reset)
Edge function tested locally (supabase functions serve)
Environment variables documented
Backup of production database (if updating existing project)

Step 1: Install and Configure Supabase CLI¶

Install Supabase CLI¶

# macOS (using Homebrew)
brew install supabase/tap/supabase

# Or using npm
npm install -g supabase

# Verify installation
supabase --version

Authenticate with Supabase¶

# Login to your Supabase account
supabase login

# This will open a browser for authentication
# After successful login, you'll be authenticated

Verify Authentication¶

# Check your linked projects
supabase projects list

Step 2: Link to Supabase Project¶

Link your local project to your remote Supabase project.

Get Your Project Reference ID¶

Go to your Supabase dashboard: https://supabase.com/dashboard
Select your project
Go to Settings > General
Copy the Reference ID (or extract it from the URL: https://supabase.com/dashboard/project/<project-ref>)

Link the Project¶

# From the project root directory
cd /Volumes/Musingly/Code/core

# Link to your Supabase project
supabase link --project-ref <your-project-ref>

# Example:
# supabase link --project-ref abcdefghijklmnop

Expected Output:

Finished supabase link.

Verify Link¶

# Check linked project
supabase status

# Or check the config
cat supabase/.temp/project-ref

Step 3: Deploy Database Migrations (Postgres Functions)¶

This step deploys all database schema changes, including Postgres functions, triggers, and tables.

Review Pending Migrations¶

# List all migrations
ls -la supabase/migrations/

# Check which migrations are already applied
supabase migration list

Expected Output:

Status    | Version | Name                                    | Description
----------|---------|-----------------------------------------|------------
Applied   | 20241229000001 | create_microlearning_schema      | ...
Applied   | 20241229000002 | seed_agentic_ai_curriculum        | ...
Pending   | 20241230000001 | add_snapshot_versioning           | ...

Deploy All Migrations¶

# Push all pending migrations to production
supabase db push

# This will:
# - Apply all new migrations in order
# - Create/update Postgres functions
# - Create/update tables, indexes, triggers
# - Apply RLS policies

Expected Output:

Applying migration 20241230000001_add_snapshot_versioning.sql...
Finished supabase db push.

Verify Migrations¶

# Check migration status
supabase migration list

# All migrations should show "Applied" status

Verify Postgres Functions¶

Connect to your database and verify functions are created:

# Get database connection string
supabase db remote get

# Connect using psql (replace with your connection string)
psql "postgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres"

# In psql, verify functions exist:
\df get_current_snapshot_id
\df set_current_snapshot
\df archive_snapshot
\df sparks_search_trigger
\df update_updated_at_column

# Exit psql
\q

Alternative: Deploy Specific Migration¶

If you need to deploy a specific migration:

# Deploy a specific migration file
supabase db push --include-all

Step 4: Deploy Edge Functions¶

Deploy the API as multiple Supabase Edge Functions. Each function handles a specific API domain.

Available Functions¶

browse - Content browsing (domains, trails, concepts, sparks, beacons)
search - Search and autocomplete
graph - Graph operations and learning paths
discovery - Discovery endpoints
user - User endpoints (me, journeys, events)
metadata - Metadata endpoints
snapshots - Snapshot management

Test Functions Locally (Optional but Recommended)¶

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

# Serve a specific function locally
supabase functions serve browse

# Or serve all functions (using helper script)
deno task serve-functions

# Test locally
curl http://127.0.0.1:54321/functions/v1/browse/health
curl http://127.0.0.1:54321/functions/v1/search/health

Deploy All Functions¶

# Deploy all functions at once
deno task deploy:all

# Or deploy individually
supabase functions deploy browse
supabase functions deploy search
supabase functions deploy graph
supabase functions deploy discovery
supabase functions deploy user
supabase functions deploy metadata
supabase functions deploy snapshots

Deploy Specific Functions¶

# Deploy a single function
deno task deploy:browse
# or
supabase functions deploy browse

# Deploy multiple functions
deno run scripts/deploy-functions.ts browse search graph

# Deploy only changed functions (git-based)
deno task deploy:changed

Deploy with Specific Project (if not linked)¶

# Deploy to a specific project without linking
supabase functions deploy browse --project-ref <your-project-ref>

Verify Function Deployment¶

# List all deployed functions
supabase functions list

# Check function health
deno task check:functions

# Expected output:
# ✅ browse      deployed         healthy
# ✅ search      deployed         healthy
# ✅ graph       deployed         healthy
# ...

Get Function URLs¶

# Get your project URL
supabase status

# Your functions will be available at:
# https://<project-ref>.supabase.co/functions/v1/browse
# https://<project-ref>.supabase.co/functions/v1/search
# https://<project-ref>.supabase.co/functions/v1/graph
# https://<project-ref>.supabase.co/functions/v1/discovery
# https://<project-ref>.supabase.co/functions/v1/user
# https://<project-ref>.supabase.co/functions/v1/metadata
# https://<project-ref>.supabase.co/functions/v1/snapshots

Step 5: Configure Environment Variables¶

Supabase automatically injects some environment variables, but you may need to set custom secrets.

Automatic Environment Variables¶

Supabase automatically provides these to edge functions: - SUPABASE_URL - SUPABASE_ANON_KEY - SUPABASE_SERVICE_ROLE_KEY

Set Custom Secrets¶

If your edge function needs custom environment variables:

# Set a secret
supabase secrets set MY_API_KEY=your-api-key-value

# Set multiple secrets
supabase secrets set \
  MY_API_KEY=value1 \
  ANOTHER_SECRET=value2

# List all secrets
supabase secrets list

# Unset a secret
supabase secrets unset MY_API_KEY

Verify Secrets¶

# List all configured secrets
supabase secrets list

# Note: Secret values are hidden for security

Step 6: Verify Deployment¶

Test Database Functions¶

# Connect to your database
psql "postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres"

# Test a function
SELECT get_current_snapshot_id();

# Check tables exist
\dt

# Check functions exist
\df

# Exit
\q

Test Edge Function¶

# Get your project reference ID
PROJECT_REF=$(cat supabase/.temp/project-ref 2>/dev/null || echo "your-project-ref")

# Test health endpoint
curl https://${PROJECT_REF}.supabase.co/functions/v1/browse/health

# Test API endpoint
curl https://${PROJECT_REF}.supabase.co/functions/v1/browse/api/v1/domains

# With authentication (if required)
curl https://${PROJECT_REF}.supabase.co/functions/v1/browse/api/v1/domains \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Check Function Logs¶

# View real-time logs
supabase functions logs browse

# View logs with tail
supabase functions logs browse --tail

# View logs for specific time range
supabase functions logs browse --since 1h

Verify in Supabase Dashboard¶

Go to your Supabase dashboard
Navigate to Edge Functions section
Verify browse function is listed and active
Check Database > Functions to see Postgres functions
Check Database > Tables to verify schema

Troubleshooting¶

Migration Errors¶

Problem: Migration fails with syntax error

# Solution: Test migration locally first
supabase db reset
supabase migration up

# Fix the migration file, then retry
supabase db push

Problem: Migration already applied

# Check migration status
supabase migration list

# If migration shows as applied but changes aren't present:
# Option 1: Create a new migration to fix
supabase migration new fix_migration_name

# Option 2: Reset and reapply (CAUTION: This will delete data)
supabase db reset

Edge Function Deployment Errors¶

Problem: Function deployment fails

# Check function syntax
cd supabase/functions/browse
deno check index.ts

# Test locally first
supabase functions serve browse

# Check logs for errors
supabase functions logs browse

Problem: Function not accessible

# Verify function is deployed
supabase functions list

# Check function URL format
# Should be: https://<project-ref>.supabase.co/functions/v1/browse

# Verify authentication if required
curl -v https://<project-ref>.supabase.co/functions/v1/browse/health

Authentication Issues¶

Problem: supabase login fails

# Clear cached credentials
rm -rf ~/.supabase

# Try login again
supabase login

Problem: Project link fails

# Unlink and relink
supabase unlink
supabase link --project-ref <your-project-ref>

Database Connection Issues¶

Problem: Cannot connect to database

# Verify project is linked
supabase status

# Get connection string
supabase db remote get

# Check firewall settings in Supabase dashboard
# Settings > Database > Connection Pooling

Rollback Procedures¶

Rollback Database Migration¶

CAUTION: Rolling back migrations can cause data loss. Always backup first.

# Option 1: Create a new migration to undo changes
supabase migration new rollback_previous_migration

# Edit the new migration file to reverse the changes
# Then deploy:
supabase db push

Option 2: Manual rollback via SQL

# Connect to database
psql "postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres"

# Manually execute rollback SQL
-- Example: Drop function if needed
DROP FUNCTION IF EXISTS function_name();

# Exit
\q

Rollback Edge Function¶

# Deploy previous version (if you have version control)
git checkout <previous-commit> -- supabase/functions/browse
supabase functions deploy browse

# Or redeploy current version to fix issues
supabase functions deploy browse --no-verify-jwt

Emergency Rollback¶

If you need to quickly disable a function:

Go to Supabase Dashboard
Navigate to Edge Functions
Pause or delete the function
Fix issues locally
Redeploy when ready

Deployment Checklist¶

Use this checklist for each deployment:

Pre-Deployment¶

All migrations tested locally (supabase db reset)
Edge function tested locally (supabase functions serve)
Code reviewed and committed
Backup of production database (if updating)

Deployment¶

Supabase CLI authenticated (supabase login)
Project linked (supabase link)
Migrations deployed (supabase db push)
Edge function deployed (supabase functions deploy)
Environment variables set (supabase secrets set)

Post-Deployment¶

Migrations verified (supabase migration list)
Postgres functions verified (via psql)
Edge function accessible (curl test)
Function logs checked (supabase functions logs)
Dashboard verification completed

Quick Reference¶

Common Commands¶

# Authentication
supabase login

# Project Management
supabase link --project-ref <ref>
supabase status
supabase projects list

# Database Migrations
supabase db push                    # Deploy all migrations
supabase migration list             # List migration status
supabase migration new <name>       # Create new migration

# Edge Functions
supabase functions deploy <name>    # Deploy function
supabase functions list             # List functions
supabase functions logs <name>      # View logs
supabase functions serve <name>     # Test locally

# Secrets Management
supabase secrets set KEY=value      # Set secret
supabase secrets list               # List secrets
supabase secrets unset KEY          # Remove secret

# Database Access
supabase db remote get              # Get connection string
psql "<connection-string>"          # Connect to database

Function URLs¶

Edge Function: https://<project-ref>.supabase.co/functions/v1/browse
Health Check: https://<project-ref>.supabase.co/functions/v1/browse/health
API Base: https://<project-ref>.supabase.co/functions/v1/browse/api/v1

Additional Resources¶

Support¶

If you encounter issues not covered in this guide:

Check Supabase CLI logs: supabase functions logs browse
Review Supabase Dashboard for errors
Check migration files for syntax errors
Verify environment variables are set correctly
Consult Supabase Documentation

Part 2: Vercel Experience APIs Deployment¶

The Experience APIs (BFF layer) are deployed to Vercel as a Next.js application. These APIs orchestrate calls to the Supabase Edge Functions and provide UI-specific transformations.

Vercel Prerequisites¶

Vercel Account: A Vercel account with access to deploy
Sign up at vercel.com

Vercel CLI: Installed globally

npm i -g vercel

# Verify installation
vercel --version

GitHub Integration (Recommended): For automatic deployments
Connect your GitHub repository in Vercel Dashboard
Supabase Credentials: Your Supabase project URL and anonymous key

Vercel Environment Setup¶

Set Environment Variables¶

Set these variables in Vercel Dashboard → Project → Settings → Environment Variables:

Variable	Required	Description
`SUPABASE_URL`	Yes	Your Supabase project URL (e.g., `https://xxx.supabase.co`)
`SUPABASE_ANON_KEY`	Yes	Supabase anonymous/public API key

Important: Set these for all environments (Production, Preview, Development).

Via Vercel CLI¶

# Navigate to the Vercel API app
cd apps/vercel-api

# Link to your Vercel project (first time only)
vercel link

# Add environment variables
vercel env add SUPABASE_URL
vercel env add SUPABASE_ANON_KEY

Via Vercel Dashboard¶

Go to Vercel Dashboard
Select your project
Navigate to Settings → Environment Variables
Add each variable for Production, Preview, and Development

Deploy to Vercel¶

Option 1: Automatic Deployment (Recommended)¶

If your GitHub repository is connected to Vercel:

# Push to main branch triggers production deployment
git push origin main

# Push to feature branch triggers preview deployment
git push origin feature/my-changes

Option 2: Manual Deployment via CLI¶

# Navigate to the Vercel API app
cd apps/vercel-api

# Deploy to preview (staging)
vercel

# Deploy to production
vercel --prod

Option 3: Deploy from Root¶

# From repository root, using pnpm filter
pnpm --filter @microlearn/vercel-api run build
pnpm --filter @microlearn/vercel-api exec vercel --prod

Verify Deployment¶

After deployment, test the endpoints:

# Replace with your Vercel deployment URL
VERCEL_URL="https://your-project.vercel.app"

# Test metadata endpoint (static, no DB)
curl $VERCEL_URL/api/metadata

# Test discovery domains endpoint
curl $VERCEL_URL/api/discovery/domains

# Test browse endpoint with filters
curl "$VERCEL_URL/api/discovery/browse?domain=ml"

Vercel Monitoring¶

View Logs¶

# Via CLI
vercel logs

# Follow logs in real-time
vercel logs --follow

Via Dashboard¶

Go to Vercel Dashboard → Your Project
Click on Deployments
Select a deployment
Click Functions to see serverless function logs

Performance Analytics¶

Go to Vercel Dashboard → Your Project
Click on Analytics
View Web Vitals, function performance, and error rates

Vercel Rollback¶

Via CLI¶

# List deployments
vercel ls

# Rollback to previous deployment
vercel rollback

# Or promote a specific deployment
vercel promote <deployment-url>

Via Dashboard¶

Go to Vercel Dashboard → Your Project
Click on Deployments
Find the deployment you want to restore
Click the three dots menu → Promote to Production

Deployment Workflow Summary¶

Full Deployment (Both Platforms)¶

# 1. Run tests and type checks
deno task check
pnpm run build

# 2. Deploy Supabase Edge Functions
deno task deploy:all

# 3. Deploy Vercel Experience APIs
cd apps/vercel-api && vercel --prod

# 4. Verify both deployments
deno task check:functions
curl https://your-project.vercel.app/api/metadata

Quick Reference¶

Task	Command
Type check Edge Functions	`deno task check`
Deploy all Edge Functions	`deno task deploy:all`
Deploy single Edge Function	`deno task deploy:<name>`
Health check Edge Functions	`deno task check:functions`
Build Vercel API	`cd apps/vercel-api && npm run build`
Deploy Vercel (preview)	`cd apps/vercel-api && vercel`
Deploy Vercel (production)	`cd apps/vercel-api && vercel --prod`
View Vercel logs	`vercel logs`
Rollback Vercel	`vercel rollback`

Last Updated: 2025-01-06 Maintained By: Development Team