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)

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
npm run deploy:pokedex -- --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

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

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