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

# 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

# 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

# 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:

# 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

# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build

Container Won't Start

# 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

# 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/:

# 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

ssh GregRJacobs@10.0.0.81 -p 2323
cd /volume1/docker/pokedex.online
docker compose down

2. Restore from Backup (Local)

# 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

./deploy.sh --skip-tests --target internal

Quick Restart

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

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

Git-Based Rollback

Roll back to a previous commit:

# 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:

# 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:

# 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:

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