TurboTrades/GITEA_DEPLOY.md

# 🚀 TurboTrades - Gitea Deployment Guide

Complete deployment guide for TurboTrades using Gitea self-hosted repository.

---

## 📋 Overview

**Repository:** https://git.turbotrades.dev/iDefineHD/TurboTrades.git  
**Server:** turbotrades.dev  
**Deployment Method:** Gitea Actions + SSH

### Domain Structure
- **Frontend:** https://turbotrades.dev (Nginx serves static files)
- **Backend API:** https://api.turbotrades.dev (Nginx → Node.js)
- **WebSocket:** https://ws.turbotrades.dev (Nginx → Node.js)

### Server Paths
- **Backend Code:** `/root/ttbackend`
- **Frontend Build:** `/var/www/html/turbotrades`
- **Nginx Config:** `/etc/nginx/sites-available/turbotrades.conf`
- **Logs:** `/root/ttbackend/logs/`

---

## 🎯 Quick Deployment

### For First-Time Setup

```bash
# 1. SSH into server
ssh root@turbotrades.dev

# 2. Clone repository
mkdir -p /root/ttbackend
cd /root/ttbackend
git clone https://git.turbotrades.dev/iDefineHD/TurboTrades.git .

# 3. Install dependencies
npm ci --production

# 4. Build frontend
cd frontend
npm ci
npm run build

# 5. Deploy frontend to nginx
mkdir -p /var/www/html/turbotrades
cp -r dist/* /var/www/html/turbotrades/
chown -R www-data:www-data /var/www/html/turbotrades

# 6. Configure environment
cd /root/ttbackend
cp .env.example .env
nano .env  # Edit with your settings

# 7. Start backend with PM2
pm2 start ecosystem.config.js --env production
pm2 save
pm2 startup  # Follow instructions
```

### For Updates (Automatic via Gitea Actions)

Just push to `main` branch:
```bash
git add .
git commit -m "Your update"
git push origin main
```

Gitea Actions will automatically deploy!

---

## 🔧 Detailed Setup

### 1. Server Prerequisites

#### Install Required Software

```bash
# Update system
apt update && apt upgrade -y

# Install Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

# Install PM2
npm install -g pm2

# Install Nginx
apt install -y nginx

# Install MongoDB (if not installed)
wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu $(lsb_release -cs)/mongodb-org/7.0 multiverse" | tee /etc/apt/sources.list.d/mongodb-org-7.0.list
apt update
apt install -y mongodb-org
systemctl enable mongod
systemctl start mongod

# Install Git
apt install -y git
```

#### Create Directories

```bash
# Backend directory
mkdir -p /root/ttbackend
mkdir -p /root/ttbackend/logs

# Frontend directory
mkdir -p /var/www/html/turbotrades

# Set permissions
chown -R www-data:www-data /var/www/html/turbotrades
chmod -R 755 /var/www/html/turbotrades
```

### 2. Configure Nginx

#### Copy Nginx Config

```bash
# Copy config file
cp /root/ttbackend/nginx-config/turbotrades.conf /etc/nginx/sites-available/

# Enable site
ln -s /etc/nginx/sites-available/turbotrades.conf /etc/nginx/sites-enabled/

# Test configuration
nginx -t

# Reload Nginx
systemctl reload nginx
```

#### Setup SSL with Let's Encrypt

```bash
# Install Certbot
apt install -y certbot python3-certbot-nginx

# Get SSL certificate (will configure nginx automatically)
certbot --nginx -d turbotrades.dev -d www.turbotrades.dev -d api.turbotrades.dev -d ws.turbotrades.dev

# Auto-renewal
certbot renew --dry-run
```

### 3. Configure Backend

#### Create .env File

```bash
cd /root/ttbackend
nano .env
```

**Required Environment Variables:**

```env
# Application
NODE_ENV=production
PORT=3000

# URLs
FRONTEND_URL=https://turbotrades.dev
BACKEND_URL=https://api.turbotrades.dev
WS_URL=https://ws.turbotrades.dev

# Database
MONGODB_URI=mongodb://localhost:27017/turbotrades

# JWT Secrets
JWT_SECRET=your-super-secret-jwt-key-change-this
REFRESH_TOKEN_SECRET=your-refresh-token-secret-change-this

# Steam OAuth
STEAM_API_KEY=your-steam-api-key
STEAM_REALM=https://turbotrades.dev
STEAM_RETURN_URL=https://api.turbotrades.dev/auth/steam/return

# Session
SESSION_SECRET=your-session-secret-change-this

# Email (Optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-email-password
SMTP_FROM=noreply@turbotrades.dev

# Admin
ADMIN_EMAIL=admin@turbotrades.dev

# Rate Limiting
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=100
```

### 4. Deploy Backend with PM2

```bash
cd /root/ttbackend

# Start with ecosystem config
pm2 start ecosystem.config.js --env production

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup
# Follow the command it outputs

# Monitor
pm2 list
pm2 logs turbotrades-backend
```

---

## 🤖 Gitea Actions Setup

### 1. Configure Repository Secrets

