thrilltrack-explorer/docs/DEPLOYMENT.md

Deployment Guide

Complete guide to deploying and configuring ThrillWiki.

---

Prerequisites

• Node.js 18+ and npm/pnpm
• Supabase project (or Lovable Cloud)
• CloudFlare Images account
• Novu Cloud account (optional, for notifications)

---

Environment Variables

Frontend (.env)

# Supabase
VITE_SUPABASE_URL=https://[project-ref].supabase.co
VITE_SUPABASE_ANON_KEY=[anon_key]

# CloudFlare Images
VITE_CLOUDFLARE_ACCOUNT_HASH=[account_hash]

# Novu (optional)
VITE_NOVU_APPLICATION_IDENTIFIER=[app_id]
VITE_NOVU_SOCKET_URL=wss://ws.novu.co
VITE_NOVU_API_URL=https://api.novu.co

Backend (Supabase Secrets)

Set these in Supabase Dashboard → Project Settings → Secrets:

# CloudFlare Images
CLOUDFLARE_ACCOUNT_ID=[account_id]
CLOUDFLARE_IMAGES_API_TOKEN=[api_token]

# Novu (optional)
NOVU_API_KEY=[api_key]

---

Setup Instructions

1. Clone Repository

git clone https://github.com/your-org/thrillwiki.git
cd thrillwiki

2. Install Dependencies

npm install
# or
pnpm install

3. Configure Environment

cp .env.example .env
# Edit .env with your values

4. Database Setup

The database migrations are already applied in Supabase. If setting up a new project:

# Install Supabase CLI
npm install -g supabase

# Link to your project
supabase link --project-ref [project-ref]

# Push migrations
supabase db push

5. Deploy Edge Functions

# Deploy all functions
supabase functions deploy

# Or deploy individually
supabase functions deploy upload-image
supabase functions deploy process-selective-approval  # Atomic transaction RPC
# ... etc

6. Set Supabase Secrets

# Via CLI
supabase secrets set CLOUDFLARE_ACCOUNT_ID=[value]
supabase secrets set CLOUDFLARE_IMAGES_API_TOKEN=[value]

# Or via Dashboard
# Project Settings → Secrets → Add Secret

7. Configure CloudFlare Images

1. Create CloudFlare account
2. Enable Images product
3. Create API token with Images Write permission
4. Get Account ID and Account Hash
5. Configure variants (avatar, banner, card, etc.)

8. Configure Novu (Optional)

1. Create Novu Cloud account
2. Create notification templates:
   • content-approved
   • content-rejected
   • moderation-alert
   • review-reply
3. Get API key and Application Identifier
4. Set environment variables

9. Build Frontend

npm run build

10. Deploy Frontend

Option A: Lovable (Recommended)

• Deploy via Lovable interface
• Automatic deployments on git push

Option B: Vercel

npm install -g vercel
vercel --prod

Option C: Netlify

npm install -g netlify-cli
netlify deploy --prod

---

Post-Deployment Checklist

Verify Services

• Frontend loads without errors
• Can sign in with password
• Can sign in with OAuth (Google, Discord)
• Database queries work
• Edge functions respond
• CloudFlare image upload works
• Notifications send (if enabled)

Create Admin User

-- In Supabase SQL Editor
-- 1. Sign up user via UI first
-- 2. Then grant superuser role
INSERT INTO user_roles (user_id, role, granted_by)
VALUES (
  '[user-id-from-auth-users]',
  'superuser',
  '[user-id-from-auth-users]' -- Self-grant for first superuser
);

Configure RLS

Verify Row-Level Security is enabled:

-- Check RLS status
SELECT tablename, rowsecurity 
FROM pg_tables 
WHERE schemaname = 'public';

-- All should return rowsecurity = true

Test Critical Flows

1. Create test park submission
2. Review in moderation queue
3. Approve submission
4. Verify park appears on site
5. Check version created
6. Test rollback

---

Domain Configuration

Custom Domain (Lovable)

1. Go to Project → Settings → Domains
2. Add custom domain
3. Update DNS records:
   • CNAME: www → [lovable-subdomain]
   • A: @ → [lovable-ip]
4. Wait for SSL provisioning

Custom Domain (Vercel/Netlify)

