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)

```bash
# 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**
   ```bash
   # Automatic on first deploy, or manually:
   docker exec trustos_backend python seed.py
   ```

2. **Create Admin User**
   ```bash
   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
```bash
# 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
```bash
# Verify NEXT_PUBLIC_API_URL is set correctly
# Check CORS headers on backend
# Verify backend is accessible from frontend origin
```

### Database connection issues
```bash
# 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
```bash
# 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
```bash
# 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