FleetOS Production Deployment Guide

Version: 1.0 Last Updated: 2025-12-31 Status: Production Ready

---

Overview

This guide walks through deploying FleetOS to production. FleetOS is built with React + TypeScript + Vite, backed by Supabase (PostgreSQL + Auth + Realtime).

Tech Stack:

• Frontend: React 18, TypeScript, Vite

• Backend: Supabase (PostgreSQL, Auth, Realtime, Storage)

• Notifications: Twilio (WhatsApp)

• Analytics: Custom viral analytics via Supabase

Production Readiness:

• ✅ Row Level Security (RLS) policies ready

• ✅ Error boundaries implemented

• ✅ Loading states added

• ✅ Progressive authentication system

• ✅ Viral analytics tracking

• ✅ Production build optimized

---

Pre-Deployment Checklist

1. Security Audit

CRITICAL: Review credentials before deploying

• Service role key is NOT exposed to frontend (no VITE_ prefix)

• RLS policies applied to all tables

• Magic link tokens are cryptographically secure

• Twilio credentials are server-side only

• .env file is in .gitignore

• Production credentials are rotated (not using dev keys)

Files to review:

• .env.production.example (safe template)

• SECURITY_CREDENTIALS.md (security audit)

2. Database Setup

CRITICAL: Apply database migrations before deploying

All SQL migrations must be applied via Supabase SQL Editor:

1. RLS Policies: database/fleetos/rls-policies.sql

   • 30+ policies for data isolation

   • Apply via Supabase dashboard → SQL Editor

2. Core Migrations: database/APPLY_ALL_MIGRATIONS.sql

   • Combines 3 migrations: auth tiers, tracking tokens, viral tables

   • Run once in production database

3. Verification:

   -- Check RLS is enabled
   SELECT tablename, rowsecurity FROM pg_tables
   WHERE schemaname = 'public' AND tablename LIKE 'fleetos%';
   
   -- Should return TRUE for all FleetOS tables

See: database/MIGRATION_GUIDE.md for step-by-step instructions

---

Environment Variables

Production Environment Variables

Create a .env.production file with the following structure:

# Supabase Configuration (Frontend Safe)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here

# Supabase Service Role (Server-Side ONLY - NO VITE_ PREFIX)
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

# Twilio (Server-Side ONLY - NO VITE_ PREFIX)
TWILIO_ACCOUNT_SID=your-account-sid
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_WHATSAPP_NUMBER=[phone]

# Gemini API (Optional - for AI features)
GEMINI_API_KEY=your-gemini-key-here

Security Notes:

1. VITE_ Prefix = Frontend Exposed:

   • Only use VITE_ for PUBLIC keys (anon key, URL)

   • NEVER prefix service role or Twilio tokens with VITE_

2. Service Role Key:

   • Bypasses ALL RLS policies

   • Must be server-side only

   • Rotate immediately if exposed

3. Magic Link Security:

   • 24-hour expiry

   • Single-use tokens

   • Cryptographically random (32 bytes)

---

Build Process

1. Install Dependencies

npm install --production=false

2. Run Production Build

npm run build

Expected output:

✓ 162 modules transformed
✓ built in ~50s

Bundle sizes:
- vendor-react: 141 KB (45 KB gzipped)
- fleetos: 145 KB (33 KB gzipped)
- vendor-supabase: 179 KB (45 KB gzipped)
- index: 438 KB (94 KB gzipped)

3. Preview Production Build Locally

npm run preview

Visit: http://localhost:4173

Test checklist:

• FleetOS landing page loads

• Magic link login works

• Supplier dashboard loads with demo data

• Fleet dashboard loads

• Public request form submits successfully

• Tracking page shows real-time updates

• No console errors

---

Deployment Platforms

Option 1: Vercel (Recommended)

Why Vercel:

• Zero-config for Vite

• Automatic HTTPS

• Global CDN

• Serverless functions (if needed)

Steps:

1. Install Vercel CLI:

   npm install -g vercel

2. Deploy:

   vercel --prod

3. Set Environment Variables in Vercel Dashboard:

   • Settings → Environment Variables

   • Add all variables from .env.production

   • Ensure VITE_ prefix is correct

4. Verify Deployment:

   • Visit provided URL

   • Test magic link auth

   • Check Supabase connectivity

Vercel Configuration (vercel.json):

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Option 2: Netlify

Steps:

1. Install Netlify CLI:

   npm install -g netlify-cli

2. Deploy:

   netlify deploy --prod

3. Configuration (netlify.toml):

   [build]
     command = "npm run build"
     publish = "dist"
   
   [[redirects]]
     from = "/*"
     to = "/index.html"
     status = 200

Option 3: Custom Server (Node.js)

Use serve or similar static server:

npm install -g serve
serve -s dist -l 3000

For production, use PM2:

npm install -g pm2
pm2 start "serve -s dist -l 3000" --name fleetos
pm2 save

---

Post-Deployment Verification

1. Functional Tests

Run through complete user flows:

Supplier Flow:

1. Visit /fleetos/login

2. Request magic link

3. Click email link

4. Complete onboarding

5. Access supplier dashboard

6. Acknowledge a request

7. Mark request complete

8. Verify viral moments appear

Fleet Flow:

1. Visit supplier's public request page

2. Submit service request

3. Receive magic link

4. Track request status

5. Verify real-time updates

6. Check WhatsApp notifications

2. Database Verification

-- Check RLS is active
SELECT COUNT(*) FROM fleetos_invites;
-- Should fail if not authenticated