Follow platform-specific instructions for custom domains.

---

Monitoring & Logging

Supabase Monitoring

• Dashboard: Monitor database performance
• Logs: View edge function logs
• Analytics: Track API usage

Frontend Monitoring

Consider adding:

• Sentry: Error tracking
• PostHog: Product analytics
• LogRocket: Session replay

Database Monitoring

-- Active connections
SELECT count(*) FROM pg_stat_activity;

-- Slow queries
SELECT * FROM pg_stat_statements 
WHERE mean_exec_time > 100 
ORDER BY mean_exec_time DESC 
LIMIT 10;

-- Table sizes
SELECT 
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

---

Backup & Recovery

Database Backups

Supabase Pro automatically backs up:

• Daily backups kept for 7 days
• Point-in-time recovery

Manual backup:

supabase db dump > backup.sql

Image Backups

CloudFlare Images are automatically backed up by CloudFlare.

To export all image IDs:

COPY (
  SELECT cloudflare_image_id, cloudflare_image_url 
  FROM (
    SELECT banner_image_id AS cloudflare_image_id, banner_image_url AS cloudflare_image_url FROM parks
    UNION
    SELECT card_image_id, card_image_url FROM parks
    UNION
    SELECT banner_image_id, banner_image_url FROM rides
    UNION
    SELECT card_image_id, card_image_url FROM rides
    -- ... etc
  ) AS images
  WHERE cloudflare_image_id IS NOT NULL
) TO '/tmp/image_ids.csv' WITH CSV HEADER;

---

Scaling Considerations

Database Optimization

Indexes:

• Add indexes for frequently filtered columns
• Add composite indexes for multi-column queries
• Monitor slow query log

Caching:

• Use React Query caching aggressively
• Cache static data (entity lists) for 5+ minutes
• Cache dynamic data (moderation queue) for 10-30 seconds

Partitioning: Consider partitioning large tables when:

• entity_page_views > 10M rows
• notification_logs > 5M rows

Edge Function Optimization

• Keep functions small and focused
• Use connection pooling for database
• Cache frequently accessed data
• Consider Deno KV for session data

Frontend Optimization

Code Splitting:

const AdminDashboard = lazy(() => import('./pages/AdminDashboard'));

Image Optimization:

• Use CloudFlare variants (thumbnail, card, banner)
• Lazy load images with loading="lazy"
• Use AVIF/WebP formats

Bundle Size:

• Analyze bundle: npm run build -- --analyze
• Target: < 1MB initial bundle
• Lazy load admin pages

---

Security Checklist

• RLS enabled on all tables
• Supabase secrets set (not in .env)
• CloudFlare API token restricted to Images only
• MFA required for admin actions
• Rate limiting enabled on edge functions
• CORS configured correctly
• HTTPS enforced
• Content Security Policy configured
• XSS protection enabled

---

Troubleshooting

Common Issues

Build fails:

# Clear cache and rebuild
rm -rf node_modules .next dist
npm install
npm run build

Edge function 503:

• Check function logs in Supabase Dashboard
• Verify secrets are set
• Check function timeout (default 60s)

Image upload fails:

• Verify CloudFlare credentials
• Check CORS configuration
• Verify account not over quota

RLS blocking queries:

• Check if user authenticated
• Verify policy conditions
• Check AAL level (MFA)

---

Maintenance

Regular Tasks

Weekly:

• Review error logs
• Check slow query log
• Monitor disk usage
• Review stuck locks in moderation queue

Monthly:

• Update dependencies (npm update)
• Review security advisories
• Clean up old page views (90+ days)
• Archive old notification logs

Quarterly:

• Review database performance
• Optimize indexes
• Review and update RLS policies
• Audit user permissions

---

Rollback Procedure

If deployment fails:

1. Revert Frontend:

   git revert HEAD
   git push
   # Or use platform's rollback feature
   

2. Revert Database:

   supabase db reset # Local only!
   # Production: Restore from backup
   

3. Revert Edge Functions:

   supabase functions deploy [function-name] --version [previous-version]
   

---

Support

For deployment issues:

• Check documentation: docs/
• Review logs: Supabase Dashboard → Logs
• Create issue: GitHub Issues
• Contact: [support email]

---

Last Updated: 2025-01-20