trustos/DEPLOYMENT.md

TrustOS Cloud Deployment Guide

Quick Start Options

1. Railway Deployment (Recommended - 5 minutes)

Prerequisites

• Railway account (railway.app)
• GitHub repository pushed

Steps

1. Connect GitHub Repository

   • Go to railway.app and sign in
   • Click "New Project" → "Deploy from GitHub repo"
   • Select your TrustOS repository

2. Create Services

   • PostgreSQL Database

     • Click "Add Service" → Select "PostgreSQL"
     • Railway auto-configures DATABASE_URL

   • Backend Service

     • Add from Dockerfile
     • Root directory: ./backend
     • Set variables:
       • PYTHONUNBUFFERED=1
       • SECRET_KEY=your-secure-key-here
       • OPENAI_API_KEY=sk-... (optional)
     • Port: 8000

   • Frontend Service

     • Add from Dockerfile
     • Root directory: ./frontend
     • Set variables:
       • NEXT_PUBLIC_API_URL=https://your-api.railway.app
     • Port: 3000

3. Configure Environment

   DATABASE_URL=postgresql://...  # Auto-set by Railway
   SECRET_KEY=your-64-char-key
   AI_PROVIDER=openai (or anthropic)
   OPENAI_API_KEY=sk-...
   ANTHROPIC_API_KEY=sk-ant-...
   

4. Deploy

   • Click "Deploy" - Railway builds and deploys automatically
   • Services available at *.railway.app

2. Render Deployment (Alternative)

Steps

1. Database Setup

   • Create new PostgreSQL database
   • Note connection string

2. Deploy Backend

   • New → Web Service
   • Connect GitHub repository
   • Build command: pip install -r requirements.txt && python -m app.db.init_db
   • Start command: uvicorn app.main:app --host 0.0.0.0 --port 8000
   • Environment variables (same as Railway)

3. Deploy Frontend

   • New → Web Service
   • Connect GitHub repository
   • Build command: npm install && npm run build
   • Start command: npm start
   • Set NEXT_PUBLIC_API_URL to backend URL

3. Docker Compose on VPS (DigitalOcean, Linode)

# SSH into your VPS
ssh root@your-vps-ip

# Install Docker & Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
apt install -y docker-compose

# Clone and deploy
git clone https://github.com/your-username/trustos.git
cd trustos

# Set production environment
export DB_PASSWORD=your-secure-password
export SECRET_KEY=your-64-char-secret-key
export API_URL=https://api.your-domain.com

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

# Set up Let's Encrypt (optional but recommended)
apt install -y certbot python3-certbot-nginx
certbot certonly --standalone -d api.your-domain.com -d app.your-domain.com

Environment Variables

Variable	Required	Example	Purpose
DATABASE_URL	Yes	postgresql+asyncpg://...	PostgreSQL connection
SECRET_KEY	Yes	64-char random string	JWT signing key
OPENAI_API_KEY	No	sk-...	OpenAI API access (optional)
ANTHROPIC_API_KEY	No	sk-ant-...	Anthropic API access (optional)
AI_PROVIDER	No	openai	Which AI service to use
NEXT_PUBLIC_API_URL	Yes (frontend)	https://api.example.com	Backend API URL

Post-Deployment Setup

1. Initialize Database

   # Automatic on first deploy, or manually:
   docker exec trustos_backend python seed.py
   

2. Create Admin User

   curl -X POST https://api.your-domain.com/api/v1/auth/register \
     -H "Content-Type: application/json" \
     -d '{
       "email":"admin@your-company.com",
       "password":"secure-password",
       "full_name":"Admin Name"
     }'
   

3. Configure SSL/TLS

   • Railway: Automatic with custom domain
   • Render: Automatic free SSL
   • VPS: Use Let's Encrypt via certbot

4. Set Up Monitoring

   • Enable health checks in Railway/Render
   • Configure uptime monitoring (UptimeRobot, etc.)
   • Set up error tracking (Sentry)

Scaling Considerations

Horizontal Scaling

• Backend: Stateless, can scale to multiple instances
• Frontend: Static files can use CDN (Cloudflare, etc.)
• Database: Use managed database service with backups

Performance Optimization

• Enable database query caching (Redis)
• Use CDN for frontend assets
• Implement API rate limiting
• Add request/response compression

Cost Optimization (Railway/Render)

• Use smallest instances initially
• Auto-scale based on CPU/memory
• Use spot instances for non-critical services
• Schedule resource scaling by time of day

Troubleshooting

Backend won't start

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

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

Frontend won't connect to API

# Verify NEXT_PUBLIC_API_URL is set correctly
# Check CORS headers on backend
# Verify backend is accessible from frontend origin

Database connection issues

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

# Check if database exists and migrations ran
psql $DATABASE_URL -c "\dt"

Monitoring & Logging

Railway

• Built-in dashboard with metrics
• Automatic error tracking
• Network activity monitoring

Render

• Built-in logs and metrics
• Environment variable management
• Auto-rollback on failed deploys

VPS with Docker

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

# Monitor resources
docker stats

# Database backups
docker exec trustos_postgres pg_dump -U trustos trustos > backup.sql

Backup & Recovery

Database Backups

# Automatic backups (Railway/Render)
# Manual backup
pg_dump $DATABASE_URL > trustos_$(date +%Y%m%d).sql

# Restore
psql $DATABASE_URL < trustos_backup.sql

Configuration Backup

• Keep environment variables in secure password manager
• Version control all code except .env files
• Document custom configurations

Next Steps

• Set up custom domain
• Configure SSL certificates
• Enable monitoring and alerting
• Set up automated backups
• Configure CI/CD pipeline
• Add usage analytics
• Set up support/feedback system