Supabase Setup

Complete guide to setting up Supabase for BlockForge.

Overview

BlockForge uses Supabase for:

• Authentication - User management and authentication
• Database - PostgreSQL database for data storage
• Storage - File storage for images and documents
• Edge Functions - Serverless functions for API endpoints

Step 1: Create Supabase Project

1. Go to supabase.com
2. Sign up or log in
3. Click "New Project"
4. Fill in project details:
   • Name: BlockForge (or your preferred name)
   • Database Password: Choose a strong password
   • Region: Select closest region
5. Click "Create new project"
6. Wait for project to initialize (2-3 minutes)

Step 2: Get API Credentials

1. In Supabase Dashboard → Settings (⚙️) → API

2. Copy these values:

   • Project URL: https://xxxxx.supabase.co
   • anon public key: eyJhbGc... (long string starting with eyJ)
   • service_role key: Keep this secret (for server-side only)

3. Add to your .env.local:

VITE_SUPABASE_URL=https://xxxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGc...

Step 3: Run Database Schema

1. Go to SQL Editor in Supabase dashboard
2. Click New query
3. Copy contents of supabase/schema-migration.sql (or relevant schema files)
4. Paste into editor
5. Click Run (or Cmd/Ctrl + Enter)
6. Verify: Go to Table Editor → Should see tables like pages, workspaces, tasks, etc.

Verify Schema

Check that these tables exist:

• workspaces
• pages
• blocks
• tasks
• users
• collections

Step 4: Set Up Storage

Create Storage Buckets

1. Go to Storage in left sidebar

2. Click New bucket

3. Create buckets:

   • public-uploads - Public bucket for images and files
   • documents - For document uploads (optional)
   • avatars - For user avatars (optional)

4. For each bucket:

   • Set name
   • Toggle Public bucket ON for public-uploads
   • Click Create bucket

Set Storage Policies

1. Go to SQL Editor
2. Run storage policies script (check supabase/ directory for storage policies SQL)
3. This enables authenticated users to upload and access files

Example policy:

-- Allow authenticated users to upload
CREATE POLICY "Authenticated users can upload"
ON storage.objects FOR INSERT
TO authenticated
WITH CHECK (bucket_id = 'public-uploads');

-- Allow public read access
CREATE POLICY "Public read access"
ON storage.objects FOR SELECT
TO public
USING (bucket_id = 'public-uploads');

Step 5: Configure Authentication

Email/Password (Default)

Email authentication is enabled by default. Configure email templates in:

• Authentication → Email Templates

GitHub OAuth (Optional)

1. Go to Authentication → Providers
2. Enable GitHub
3. Get OAuth credentials from GitHub:
   • Go to GitHub Settings → Developer settings → OAuth Apps
   • Register new OAuth application
   • Set callback URL: https://xxxxx.supabase.co/auth/v1/callback
   • Copy Client ID and Client Secret
4. Add to Supabase:
   • Client ID: Paste from GitHub
   • Client Secret: Paste from GitHub
5. Save

Other Providers

BlockForge supports other OAuth providers:

• Google
• Apple
• Azure
• And more

Configure in Authentication → Providers

Step 6: Set Up Edge Functions (Optional)

If using Edge Functions for AI or other server-side logic:

1. Install Supabase CLI:

npm install -g supabase

2. Link to your project:

supabase link --project-ref your-project-ref

3. Deploy functions:

cd supabase/functions
supabase functions deploy function-name

Step 7: Configure Row Level Security (RLS)

RLS policies should be included in your schema migration. Verify they exist:

1. Go to Table Editor
2. Click on a table (e.g., pages)
3. Go to Policies tab
4. Verify policies are set up correctly

Example policies:

• Users can only see their own pages
• Users can create pages
• Users can update their own pages
• Users can delete their own pages

Step 8: Test Connection

1. Start your development server:

npm run dev

2. Open browser console
3. Check for Supabase connection errors
4. Try signing up/logging in

Troubleshooting

Connection Issues

• Verify VITE_SUPABASE_URL is correct
• Check VITE_SUPABASE_ANON_KEY is correct
• Ensure no typos in environment variables

Schema Errors

• Check SQL Editor for error messages
• Verify all required tables exist
• Check foreign key relationships

Storage Issues

• Verify buckets are created
• Check storage policies are applied
• Test file upload in application

Authentication Issues

• Check email templates are configured
• Verify OAuth callbacks are correct
• Check RLS policies allow user operations

Production Checklist

• [ ] Database schema deployed
• [ ] Storage buckets created
• [ ] RLS policies configured
• [ ] Authentication providers set up
• [ ] Edge Functions deployed (if used)
• [ ] Environment variables configured
• [ ] Connection tested

Next Steps

• AI Configuration
• Deployment Guide
• Environment Variables Guide