trustos/PRODUCTION_DEPLOYMENT_GUIDE.md

TrustOS Production Deployment Guide

Quick Start (Railway - 10 minutes)

Step 1: Prepare GitHub Repository

cd /root/trustos
git remote add origin https://github.com/YOUR_USERNAME/trustos.git
git branch -M main
git push -u origin main

Step 2: Create Railway Account & Project

1. Go to railway.app
2. Sign up with GitHub
3. Create new project
4. Select "Deploy from GitHub repo"
5. Authorize and select trustos repository

Step 3: Add PostgreSQL Service

1. Click "+ Add Service" → "PostgreSQL"
2. Railway auto-creates DATABASE_URL
3. Wait for service to be healthy

Step 4: Add Backend Service

1. Click "+ Add Service" → "Deploy from Dockerfile"
2. Set root directory: ./backend
3. Configure environment variables:

   PYTHONUNBUFFERED=1
   SECRET_KEY=<generate 64-char random string>
   OPENAI_API_KEY=sk-... (optional)
   ANTHROPIC_API_KEY=sk-ant-... (optional)
   AI_PROVIDER=openai (optional)
   

4. Set PORT to 8000
5. Click Deploy

Step 5: Add Frontend Service

1. Click "+ Add Service" → "Deploy from Dockerfile"
2. Set root directory: ./frontend
3. Configure environment variables:

   NEXT_PUBLIC_API_URL=<get backend URL from Railway dashboard>
   

4. Set PORT to 3000
5. Click Deploy

Step 6: Configure Custom Domain

1. In Railway, select frontend service
2. Click "Settings" → "Domains"
3. Add custom domain (e.g., trustos.example.com)
4. Update DNS records with CNAME pointing to Railway
5. SSL auto-configures within 5 minutes

Step 7: Test Deployment

# Test API health
curl https://api.trustos.example.com/health

# Test login
curl -X POST https://api.trustos.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email":"executive@acmecorp.io",
    "password":"TrustOS2024!"
  }'

# Open frontend
open https://trustos.example.com

---

Advanced: Render Deployment (15 minutes)

Prerequisites

• External PostgreSQL database (Neon, AWS RDS, DigitalOcean)
• Render account with GitHub connected

Step 1: Create PostgreSQL Database

Use Neon.tech, AWS RDS, or DigitalOcean:

# Example: Create database, note the connection string
DATABASE_URL=postgresql://user:password@host:5432/trustos

Step 2: Deploy Backend

1. Go to render.com
2. "New Web Service" → Connect repository
3. Configure:
   • Name: trustos-backend
   • Runtime: Python 3
   • Root Directory: backend
   • Build Command: pip install -r requirements.txt
   • Start Command: uvicorn app.main:app --host 0.0.0.0 --port 8000
4. Set environment variables (see railway guide)
5. Deploy

Step 3: Deploy Frontend

1. "New Web Service" → Connect repository
2. Configure:
   • Name: trustos-frontend
   • Runtime: Node
   • Root Directory: frontend
   • Build Command: npm install && npm run build
   • Start Command: npm start
3. Set NEXT_PUBLIC_API_URL=<backend-service-url>
4. Deploy

Step 4: Configure Domains

1. In Render dashboard, add custom domains
2. Update DNS CNAME records
3. SSL auto-configures

---

VPS Deployment (30 minutes)

Prerequisites

• Ubuntu 22.04 VPS (DigitalOcean, Linode, AWS)
• SSH access to root
• Domain name with DNS access

Step 1: Initial Setup

ssh root@your.vps.ip

# Update system
apt update && apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Install Docker Compose
apt install -y docker-compose

# Install Certbot for SSL
apt install -y certbot python3-certbot-nginx

Step 2: Clone and Configure

cd /opt
git clone https://github.com/YOUR_USERNAME/trustos.git
cd trustos

# Create .env.production
cp .env.production.example .env.production
# Edit with production values
nano .env.production

Step 3: Set Environment Variables

export DB_PASSWORD="your-secure-db-password"
export SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
export API_URL="https://api.your-domain.com"

Step 4: Start Services

# Create persistent directory for backups
mkdir -p /opt/trustos/backups

# Start services
docker-compose -f docker-compose.prod.yml up -d

# Check status
docker-compose logs -f

Step 5: Configure SSL

# Get SSL certificate
certbot certonly --standalone -d trustos.example.com -d api.trustos.example.com

# Update docker-compose to use certificates (optional)
# Or use nginx reverse proxy with certbot

