docs/deployment.md

Deployment — Supabase CLI & Dashboard Instructions

Purpose

Read this file when deploying any change to Supabase or your environment. Always try CLI first. Use dashboard only if CLI is not possible — dashboard steps will be clearly marked.

---

Core Principle

CLI first. Dashboard only when CLI cannot do it. Every deployment step must be logged and reversible.

---

Prerequisites

# Install Supabase CLI
npm install -g supabase

# Login
supabase login

# Link to your project (run once per project)
supabase link --project-ref YOUR_PROJECT_REF

# Confirm link
supabase status

---

Environment Variables

# .env.local (never commit this file)
NEXT_PUBLIC_SUPABASE_URL=your_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Where to find these: Dashboard → Project Settings → API → Project URL + Keys

---

Database Migrations

Create a new migration

supabase migration new migration_name
# Creates: supabase/migrations/[timestamp]_migration_name.sql
# Write your SQL inside this file, then push

Push migration to remote

supabase db push

Check migration status

supabase migration list

Reset local DB (dev only)

supabase db reset

Pull remote schema to local

supabase db pull

---

Local Development

Start local Supabase

supabase start
# Gives you local URL, anon key, service role key

Stop local Supabase

supabase stop

View local DB in browser

supabase studio
# Opens Supabase Studio at localhost:54323

---

Edge Functions

Create a new edge function

supabase functions new function-name

Serve locally

supabase functions serve function-name --env-file .env.local

Deploy edge function

supabase functions deploy function-name

Set environment secret for edge function

supabase secrets set KEY=value

List secrets

supabase secrets list

---

Storage

CLI — not fully supported for bucket creation

→ Use Dashboard for bucket creation

Dashboard Steps — Create Storage Bucket

Go to Supabase Dashboard → Storage Click "New bucket" Enter bucket name Toggle public/private Click "Create bucket"

Upload file via CLI

supabase storage cp ./local-file.png ss:///bucket-name/path/file.png

---

Row Level Security (RLS)

CLI — enable RLS on a table

-- Inside a migration file
ALTER TABLE your_table ENABLE ROW LEVEL SECURITY;

CLI — create a policy via migration

CREATE POLICY "Users can view own data"
ON your_table
FOR SELECT
USING (auth.uid() = user_id);

Dashboard Steps — RLS Policy (if migration not possible)

Go to Supabase Dashboard → Authentication → Policies Select your table Click "New Policy" Choose template or write custom Click "Review" then "Save Policy"

---

Auth Configuration

CLI — not supported for OAuth provider setup

→ Use Dashboard for OAuth setup

Dashboard Steps — Enable OAuth Provider

Go to Dashboard → Authentication → Providers Select provider (Google, GitHub, etc.) Enter Client ID and Secret Copy callback URL → paste into provider's OAuth app Click "Save"

Set auth email templates

Dashboard → Authentication → Email Templates → Edit confirm signup / reset password templates

---

scripts/deploy.sh

#!/bin/bash
echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Starting deployment..." >> logs/errors.log

# Run tests first — abort if they fail
bash scripts/test.sh
if [ $? -ne 0 ]; then
  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Deployment aborted — tests failed" >> logs/errors.log
  exit 1
fi

# Push DB migrations
echo "Pushing DB migrations..."
supabase db push
if [ $? -ne 0 ]; then
  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Migration failed — check supabase logs" >> logs/errors.log
  exit 1
fi

echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Deployment complete" >> logs/errors.log

---

Rollback

Rollback last migration

# Supabase does not have auto-rollback
# Write a reverse migration manually

supabase migration new rollback_migration_name
# Write reverse SQL (DROP TABLE, ALTER, etc.)
supabase db push

Dashboard Steps — Rollback (if CLI fails)

Go to Dashboard → Database → Migrations Identify the migration to reverse Go to Dashboard → SQL Editor Write and run reverse SQL manually

---

Deployment Checklist

• All tests pass (bash scripts/test.sh)
• .env.local is not committed
• Migration file created for every schema change
• RLS enabled on every new table
• Edge functions tested locally before deploy
• supabase db push confirms no errors
• One-liner git commit message written

---

What NOT to Do

• Do not edit schema directly in Dashboard without a migration file
• Do not push migrations without running tests first
• Do not commit .env.local or any file with keys
• Do not disable RLS on any table in production
• Do not deploy edge functions without local testing first