Skip to main content

Source: ocean/docs/supabase-deployment-guide.md | ✏️ Edit on GitHub

Supabase Deployment Guide

Overview​

Our Supabase deployment is fully automated through GitHub Actions, with local testing via pre-commit hooks to ensure migrations work before they reach production.

Local Development Setup​

Prerequisites​

  • Docker Desktop must be running
  • Supabase CLI installed (brew install supabase/tap/supabase)

Initial Setup​

# Link to remote project (one-time setup)
supabase link --project-ref fldiayolmgphysdwgsuk

# Start local Supabase
supabase start

# Your local Supabase will be available at:
# Studio UI: http://localhost:54323
# API: http://localhost:54321

Working with Migrations​

  1. Create a new migration:

    supabase migration new your_migration_name

  2. Test migrations locally: Migrations are automatically tested when you commit if:

    • Local Supabase is running (supabase start)
    • You're committing changes to supabase/migrations/*.sql

    The pre-commit hook will run supabase db reset to ensure all migrations apply cleanly.

  3. Manual testing:

    # Reset database and rerun all migrations
    supabase db reset

    # Check migration status
    supabase migration list

Production Deployment​

Automatic Deployment​

When you push to main, the deploy-supabase.yml workflow automatically:

  1. Applies any new database migrations
  2. Deploys Edge Functions
  3. Updates Edge Function secrets
  4. Runs health checks

Required GitHub Secrets​

The following secrets must be set in GitHub repository settings:

  • SUPABASE_ACCESS_TOKEN - Your personal access token from Supabase dashboard
  • SUPABASE_DB_PASSWORD - Database password for the project
  • SUPABASE_PROJECT_ID - The project reference ID (e.g., fldiayolmgphysdwgsuk)
  • SUPABASE_ANON_KEY - Anonymous/public key for health checks

Edge Function Secrets​

These are automatically set during deployment:

  • STRIPE_SECRET_KEY
  • STRIPE_WEBHOOK_SECRET
  • STRIPE_FREE_PRICE_ID
  • NEON_API_KEY
  • POSTHOG_API_KEY
  • POSTHOG_PROJECT_API_KEY
  • SENTRY_DSN

Troubleshooting​

Migration Conflicts​

If you encounter migration history mismatches:

# Check migration status
supabase migration list

# Repair migration history if needed
supabase migration repair --status applied <migration_version>

Local Supabase Issues​

# Stop all containers
supabase stop

# Start fresh
supabase start

# Check container status
docker ps -a | grep supabase

Pre-commit Hook Failures​

If migrations fail during commit:

  1. Check the error output in terminal
  2. Review detailed logs at /tmp/supabase-migration-test.log
  3. Fix the migration SQL
  4. Run supabase db reset to test manually
  5. Try committing again

Best Practices​

  1. Always test migrations locally - The pre-commit hook enforces this
  2. Use descriptive migration names - e.g., add_user_preferences_table
  3. Keep migrations idempotent - They should be safe to run multiple times
  4. Review production logs - Check GitHub Actions logs if deployment fails
  5. Don't edit existing migrations - Create new ones to fix issues