Go to: `https://git.turbotrades.dev/iDefineHD/TurboTrades/settings/secrets`

Add these secrets:

| Secret Name | Value | Description |
|-------------|-------|-------------|
| `SERVER_HOST` | `turbotrades.dev` | Your server hostname |
| `SERVER_USER` | `root` | SSH user |
| `SERVER_PORT` | `22` | SSH port (default 22) |
| `SSH_PRIVATE_KEY` | `-----BEGIN OPENSSH PRIVATE KEY-----...` | SSH private key for deployment |

### 2. Generate SSH Key for Deployment

```bash
# On your server
ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy

# Add public key to authorized_keys
cat ~/.ssh/gitea_deploy.pub >> ~/.ssh/authorized_keys

# Copy PRIVATE key for Gitea secret
cat ~/.ssh/gitea_deploy
# Copy entire output including BEGIN/END lines
```

### 3. Enable Gitea Actions

1. Go to repository settings
2. Enable "Actions" if not already enabled
3. Workflow file is at `.github/workflows/deploy.yml`

### 4. Test Deployment

```bash
# Make a change
echo "# Test" >> README.md
git add README.md
git commit -m "Test deployment"
git push origin main

# Watch in Gitea Actions tab
# Go to: https://git.turbotrades.dev/iDefineHD/TurboTrades/actions
```

---

## 📊 Monitoring & Management

### PM2 Commands

```bash
# View status
pm2 list

# View logs
pm2 logs turbotrades-backend

# Restart
pm2 restart turbotrades-backend

# Stop
pm2 stop turbotrades-backend

# Start
pm2 start turbotrades-backend

# Monitor resources
pm2 monit

# Clear logs
pm2 flush
```

### Nginx Commands

```bash
# Test configuration
nginx -t

# Reload (without downtime)
systemctl reload nginx

# Restart
systemctl restart nginx

# View access logs
tail -f /var/log/nginx/turbotrades-access.log
tail -f /var/log/nginx/api-turbotrades-access.log
tail -f /var/log/nginx/ws-turbotrades-access.log

# View error logs
tail -f /var/log/nginx/turbotrades-error.log
tail -f /var/log/nginx/api-turbotrades-error.log
tail -f /var/log/nginx/ws-turbotrades-error.log
```

### Health Checks

```bash
# Frontend
curl https://turbotrades.dev

# Backend API
curl https://api.turbotrades.dev/api/health

# WebSocket (needs wscat)
npm install -g wscat
wscat -c wss://ws.turbotrades.dev
```

---

## 🔄 Manual Deployment

If Gitea Actions fail or you prefer manual deployment:

```bash
# SSH to server
ssh root@turbotrades.dev

# Navigate to backend
cd /root/ttbackend

# Stop application
pm2 stop turbotrades-backend

# Backup current version
cp -r /root/ttbackend /root/ttbackend-backup-$(date +%Y%m%d-%H%M%S)

# Pull latest code
git fetch origin
git reset --hard origin/main
git clean -fd

# Install backend dependencies
npm ci --production

# Build frontend
cd frontend
npm ci
npm run build

# Deploy frontend
rm -rf /var/www/html/turbotrades/*
cp -r dist/* /var/www/html/turbotrades/
chown -R www-data:www-data /var/www/html/turbotrades
chmod -R 755 /var/www/html/turbotrades

# Back to root
cd /root/ttbackend

# Restart backend
pm2 restart turbotrades-backend
pm2 save

# Verify
pm2 list
pm2 logs turbotrades-backend --lines 50
```

---

## 🐛 Troubleshooting

### Backend Not Starting

```bash
# Check logs
pm2 logs turbotrades-backend

# Check if port 3000 is in use
netstat -tulpn | grep 3000

# Check MongoDB connection
mongo --eval "db.runCommand({ ping: 1 })"

# Check environment variables
cd /root/ttbackend
cat .env | grep -v "SECRET\|PASSWORD\|KEY"
```

### Frontend Not Loading

```bash
# Check Nginx config
nginx -t

# Check if files exist
ls -la /var/www/html/turbotrades/

# Check permissions
ls -ld /var/www/html/turbotrades/

# Check Nginx logs
tail -f /var/log/nginx/turbotrades-error.log
```

### SSL Certificate Issues

```bash
# Renew certificate
certbot renew

# Check certificate status
certbot certificates

# Test SSL
curl -I https://turbotrades.dev
```

### WebSocket Connection Failed

```bash
# Check if backend is listening
netstat -tulpn | grep 3000

# Check Nginx WebSocket proxy
grep -A 20 "ws.turbotrades.dev" /etc/nginx/sites-available/turbotrades.conf

# Test WebSocket upgrade
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" https://ws.turbotrades.dev
```

### Database Connection Issues

```bash
# Check MongoDB status
systemctl status mongod

# Restart MongoDB
systemctl restart mongod

# Check connection
mongo turbotrades --eval "db.stats()"
```

### Gitea Actions Failed

