TurboTrades/DEPLOYMENT_GUIDE.md

# TurboTrades Deployment Guide

Complete guide to deploy TurboTrades to your production server at `178.63.127.19`

---

## 📋 Table of Contents

1. [Prerequisites](#prerequisites)
2. [Server Setup](#server-setup)
3. [GitHub Secrets Configuration](#github-secrets-configuration)
4. [Initial Deployment](#initial-deployment)
5. [Automatic Deployments](#automatic-deployments)
6. [Manual Deployment](#manual-deployment)
7. [Monitoring & Maintenance](#monitoring--maintenance)
8. [Troubleshooting](#troubleshooting)
9. [Rollback Procedures](#rollback-procedures)

---

## 🔧 Prerequisites

### On Your Local Machine:
- [x] Git installed
- [x] GitHub account with repository access
- [x] SSH access to server (178.63.127.19)

### On Your Server (178.63.127.19):
- [ ] Ubuntu/Debian Linux
- [ ] Node.js 18+ installed
- [ ] MongoDB installed and running
- [ ] PM2 process manager
- [ ] Nginx (optional, for reverse proxy)
- [ ] Git installed

---

## 🖥️ Server Setup

### Step 1: SSH into Your Server

```bash
ssh root@178.63.127.19
# Or with specific user:
ssh yourusername@178.63.127.19
```

### Step 2: Install Required Software

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

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

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

# Start MongoDB
sudo systemctl start mongod
sudo systemctl enable mongod

# Install PM2 globally
sudo npm install -g pm2

# Install Git
sudo apt install -y git

# Install Nginx (optional)
sudo apt install -y nginx
```

### Step 3: Create Deployment Directory

```bash
# Create directory
sudo mkdir -p /var/www/turbotrades
sudo chown -R $USER:$USER /var/www/turbotrades

# Navigate to directory
cd /var/www/turbotrades
```

### Step 4: Generate SSH Deploy Key (Optional but Recommended)

```bash
# Generate SSH key for deployment
ssh-keygen -t ed25519 -C "deploy@turbotrades" -f ~/.ssh/turbotrades_deploy_key

# Display public key (add to GitHub Deploy Keys)
cat ~/.ssh/turbotrades_deploy_key.pub

# Display private key (add to GitHub Secrets)
cat ~/.ssh/turbotrades_deploy_key
```

### Step 5: Clone Repository

```bash
cd /var/www/turbotrades
git clone https://git.turbotrades.dev/iDefineHD/TurboTrades.git .

# Or with SSH key:
git clone git@git.turbotrades.dev:iDefineHD/TurboTrades.git .
```

### Step 6: Create Environment File

```bash
cd /var/www/turbotrades
nano .env
```

Add the following configuration:

```env
# Server Configuration
NODE_ENV=production
PORT=3000
HOST=0.0.0.0

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

# Session Secret (Generate a secure random string)
SESSION_SECRET=your-super-secret-session-key-change-this

# Steam API
STEAM_API_KEY=your-steam-api-key-here
STEAM_RETURN_URL=http://178.63.127.19:3000/auth/steam/return

# JWT Secret (Generate a secure random string)
JWT_SECRET=your-super-secret-jwt-key-change-this
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# CORS
CORS_ORIGIN=http://178.63.127.19

# Redis (if using)
REDIS_URL=redis://localhost:6379

# Admin Steam IDs (comma-separated)
ADMIN_STEAM_IDS=76561198000000000,76561198111111111

# Bot Configuration
STEAM_BOT_USERNAME=your-bot-username
STEAM_BOT_PASSWORD=your-bot-password
STEAM_BOT_SHARED_SECRET=your-bot-shared-secret
STEAM_BOT_IDENTITY_SECRET=your-bot-identity-secret

# CSGOFloat API (optional)
CSGOFLOAT_API_KEY=your-csgofloat-api-key

# Pricing API (optional)
PRICING_API_KEY=your-pricing-api-key
```

Save and exit (Ctrl+X, Y, Enter)

### Step 7: Install Dependencies

```bash
# Backend dependencies
npm ci --production

# Frontend dependencies and build
cd frontend
npm ci
npm run build
cd ..
```

### Step 8: Setup PM2

```bash
# Start application with PM2
pm2 start ecosystem.config.js --env production

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup
# Follow the instructions provided by the command above

# Check status
pm2 status
pm2 logs turbotrades
```

### Step 9: Configure Nginx (Optional but Recommended)

```bash
sudo nano /etc/nginx/sites-available/turbotrades
```

Add the following configuration:

```nginx
server {
    listen 80;
    server_name 178.63.127.19 yourdomain.com;

    # Frontend (Vite build)
    location / {
        root /var/www/turbotrades/frontend/dist;
        try_files $uri $uri/ /index.html;
        
        # Cache static assets
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }

    # Backend API
    location /api {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
    }

    # WebSocket support
    location /ws {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Auth routes
    location /auth {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        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;
    }
}
```

Enable the site:

```bash
sudo ln -s /etc/nginx/sites-available/turbotrades /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

### Step 10: Configure Firewall

```bash
# Allow SSH, HTTP, and HTTPS
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status
```

---

## 🔐 GitHub Secrets Configuration

### Step 1: Go to GitHub Repository Settings

1. Go to your repository: `https://git.turbotrades.dev/iDefineHD/TurboTrades`
2. Click **Settings** → **Secrets** (or CI/CD settings depending on Gitea version)
3. Click **New repository secret**

### Step 2: Add Required Secrets

Add each of these secrets:

#### `SERVER_HOST`
```
178.63.127.19
```

#### `SERVER_USER`
```
root
```
(or your SSH username)

#### `SERVER_PORT`
```
22
```

#### `SSH_PRIVATE_KEY`
```
-----BEGIN OPENSSH PRIVATE KEY-----
[Your private key content from ~/.ssh/turbotrades_deploy_key]
-----END OPENSSH PRIVATE KEY-----
```

#### `DEPLOY_PATH`
```
/var/www/turbotrades
```

### Step 3: Add Deploy Key to GitHub (If Using SSH)

1. Go to **Settings** → **Deploy keys**
2. Click **Add deploy key**
3. Title: `Production Server 178.63.127.19`
4. Key: Paste your public key from `~/.ssh/turbotrades_deploy_key.pub`
5. ✅ Check **Allow write access** (if needed)
6. Click **Add key**

---

## 🚀 Initial Deployment

### Method 1: Manual Initial Setup (Recommended)

Already completed in [Server Setup](#server-setup) above!

### Method 2: Using PM2 Deploy

```bash
# From your local machine
pm2 deploy ecosystem.config.js production setup
pm2 deploy ecosystem.config.js production
```

---

## 🔄 Automatic Deployments

### How It Works

The CI/CD workflow (`.github/workflows/deploy.yml`) automatically deploys when:
1. You push to the `main` branch
2. You manually trigger the workflow

### Deployment Process

1. **Trigger**: Push to `main` branch
   ```bash
   git add .
   git commit -m "feat: Add new feature"
   git push origin main
   ```

2. **CI/CD Pipeline**: Automatically runs
   - ✅ Checks out code
   - ✅ Builds frontend
   - ✅ Runs tests
   - ✅ Deploys to server via SSH
   - ✅ Restarts PM2
   - ✅ Runs health check
   - ✅ Rolls back if failed

3. **Monitor**: Check repository Actions tab for progress

### Manual Trigger

1. Go to **Actions** tab on GitHub
2. Select **Deploy to Production Server**
3. Click **Run workflow**
4. Select branch (usually `main`)
5. Click **Run workflow**

---

## 🛠️ Manual Deployment

### Quick Deploy (SSH to Server)

```bash
# SSH into server
ssh root@178.63.127.19

# Navigate to project
cd /var/www/turbotrades

# Pull latest changes
git pull origin main

# Install dependencies
npm ci --production
cd frontend && npm ci && npm run build && cd ..

# Restart application
pm2 restart turbotrades

# Check status
pm2 status
pm2 logs turbotrades --lines 50
```

### Using PM2 Deploy Command

```bash
# From your local machine
pm2 deploy ecosystem.config.js production update
```

---

## 📊 Monitoring & Maintenance

### Check Application Status

```bash
# SSH into server
ssh root@178.63.127.19

# Check PM2 status
pm2 status

# View logs
pm2 logs turbotrades

# View last 100 lines
pm2 logs turbotrades --lines 100

# View only errors
pm2 logs turbotrades --err

# Monitor in real-time
pm2 monit
```

### Check Server Resources

```bash
# CPU and Memory usage
htop

# Disk usage
df -h

# Check MongoDB status
sudo systemctl status mongod

# Check Nginx status
sudo systemctl status nginx
```

### Database Backup

```bash
# Create backup directory
mkdir -p /var/backups/turbotrades

# Backup MongoDB
mongodump --out /var/backups/turbotrades/backup-$(date +%Y%m%d-%H%M%S)

# Automated daily backup (add to crontab)
crontab -e
# Add this line:
0 2 * * * mongodump --out /var/backups/turbotrades/backup-$(date +\%Y\%m\%d)
```

### View Application Logs

```bash
# PM2 logs
pm2 logs turbotrades

# Application logs (if file-based)
tail -f /var/www/turbotrades/logs/app.log

# Nginx access logs
tail -f /var/log/nginx/access.log

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

### Restart Services

```bash
# Restart application
pm2 restart turbotrades

# Restart all PM2 apps
pm2 restart all

# Restart MongoDB
sudo systemctl restart mongod

# Restart Nginx
sudo systemctl restart nginx

# Reload Nginx (without downtime)
sudo systemctl reload nginx
```

---

## 🐛 Troubleshooting

### Issue: Application Won't Start

```bash
# Check PM2 logs
pm2 logs turbotrades --err

# Check if port is already in use
sudo lsof -i :3000

# Check environment variables
pm2 show turbotrades

# Restart with fresh environment
pm2 delete turbotrades
pm2 start ecosystem.config.js --env production
```

### Issue: Cannot Connect to Database

```bash
# Check MongoDB status
sudo systemctl status mongod

# Start MongoDB
sudo systemctl start mongod

# Check MongoDB logs
sudo tail -f /var/log/mongodb/mongod.log

# Test MongoDB connection
mongosh
```

### Issue: "Permission Denied" Errors

```bash
# Fix ownership
sudo chown -R $USER:$USER /var/www/turbotrades

# Fix permissions
chmod -R 755 /var/www/turbotrades
```

### Issue: CI/CD Deployment Fails

1. **Check CI/CD logs**
   - Go to repository Actions tab
   - Click on failed workflow
   - Review error messages

2. **Verify Secrets**
   - Settings → Secrets and variables → Actions
   - Ensure all secrets are set correctly

3. **Test SSH Connection Manually**
   ```bash
   ssh root@178.63.127.19
   ```

4. **Check Deployment Path**
   ```bash
   ssh root@178.63.127.19 "ls -la /var/www/turbotrades"
   ```

### Issue: 502 Bad Gateway (Nginx)

```bash
# Check if app is running
pm2 status

# Restart application
pm2 restart turbotrades

# Check Nginx configuration
sudo nginx -t

# View Nginx error logs
sudo tail -f /var/log/nginx/error.log
```

### Issue: Out of Memory

```bash
# Check memory usage
free -h

# Increase PM2 memory limit
pm2 stop turbotrades
# Edit ecosystem.config.js and increase max_memory_restart
pm2 start ecosystem.config.js

# Add swap space (if needed)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```

---

## ⏮️ Rollback Procedures

### Automatic Rollback

The CI/CD workflow automatically rolls back if deployment fails.

### Manual Rollback

#### Method 1: Using Backups

```bash
# SSH into server
ssh root@178.63.127.19

# List backups
ls -lt /var/www/ | grep turbotrades-backup

# Restore from backup
cd /var/www
rm -rf turbotrades/*
cp -r turbotrades-backup-YYYYMMDD-HHMMSS/* turbotrades/

# Restart application
cd turbotrades
pm2 restart turbotrades
```

#### Method 2: Using Git

```bash
# SSH into server
ssh root@178.63.127.19
cd /var/www/turbotrades

# View commit history
git log --oneline

# Rollback to specific commit
git reset --hard COMMIT_HASH

# Reinstall dependencies
npm ci --production
cd frontend && npm ci && npm run build && cd ..

# Restart
pm2 restart turbotrades
```

#### Method 3: Rollback to Previous Tag

```bash
# SSH into server
cd /var/www/turbotrades

# List tags
git tag -l

# Checkout specific tag
git checkout v1.0.0

# Rebuild and restart
npm ci --production
cd frontend && npm ci && npm run build && cd ..
pm2 restart turbotrades
```

---

## 📝 Deployment Checklist

### Before Deployment
- [ ] All tests pass locally
- [ ] Environment variables configured
- [ ] Database migrations ready (if any)
- [ ] Backup current production data
- [ ] Notify team about deployment

### During Deployment
- [ ] Monitor CI/CD workflow
- [ ] Watch server logs
- [ ] Check PM2 status
- [ ] Verify health endpoint

### After Deployment
- [ ] Test critical features
- [ ] Check error logs
- [ ] Verify database connectivity
- [ ] Test admin panel
- [ ] Test user authentication
- [ ] Monitor performance metrics

---

## 🔒 Security Best Practices

1. **Keep Secrets Safe**
   - Never commit `.env` file
   - Use GitHub Secrets for sensitive data
   - Rotate secrets regularly

2. **Keep Software Updated**
   ```bash
   sudo apt update && sudo apt upgrade
   npm update
   ```

3. **Enable Firewall**
   ```bash
   sudo ufw enable
   sudo ufw status
   ```

4. **Use HTTPS** (Recommended)
   ```bash
   sudo apt install certbot python3-certbot-nginx
   sudo certbot --nginx -d yourdomain.com
   ```

5. **Regular Backups**
   - Database backups daily
   - Code backups before deployment
   - Test restore procedures

---

## 📞 Support & Resources

### Useful Commands

```bash
# Full deployment script
cd /var/www/turbotrades && \
git pull origin main && \
npm ci --production && \
cd frontend && npm ci && npm run build && cd .. && \
pm2 restart turbotrades && \
pm2 logs turbotrades --lines 20

# Quick restart
pm2 restart turbotrades && pm2 logs turbotrades

# Check everything
pm2 status && \
sudo systemctl status mongod && \
sudo systemctl status nginx
```

### Logs Locations

- PM2 Logs: `~/.pm2/logs/`
- Application Logs: `/var/www/turbotrades/logs/`
- Nginx Access: `/var/log/nginx/access.log`
- Nginx Error: `/var/log/nginx/error.log`
- MongoDB: `/var/log/mongodb/mongod.log`

### Performance Monitoring

```bash
# Install monitoring tools
sudo npm install -g pm2-logrotate
pm2 install pm2-logrotate

# Monitor resources
pm2 monit
htop
```

---

## 🎯 Quick Reference

### Deploy from Local Machine
```bash
git add .
git commit -m "Your message"
git push origin main
# CI/CD pipeline handles the rest!
```

### Manual Deploy on Server
```bash
ssh root@178.63.127.19
cd /var/www/turbotrades
git pull && npm ci --production && cd frontend && npm ci && npm run build && cd .. && pm2 restart turbotrades
```

### Check Status
```bash
ssh root@178.63.127.19 "pm2 status && pm2 logs turbotrades --lines 20"
```

### Emergency Restart
```bash
ssh root@178.63.127.19 "pm2 restart turbotrades"
```

---

**🎉 Your deployment is now automated and production-ready!**

For issues or questions, check the troubleshooting section or review the logs.