memory-infrastructure-palace/code/websites/pokedex.online/DEPLOYMENT.md

# Pokedex.Online Deployment Guide

## Overview

Pokedex.Online uses a multi-container Docker setup with:
- **Frontend**: Nginx serving built Vue.js application
- **Backend**: Node.js Express server (OAuth proxy + Gamemaster API)

## Automated Deployment (Recommended)

Use `deploy.sh` for a complete, automated deployment with built-in safety checks.

### Basic Usage

```bash
# Deploy to internal network
./deploy.sh --target internal

# Deploy to external (requires Cloudflare tunnel)
./deploy.sh --target external --port 8080 --backend-port 3000

# Dry run (preview without deploying)
./deploy.sh --dry-run --target internal
```

### Options

- `--target <internal|external>` - Deployment target (default: internal)
- `--port <number>` - Frontend HTTP port (default: 8080)
- `--ssl-port <number>` - Frontend HTTPS port (optional)
- `--backend-port <number>` - Backend port (default: 3000)
- `--skip-tests` - Skip test execution
- `--skip-build` - Skip build step (use existing dist/)
- `--no-backup` - Skip backup creation
- `--dry-run` - Preview without deploying

### What deploy.sh Does

The deployment script automates the entire process:

1. **Prerequisites Check** - Verifies Node.js, npm, and dependencies
2. **Environment Validation** - Checks for server/.env configuration
3. **Test Suite** - Runs frontend and backend tests
4. **Build Process** - Builds and verifies the application
5. **Backup Creation** - Creates timestamped backup (keeps last 5)
6. **Deployment** - Transfers files and starts containers
7. **Verification** - Health checks both services
8. **Summary** - Reports deployment URLs and next steps

### Examples

```bash
# Standard internal deployment
./deploy.sh --target internal

# External deployment with custom ports
./deploy.sh --target external --port 8080 --ssl-port 8443

# Quick deploy (skip tests, use existing build)
./deploy.sh --skip-tests --skip-build

# Development iteration (no backup needed)
./deploy.sh --no-backup --target internal

# Check what would happen
./deploy.sh --dry-run
```

## Manual Deployment

### Quick Deploy

```bash
# Deploy to internal network (10.0.0.81)
npm run deploy:pokedex

# Deploy to external (home.gregrjacobs.com)
npm run deploy:pokedex -- --target external

# Custom ports
npm run deploy:pokedex -- --port 8081 --backend-port 3001

# With HTTPS
npm run deploy:pokedex -- --port 8080 --ssl-port 8443 --backend-port 3000
```

## Configuration

### Deployment Targets

| Target | Host | SSH Port | Default Frontend Port | Default Backend Port |
|--------|------|----------|----------------------|---------------------|
| internal | 10.0.0.81 | 2323 | 8080 | 3000 |
| external | home.gregrjacobs.com | 2323 | 8080 | 3000 |

### Command Line Arguments

- `--target <internal|external>` - Deployment target (default: internal)
- `--port <number>` - Frontend HTTP port (default: 8080)
- `--ssl-port <number>` - Frontend HTTPS port (optional)
- `--backend-port <number>` - Backend API port (default: 3000)

## Deployment Process

The deploy script (`code/utils/deploy-pokedex.js`) performs:

1. **Build** - Runs `npm run build` locally
2. **Connect** - SSH to Synology NAS
3. **Transfer Files**:
   - Built `dist/` directory
   - Backend server code (`server/`)
   - Docker configuration files
   - Nginx configuration
4. **Deploy Containers**:
   - Stops existing containers
   - Builds new images
   - Starts frontend + backend containers
5. **Health Checks**:
   - Verifies frontend responds on configured port
   - Verifies backend responds on configured port
6. **Rollback** - Automatically reverts on failure

## Docker Compose Files

### Production (`docker-compose.production.yml`)
- Multi-container setup
- Health checks enabled
- Volume mounts for persistence
- Container networking

### Development (`docker-compose.yml`)
- Simple single-container setup
- For local testing only

## Environment Variables

Backend requires `.env` file with:

```bash
# Copy from example
cp server/.env.example server/.env

# Edit with your values
CHALLONGE_CLIENT_ID=your_client_id
CHALLONGE_CLIENT_SECRET=your_client_secret
REDIRECT_URI=https://yourdomain.com/oauth/callback
SESSION_SECRET=your_random_secret
PORT=3000
NODE_ENV=production
```

## Health Checks

Both containers expose health endpoints:

- **Frontend**: `http://localhost:8080/health`
- **Backend**: `http://localhost:3000/health`

## Troubleshooting

### Build Fails
```bash
# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build
```

### Container Won't Start
```bash
# SSH to Synology and check logs
ssh GregRJacobs@10.0.0.81 -p 2323
cd /volume1/docker/pokedex-online/base
docker compose logs
```