1. Check Actions tab: `https://git.turbotrades.dev/iDefineHD/TurboTrades/actions`
2. Click failed workflow to view logs
3. Common issues:
   - SSH key not configured
   - Secrets not set
   - Server unreachable
   - Permission issues

### 502 Bad Gateway

```bash
# Backend not running
pm2 status turbotrades-backend
pm2 start turbotrades-backend

# Port mismatch - check backend port
grep "PORT" /root/ttbackend/.env

# Nginx proxy config
grep "proxy_pass" /etc/nginx/sites-available/turbotrades.conf
```

---

## 🔒 Security Checklist

- [x] SSL certificates installed for all domains
- [ ] Firewall configured (UFW or iptables)
- [ ] SSH key authentication only (disable password auth)
- [ ] MongoDB secured (authentication enabled)
- [ ] Secrets properly set in .env (not hardcoded)
- [ ] Rate limiting enabled (Nginx + Backend)
- [ ] CORS properly configured
- [ ] Security headers in Nginx
- [ ] Regular backups configured
- [ ] Log rotation enabled
- [ ] Fail2ban installed (optional)
- [ ] Server updates automated

### Firewall Setup (UFW)

```bash
# Install UFW
apt install -y ufw

# Allow SSH
ufw allow 22/tcp

# Allow HTTP/HTTPS
ufw allow 80/tcp
ufw allow 443/tcp

# Enable firewall
ufw enable

# Check status
ufw status
```

---

## 📦 Backup Strategy

### Automated Backup Script

```bash
# Create backup script
nano /root/backup-turbotrades.sh
```

**backup-turbotrades.sh:**
```bash
#!/bin/bash

BACKUP_DIR="/root/backups"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup MongoDB
mongodump --db turbotrades --out $BACKUP_DIR/mongodb-$TIMESTAMP

# Backup backend code
tar -czf $BACKUP_DIR/backend-$TIMESTAMP.tar.gz /root/ttbackend

# Backup frontend
tar -czf $BACKUP_DIR/frontend-$TIMESTAMP.tar.gz /var/www/html/turbotrades

# Backup nginx config
tar -czf $BACKUP_DIR/nginx-$TIMESTAMP.tar.gz /etc/nginx/sites-available/turbotrades.conf

# Keep only last 7 days of backups
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete
find $BACKUP_DIR -name "mongodb-*" -mtime +7 -delete

echo "Backup completed: $TIMESTAMP"
```

```bash
# Make executable
chmod +x /root/backup-turbotrades.sh

# Test backup
/root/backup-turbotrades.sh

# Schedule daily backups (3 AM)
crontab -e
# Add this line:
0 3 * * * /root/backup-turbotrades.sh >> /var/log/turbotrades-backup.log 2>&1
```

---

## 📈 Performance Optimization

### Nginx Caching

Add to server block in nginx config:

```nginx
# Cache static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# API response caching (optional)
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;
```

### PM2 Cluster Mode

Update ecosystem.config.js:

```javascript
instances: 4,  // Use multiple CPU cores
exec_mode: "cluster",
```

### MongoDB Indexes

```bash
mongo turbotrades
```

```javascript
// Add indexes for better performance
db.users.createIndex({ email: 1 }, { unique: true })
db.users.createIndex({ steamId: 1 }, { unique: true })
db.items.createIndex({ listed: 1, price: 1 })
db.trades.createIndex({ userId: 1, createdAt: -1 })
```

---

## 📝 Deployment Checklist

### Pre-Deployment
- [ ] Code reviewed and tested locally
- [ ] All tests passing
- [ ] Environment variables updated if needed
- [ ] Database migrations prepared (if any)
- [ ] Backup created
- [ ] Team notified

### Deployment
- [ ] Push to main branch
- [ ] Monitor Gitea Actions workflow
- [ ] Check deployment logs
- [ ] Verify PM2 status

### Post-Deployment
- [ ] Frontend loads correctly
- [ ] API health check passes
- [ ] WebSocket connects
- [ ] Test critical user flows
- [ ] Monitor error logs
- [ ] Check PM2 resource usage
- [ ] Verify database connections

---

## 🆘 Emergency Rollback

```bash
# SSH to server
ssh root@turbotrades.dev

# Stop current backend
pm2 stop turbotrades-backend

# Restore from backup
cd /root
rm -rf ttbackend
cp -r ttbackend-backup ttbackend  # Use latest backup

# Restart
cd ttbackend
pm2 restart turbotrades-backend
pm2 save

# Verify
pm2 logs turbotrades-backend
curl https://api.turbotrades.dev/api/health
```

---

## 📚 Useful Links

- **Frontend:** https://turbotrades.dev
- **Backend API:** https://api.turbotrades.dev
- **WebSocket:** https://ws.turbotrades.dev
- **Gitea Repo:** https://git.turbotrades.dev/iDefineHD/TurboTrades
- **Gitea Actions:** https://git.turbotrades.dev/iDefineHD/TurboTrades/actions

---

## 🎉 Success!

Your TurboTrades deployment is now live and automatically updating via Gitea Actions!

**Questions?** Check the logs and troubleshooting section above.

**Happy Trading! 🚀**