-- Check viral analytics are tracking
SELECT moment_type, COUNT(*)
FROM viral_events
GROUP BY moment_type;
-- Should show 6 moment types

-- Check users have auth tiers
SELECT auth_tier, COUNT(*)
FROM users
GROUP BY auth_tier;

3. Performance Verification

• Initial page load < 3 seconds

• Dashboard loads < 2 seconds

• Real-time updates appear instantly

• Mobile responsive (test on phone)

• No memory leaks (check DevTools)

4. Security Verification

• RLS prevents cross-user data access

• Service role key NOT in frontend bundle

• Magic links expire after 24 hours

• HTTPS enabled (no mixed content)

• CSP headers configured (if applicable)

---

Rollback Procedure

If deployment fails or critical bugs appear:

1. Immediate Rollback (Vercel/Netlify)

Vercel:

vercel rollback

Netlify:

• Dashboard → Deploys → Click previous deploy → "Publish deploy"

2. Database Rollback

If migrations cause issues:

-- Rollback RLS policies
DROP POLICY IF EXISTS "policy_name" ON table_name;

-- Rollback viral tables
DROP TABLE IF EXISTS viral_events, viral_conversions, viral_experiments;

-- Rollback auth tiers
ALTER TABLE users DROP COLUMN IF EXISTS auth_tier;

IMPORTANT: Only rollback if absolutely necessary. Test in staging first.

3. Emergency Hotfix

For critical frontend bugs:

1. Identify commit with bug

2. Revert locally:

   git revert <commit-hash>
   git push origin main

3. Trigger new deployment

4. Verify fix deployed

---

Monitoring & Maintenance

1. Analytics Monitoring

Key Metrics to Watch:

-- Viral R₀ (should be ≥ 1.2 for self-sustaining growth)
SELECT
  DATE(created_at) AS date,
  COUNT(DISTINCT user_id) AS active_users,
  COUNT(*) FILTER (WHERE action = 'clicked') AS viral_clicks
FROM viral_events
GROUP BY DATE(created_at)
ORDER BY date DESC
LIMIT 30;

Viral Dashboard:

• Access via: /fleetos/analytics (requires ROBO_HUB tier)

• Monitor R₀ replication rate

• Track conversion funnel

• A/B test results

2. Error Monitoring

Set up Sentry (optional but recommended):

npm install @sentry/react

Add to App.tsx:

import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: 'your-sentry-dsn',
  environment: 'production',
});

3. Database Health

Weekly checks:

-- Table sizes
SELECT
  schemaname, 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;

-- Index usage
SELECT * FROM pg_stat_user_indexes;

4. Performance Monitoring

• Supabase Dashboard: Monitor API request rates

• Browser DevTools: Check bundle size growth

• Lighthouse: Monthly performance audits

---

Troubleshooting

Build Fails

Error: terser not found

• Fix: Use esbuild for minification (already configured)

Error: TypeScript errors

• Fix: Run npm run build locally first

• Check tsconfig.json is correct

Deployment Fails

Error: Environment variables not set

• Fix: Add all variables in platform dashboard

• Verify VITE_ prefix for frontend vars

Error: 404 on all routes

• Fix: Configure redirects (see platform sections above)

• Ensure SPA fallback to index.html

Runtime Errors

Error: Supabase connection fails

• Fix: Check VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY

• Verify network access to Supabase

Error: Real-time not working

• Fix: Check Supabase Realtime is enabled

• Verify RLS policies allow subscriptions

Error: Magic links not sending

• Fix: Check email configuration in Supabase Auth

• Verify SMTP settings or use Supabase's email service

---

Production Optimization Checklist

• Code splitting configured

• Minification enabled (esbuild)

• Source maps disabled in production

• Bundle size < 500 KB (gzipped)

• CDN configured (automatic with Vercel/Netlify)

• Gzip/Brotli compression enabled (automatic)

• Cache headers configured (platform default)

• Database indexes optimized

• RLS policies tested under load

---

Next Steps After Deployment

1. Domain Setup:

   • Point custom domain to deployment

   • Configure DNS (A/CNAME records)

   • Enable HTTPS/SSL

2. Email Configuration:

   • Set up custom SMTP (SendGrid, Postmark)

   • Configure magic link sender domain

   • Test email deliverability

3. WhatsApp Verification:

   • Submit Twilio WhatsApp business profile

   • Get approval for production messaging

   • Set up message templates

4. Analytics Setup (optional):

   • Google Analytics 4

   • Mixpanel for funnel analysis

   • Segment for data pipelines

5. Backup Strategy:

   • Supabase auto-backups (enabled by default)

   • Weekly manual snapshots

   • Test restore procedure

---

Support & Resources

Documentation:

• Supabase Docs

• Vite Deployment Guide

• React Router SPA

Codebase Docs:

• SECURITY_CREDENTIALS.md - Security audit

• database/MIGRATION_GUIDE.md - Database setup

• database/fleetos/README_RLS.md - RLS policy details

• components/common/LOADING_USAGE.md - UX component guide

Issue Reporting:

• GitHub Issues: anthropics/claude-code

---

🚀 FleetOS is now production-ready.

Strategic Note: FleetOS is designed as "calm infrastructure" - professional, non-pushy, respectful of users' time. The viral engine is built to achieve R₀ ≥ 1.2 through trust and quality, not manipulation. This deployment guide reflects that philosophy: thorough, clear, and respectful of production environments.