Skip to main content

Source: ocean/docs/SECURITY_SETUP.md | ✏️ Edit on GitHub

Security Setup Guide

🚨 Important Security Notice​

We've recently updated our security practices. All API keys and secrets have been removed from the repository. Follow this guide to set up your development environment securely.

🔐 Key Rotation Required​

If you had access to the previous .env file, those credentials have been compromised and need immediate rotation:

  1. Supabase: Go to your project settings and regenerate all API keys
  2. Stripe: Create new API keys in the Stripe dashboard
  3. Neon: Generate a new API key from your account settings
  4. Any other services: Rotate all exposed credentials

🏃 Quick Start​

1. Local Development Setup​

Run our setup script to configure your local environment:

./scripts/setup-local-env.sh

This will:

  • Create a .env.local file (gitignored)
  • Prompt you for all required secrets
  • Set up your local development environment

2. GitHub Secrets Setup (for maintainers)​

If you need to deploy to production/staging:

./scripts/setup-github-secrets.sh

This requires:

  • GitHub CLI (gh) installed
  • Admin access to the repository
  • All production/staging credentials

📋 Required Environment Variables​

Frontend (Public - Safe to expose)​

  • VITE_SUPABASE_URL - Your Supabase project URL
  • VITE_SUPABASE_ANON_KEY - Anonymous key (has RLS protection)
  • VITE_STRIPE_PUBLISHABLE_KEY - Stripe publishable key

Backend (Secret - Never expose)​

  • SUPABASE_SERVICE_ROLE_KEY - Service role key for backend operations
  • STRIPE_SECRET_KEY - Stripe secret key
  • STRIPE_WEBHOOK_SECRET - Stripe webhook signing secret
  • NEON_API_KEY - Neon API key for tenant provisioning

Optional Services​

  • VITE_POSTHOG_KEY - PostHog analytics
  • VITE_SENTRY_DSN - Sentry error tracking
  • SENTRY_AUTH_TOKEN - Sentry source map uploads

🔒 Security Best Practices​

DO​

  • ✅ Use .env.local for local development (gitignored)
  • ✅ Use GitHub Secrets for CI/CD
  • ✅ Use environment variables in production
  • ✅ Rotate keys periodically
  • ✅ Use test keys for development

DON'T​

  • ❌ Commit secrets to .env
  • ❌ Share service role keys
  • ❌ Use production keys locally
  • ❌ Store secrets in code
  • ❌ Log secret values

🚀 Deployment​

Vercel (Frontend)​

Set environment variables in Vercel dashboard:

  1. Go to Project Settings > Environment Variables
  2. Add all VITE_* variables
  3. Ensure proper environment scoping (Production/Preview/Development)

Supabase (Backend)​

Edge Functions automatically have access to:

  • SUPABASE_URL
  • SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY

Additional secrets should be set via:

supabase secrets set STRIPE_SECRET_KEY=sk_live_...
supabase secrets set NEON_API_KEY=napi_...

🔍 Verification​

Check your setup:

# Verify .env.local exists and .env has no secrets
grep -E "sk_|secret|password|napi_" .env  # Should return nothing

# Verify .env.local is gitignored
git status .env.local  # Should show as ignored

# Test your configuration
pnpm dev  # Should start without errors

📚 Migration from Old Setup​

If you're migrating from the old setup:

  1. Save your current values from .env (if valid)
  2. Run the setup script: ./scripts/setup-local-env.sh
  3. Delete any local copies of the old .env with secrets
  4. Update your deployment pipelines to use GitHub Secrets

🆘 Troubleshooting​

"Missing environment variable" errors​

  • Ensure .env.local exists and contains all required values
  • Check that variable names match exactly (including VITE_ prefix)

"Invalid API key" errors​

  • You may be using old/rotated keys
  • Generate new keys from your service providers

GitHub Actions failing​

  • Verify all secrets are set in GitHub repository settings
  • Check secret names match exactly with workflow files

📞 Support​

If you need help with credentials:

  • Development: Use test/development keys
  • Production: Contact repository administrators
  • Security Issues: Report immediately via security advisory

Remember: Security is everyone's responsibility! 🛡️