institutional-trader/README/DEPLOYMENT.md

🚀 PRODUCTION DEPLOYMENT GUIDE

This guide covers deploying the Institutional Trader platform to production.

Table of Contents

1. Environment Configuration
2. Backend Deployment (Railway)
3. Frontend Deployment (Vercel)
4. Self-Hosting with Nginx
5. Monitoring & Health Checks
6. Security Checklist

---

1. Environment Configuration

Backend Production .env

Create a .env file in the backend directory with the following variables:

# Production Environment Variables
NODE_ENV=production
PORT=3000

# Supabase Configuration
SUPABASE_URL=your_production_supabase_url
SUPABASE_ANON_KEY=your_production_anon_key
SUPABASE_SERVICE_KEY=your_service_role_key

# Direct PostgreSQL Connection (optional, for heavy queries)
# Get this from: Supabase Dashboard > Settings > Database > Connection String (URI)
DATABASE_URL=postgresql://postgres:[password]@db.[project-ref].supabase.co:5432/postgres

# CORS Configuration
CORS_ORIGIN=https://your-frontend-domain.com

# Security
JWT_SECRET=your_super_secret_jwt_key_min_32_chars
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=100

# Error Tracking (optional)
SENTRY_DSN=your_sentry_dsn_here

Frontend Production .env

Create a .env.production file in the frontend directory:

VITE_API_URL=https://your-backend-domain.com
VITE_WS_URL=wss://your-backend-domain.com
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_anon_key

---

2. Backend Deployment (Railway)

Prerequisites

1. Install Railway CLI:

npm install -g railway

2. Login to Railway:

railway login

Deployment Steps

1. Initialize Railway project:

cd backend
railway init

2. Link to existing project (if applicable):

railway link

3. Set environment variables:

railway variables set NODE_ENV=production
railway variables set PORT=3000
railway variables set SUPABASE_URL=your_url
railway variables set SUPABASE_ANON_KEY=your_anon_key
railway variables set SUPABASE_SERVICE_KEY=your_service_key
railway variables set CORS_ORIGIN=https://your-frontend-domain.com
railway variables set RATE_LIMIT_WINDOW=15
railway variables set RATE_LIMIT_MAX=100
railway variables set JWT_SECRET=your_jwt_secret_min_32_chars

Or set them via Railway Dashboard:

• Go to your project → Variables tab
• Add each variable individually

4. Deploy:

railway up

5. View logs:

railway logs

Railway Configuration

The railway.toml file is already configured with:

• Build command: npm install && npm run build
• Start command: npm start
• Health check endpoint: /health
• Auto-restart on failure

---

3. Frontend Deployment (Vercel)

Prerequisites

1. Install Vercel CLI:

npm install -g vercel

2. Login to Vercel:

vercel login

Deployment Steps

1. Navigate to frontend directory:

cd frontend

2. Deploy to preview:

vercel

3. Deploy to production:

vercel --prod

4. Set environment variables in Vercel Dashboard:
   • Go to your project → Settings → Environment Variables
   • Add all VITE_* variables for Production environment

Vercel Configuration

The vercel.json file is already configured for:

• Static build from dist directory
• SPA routing (all routes → index.html)
• Environment variables support

---

4. Self-Hosting with Nginx

Prerequisites

• Ubuntu/Debian server with Nginx installed
• SSL certificate (Let's Encrypt recommended)
• Node.js installed on server

Setup Steps

1. Install dependencies on server:

# Backend
cd backend
npm install --production

# Frontend
cd frontend
npm install
npm run build

2. Set up systemd service for backend:

sudo nano /etc/systemd/system/flow-api.service

Add:

[Unit]
Description=Flow Platform API
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/institutional_trader/backend
Environment=NODE_ENV=production
ExecStart=/usr/bin/node src/server.js
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable flow-api
sudo systemctl start flow-api

3. Configure Nginx:

Copy nginx.conf.example to /etc/nginx/sites-available/your-domain and update:

• Replace yourdomain.com with your domain
• Update SSL certificate paths
• Update root path for frontend
• Update proxy_pass URLs if needed

Enable site:

sudo ln -s /etc/nginx/sites-available/your-domain /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4. Set up SSL with Let's Encrypt:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com -d api.yourdomain.com

---

5. Monitoring & Health Checks

Health Check Endpoint

The backend includes an enhanced health check at /health:

curl https://api.yourdomain.com/health

Response includes:

• Status (ok/degraded)
• Timestamp
• Uptime
• Database connection status
• Database latency

Uptime Monitoring

Set up monitoring with:

• UptimeRobot (free): Monitor /health endpoint
• Pingdom: Full-page monitoring
• Sentry: Error tracking (configure SENTRY_DSN)

Logs

Railway:

railway logs --tail

Vercel:

• View in Dashboard → Deployments → Logs

Self-hosted:

# Backend logs
sudo journalctl -u flow-api -f

# Nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

---

6. Security Checklist

• All environment variables set in production
• JWT_SECRET is at least 32 characters and random
• SUPABASE_SERVICE_KEY is kept secret (never in frontend)
• CORS origin set to production frontend URL only
• Rate limiting enabled (default: 100 requests per 15 minutes)
• SSL/TLS certificates installed and valid
• Security headers configured (Helmet)
• Health check endpoint configured
• Error tracking configured (Sentry)
• Database connection pooling enabled
• Caching layer configured for performance
• .env files excluded from git (verify .gitignore)
• Production build optimized (check bundle sizes)

---

Performance Optimizations

Already Implemented

1. Backend:

   • Compression middleware (gzip)
   • Connection pooling (PostgreSQL)
   • Request caching (NodeCache)
   • Rate limiting

2. Frontend:

   • Code splitting (vendor chunks)
   • Asset optimization
   • Production build minification

Additional Recommendations

1. CDN: Use Cloudflare or similar for static assets
2. Database: Enable connection pooling in Supabase
3. Caching: Consider Redis for distributed caching
4. Monitoring: Set up APM (Application Performance Monitoring)

---

Troubleshooting

Backend won't start

1. Check environment variables:

railway variables

2. Check logs:

railway logs

3. Verify database connection:

curl https://api.yourdomain.com/health

Frontend build fails

1. Check environment variables are set
2. Verify API URLs are correct
3. Check build logs:

vercel logs [deployment-url]

WebSocket connection fails

1. Verify VITE_WS_URL uses wss:// (not ws://)
2. Check Nginx WebSocket configuration
3. Verify backend WebSocket route is accessible

---

Support

For issues or questions:

1. Check logs first
2. Verify environment variables
3. Test health check endpoint
4. Review security checklist

Your platform is now production-ready! 🎉