Step 6: Set Up Nginx Reverse Proxy (Optional)

apt install -y nginx

# Create /etc/nginx/sites-available/trustos
cat > /etc/nginx/sites-available/trustos << 'EOF'
server {
    listen 443 ssl http2;
    server_name api.trustos.example.com;
    ssl_certificate /etc/letsencrypt/live/trustos.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/trustos.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 443 ssl http2;
    server_name trustos.example.com;
    ssl_certificate /etc/letsencrypt/live/trustos.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/trustos.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
EOF

# Enable and restart
ln -s /etc/nginx/sites-available/trustos /etc/nginx/sites-enabled/
nginx -t && systemctl restart nginx

Step 7: Set Up Automated Backups

# Create backup script
cat > /opt/trustos/backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/opt/trustos/backups"
docker exec trustos_postgres pg_dump -U trustos trustos > "$BACKUP_DIR/trustos_$DATE.sql"
# Keep only last 30 days
find $BACKUP_DIR -name "trustos_*.sql" -mtime +30 -delete
EOF

chmod +x /opt/trustos/backup.sh

# Add to crontab for daily backups at 2 AM
crontab -e
# Add: 0 2 * * * /opt/trustos/backup.sh

Step 8: Monitor and Maintain

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

# Check resource usage
docker stats

# Backup database
/opt/trustos/backup.sh

# Update services
docker-compose pull
docker-compose up -d

---

Post-Deployment Verification

1. Health Checks

# Check backend health
curl https://api.your-domain.com/health

# Should respond with:
# {"status":"ok","service":"TrustOS","version":"0.1.0"}

2. API Tests

# Test login
curl -X POST https://api.your-domain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"executive@acmecorp.io","password":"TrustOS2024!"}'

# Extract token from response and test authenticated request
TOKEN="<token-from-login-response>"
curl -H "Authorization: Bearer $TOKEN" \
  https://api.your-domain.com/api/v1/auth/me

3. Frontend Tests

• Open https://your-domain.com
• Should redirect to login
• Test login with demo credentials
• Verify dashboard loads
• Check all pages are accessible

4. Database Verification

# Connect to production database
psql $DATABASE_URL

# Check tables exist
\dt

# Verify demo data
SELECT COUNT(*) FROM tenants;
SELECT COUNT(*) FROM users;
SELECT COUNT(*) FROM findings;

---

Troubleshooting

Backend won't start

# Check logs
railway logs
# or
docker-compose logs backend

# Common issues:
# - DATABASE_URL malformed
# - SECRET_KEY not set
# - Port 8000 already in use

Frontend can't reach API

# Verify NEXT_PUBLIC_API_URL
# Should be: https://api.your-domain.com (no trailing slash)

# Check CORS headers
curl -H "Origin: https://your-domain.com" \
  -H "Access-Control-Request-Method: GET" \
  https://api.your-domain.com/health -v

Database connection fails

# Test connection
psql $DATABASE_URL -c "SELECT version();"

# If fails, check:
# - DATABASE_URL syntax
# - Network access to database host
# - Database user permissions

---

Performance Optimization

Caching

# Add Redis caching for dashboard
REDIS_URL = "redis://localhost:6379"

CDN

• Railway/Render: Use built-in CDN
• VPS: Configure CloudFlare or AWS CloudFront

Database Optimization

-- Add indexes for common queries
CREATE INDEX idx_findings_tenant ON findings(tenant_id);
CREATE INDEX idx_findings_status ON findings(status);
CREATE INDEX idx_risk_scores_tenant ON risk_scores(tenant_id);

---

Monitoring & Alerts

Railroad/Render Dashboard

• Built-in metrics and logs
• Automatic error tracking
• Performance monitoring

Uptime Monitoring

1. Sign up for UptimeRobot
2. Monitor: https://api.your-domain.com/health
3. Set alert email
4. Get weekly reports

Error Tracking (Optional)

1. Sign up for Sentry
2. Set SENTRY_DSN in production
3. View errors and exceptions
4. Get automatic alerts

---

Next Steps

• Verify deployment is live
• Test all user flows (login, dashboard, findings, status update)
• Configure uptime monitoring
• Set up error tracking
• Create support/feedback channel
• Document any customizations
• Schedule security audit
• Plan for scaling if needed

---

For help, refer to:

• Railway Docs
• Render Docs
• Next.js Deployment
• FastAPI Deployment

Questions? Check DEPLOYMENT.md for more details.