Add production deployment configurations and guides
Deployment options: - Railway cloud deployment (recommended, 5-min setup) - Render alternative deployment - Docker Compose for VPS deployment - Comprehensive environment variable documentation Includes: - Production-grade Dockerfile with multi-stage builds - Docker Compose configuration for production - Detailed deployment guide with troubleshooting - Backup and recovery procedures - Monitoring and scaling recommendations Deployment paths ready: ✅ Railway (railway.app) ✅ Render (render.com) ✅ Self-hosted VPS (DigitalOcean, Linode, etc.) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
drjones
240
DEPLOYMENT.md
Normal file
240
DEPLOYMENT.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user