### Port Already in Use
```bash
# Use different port
./deploy.sh --target internal --port 8081 --backend-port 3001
```

### Backend Can't Connect to Frontend
- Check nginx.conf proxy settings
- Verify backend container is on same Docker network
- Check backend service name in nginx config matches compose file

## Rollback

### Automated Backups

The deploy script creates timestamped backups before each deployment in `backups/`:

```bash
# List available backups
ls -lh backups/

# Example:
# backup_20240115_143022.tar.gz (5.2M)
# backup_20240115_151534.tar.gz (5.3M)
```

The script automatically keeps only the last 5 backups to save space.

### Rollback Procedure

**1. Stop Current Deployment**
```bash
ssh GregRJacobs@10.0.0.81 -p 2323
cd /volume1/docker/pokedex.online
docker compose down
```

**2. Restore from Backup (Local)**
```bash
# Extract backup to temporary directory
mkdir /tmp/restore
tar -xzf backups/backup_TIMESTAMP.tar.gz -C /tmp/restore

# Copy files back
rsync -av /tmp/restore/ ./
```

**3. Redeploy**
```bash
./deploy.sh --skip-tests --target internal
```

### Quick Restart

If you just need to restart existing containers without code changes:

```bash
# On the server
cd /volume1/docker/pokedex.online
docker compose restart
```

### Git-Based Rollback

Roll back to a previous commit:

```bash
# Find commit to rollback to
git log --oneline -n 10

# Checkout previous version
git checkout <commit-hash>

# Redeploy
./deploy.sh --target internal

# Return to main branch when done
git checkout main
```

### Emergency Rollback

If deployment completely fails and you need to restore quickly:

```bash
# Stop failed deployment
ssh GregRJacobs@10.0.0.81 -p 2323 "cd /volume1/docker/pokedex.online && docker compose down"

# Extract most recent backup directly on server
LATEST_BACKUP=$(ls -t backups/backup_*.tar.gz | head -1)
ssh GregRJacobs@10.0.0.81 -p 2323 "cd /volume1/docker/pokedex.online && tar -xzf /path/to/backup"

# Restart containers
ssh GregRJacobs@10.0.0.81 -p 2323 "cd /volume1/docker/pokedex.online && docker compose up -d"
```

## URLs After Deployment

### Internal Network
- Frontend: http://10.0.0.81:8080
- Backend API: http://10.0.0.81:3000
- Backend Health: http://10.0.0.81:3000/health

### External
- Frontend: http://home.gregrjacobs.com:8080
- Backend API: http://home.gregrjacobs.com:3000
- Backend Health: http://home.gregrjacobs.com:3000/health

## Pre-Deployment Checklist

Before running `./deploy.sh`, ensure:

- [ ] All tests passing (`npm run test:all`)
- [ ] Code committed to git
- [ ] Environment variables configured in `server/.env`
- [ ] Build completes successfully (`npm run build`)
- [ ] No uncommitted breaking changes
- [ ] Deployment target accessible (ping host)
- [ ] Previous deployment backed up (script does this automatically)

## Post-Deployment Checklist

After deployment, verify:

- [ ] Frontend loads: http://10.0.0.81:8080
- [ ] Backend health check: http://10.0.0.81:3000/health
- [ ] OAuth flow works (login with Challonge)
- [ ] Gamemaster API accessible
- [ ] Browser console shows no errors
- [ ] Check Docker logs: `ssh ... && docker compose logs --tail=50`
- [ ] Monitor backend logs in `server/logs/`

## Manual Deployment

If automated deploy fails, you can deploy manually:

```bash
# 1. Build locally
npm run build

# 2. SSH to Synology
ssh GregRJacobs@10.0.0.81 -p 2323

# 3. Navigate to deployment directory
cd /volume1/docker/pokedex-online/base

# 4. Upload files (use scp or FileStation)

# 5. Deploy
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml up -d --build

# 6. Check logs
docker compose logs -f
```

## Rollback

Automatic rollback occurs on deployment failure. Manual rollback:

```bash
ssh GregRJacobs@10.0.0.81 -p 2323
cd /volume1/docker/pokedex-online/base
docker compose down
docker tag <previous-image-id> pokedex-frontend:latest
docker tag <previous-image-id> pokedex-backend:latest
docker compose up -d
```

## Production Checklist

Before deploying to production:

- [ ] Update `.env` with production credentials
- [ ] Set `NODE_ENV=production`
- [ ] Configure SSL/TLS certificates (if using HTTPS)
- [ ] Update CORS origins in backend
- [ ] Set secure session secret
- [ ] Test locally with `docker compose -f docker-compose.production.yml up`
- [ ] Verify health checks pass
- [ ] Check backend can reach external APIs (Challonge, etc.)
- [ ] Verify frontend can call backend endpoints
- [ ] Test OAuth flow end-to-end