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

Deployment Configuration Progress

Date: January 30, 2026
Goal: Configure three distinct deployment strategies with environment-specific validation

Three Deployment Strategies

1. Development (dev)

   • Vite dev server at http://localhost:5173
   • Hot module reloading for rapid development
   • Backend OAuth proxy at http://localhost:3001
   • Discord redirect: http://localhost:5173/oauth/callback

2. Local Docker (local)

   • Full production build tested in Docker locally
   • Frontend at http://localhost:8099
   • Backend at http://localhost:3099
   • Discord redirect: http://localhost:8099/oauth/callback

3. Production (production)

   • Deployed to Synology NAS at 10.0.0.81:8099
   • Accessible via reverse proxy at https://app.pokedex.online
   • Discord redirect: https://app.pokedex.online/oauth/callback

Implementation Progress

Phase 1: Environment Files

• Create .env.development
• Create .env.local
• Create .env.production
• Delete root .env.example
• Delete server/.env

Phase 2: Deployment Scripts

• Refactor deploy.sh to use local/production targets
• Create scripts/verify-build.js
• Update build process to auto-verify

Phase 3: Backend Validation

• Add DEPLOYMENT_TARGET to env-validator.js
• Implement environment mismatch detection
• Update CORS to single origin per target

Phase 4: Docker Configuration

• Create docker-compose.local.yml
• Update docker-compose.production.yml
• Update nginx.conf server_name

Phase 5: Scripts Consolidation

• Update pokedex.online package.json
• Update server package.json
• Update root package.json
• Deprecate deploy-pokedex.js

Phase 6: Testing

• Test dev strategy
• Test local Docker strategy
• Test production deployment

Notes

Discord OAuth Redirect URIs Registered

• ✅ http://localhost:5173/oauth/callback (dev)
• ✅ http://localhost:8099/oauth/callback (local)
• ✅ https://app.pokedex.online/oauth/callback (production)

Key Design Decisions

1. Using Vite mode flags (--mode local, --mode production) to automatically load correct .env.{mode} files
2. Backend requires explicit DEPLOYMENT_TARGET and validates it matches FRONTEND_URL pattern
3. Build verification runs automatically after frontend build, fails on URL mismatch
4. Single CORS origin per deployment target (no arrays) for security
5. Simplified target naming: local and production (removed internal/external confusion)

Current Status

Status: ✅ Implementation complete, all three strategies tested successfully!
Last Updated: January 30, 2026

Test Results

✅ Dev Strategy (localhost:5173)

• ✅ Backend starts successfully on port 3001
• ✅ Environment validation working (DEPLOYMENT_TARGET=dev)
• ✅ CORS configured for http://localhost:5173
• ✅ Frontend Vite dev server running successfully
• ✅ Both services accessible and healthy

✅ Local Docker Strategy (localhost:8099)

• ✅ Build process with vite build --mode docker-local successful
• ✅ Build verification detects correct redirect URI (http://localhost:8099/oauth/callback)
• ✅ Docker containers build and deploy successfully
• ✅ Backend health check passes (DEPLOYMENT_TARGET=docker-local)
• ✅ Frontend accessible at http://localhost:8099
• ✅ Backend accessible at http://localhost:3099

⏳ Production Strategy (app.pokedex.online)

• ⏳ Ready to test but requires Synology access
• ✅ Configuration files ready (.env.production, docker-compose.production.yml)
• ✅ Deploy script updated (./deploy.sh --target production)
• ✅ Build verification configured for https://app.pokedex.online/oauth/callback
• ℹ️ Manual testing on Synology recommended before marking complete

Summary of Changes

Environment Management

• Created mode-specific .env files for each deployment strategy:
  • .env.development - Dev server (localhost:5173)
  • .env.docker-local - Local Docker (localhost:8099)
  • .env.production - Synology (https://app.pokedex.online)
• Removed redundant .env.example files to eliminate confusion
• Backend uses matching .env.{mode} files in server/ directory

Deployment Script (deploy.sh)

• Simplified from 3 targets (internal/external/local) to 2 (local/production)
• Automated Vite build with correct mode flags
• Integrated build verification into deployment pipeline
• Environment-specific Docker compose file selection
• Comprehensive health checks for both frontend and backend

Build Verification (scripts/verify-build.js)

• Extracts embedded redirect URIs from built JavaScript bundles
• Validates URLs match expected deployment target
• Fails deployment if incorrect configuration detected
• Provides clear error messages and remediation steps

Backend Validation (server/utils/env-validator.js)

• Requires explicit DEPLOYMENT_TARGET variable
• Validates FRONTEND_URL matches deployment target
• Single CORS origin per environment for security
• Refuses to start if environment misconfigured

Docker Configuration

• docker-compose.docker-local.yml - Local testing with explicit DEPLOYMENT_TARGET
• docker-compose.production.yml - Synology deployment with production URLs
• Both use environment-specific .env files
• nginx.conf accepts requests from localhost, 10.0.0.81, and app.pokedex.online

Package.json Scripts

All three package.json files updated with streamlined scripts:

Root package.json:

• npm run pokedex:dev - Start Vite dev server
• npm run pokedex:dev:full - Start dev server + backend
• npm run pokedex:docker:local - Local Docker deployment
• npm run pokedex:deploy:local - Deploy via deploy.sh (local)
• npm run pokedex:deploy:prod - Deploy via deploy.sh (production)

pokedex.online/package.json:

• npm run dev - Vite dev server
• npm run dev:full - Dev server + backend (concurrent)
• npm run docker:local - Local Docker up
• npm run docker:local:down - Local Docker down
• npm run docker:local:logs - View local Docker logs
• npm run deploy:local - Deploy to local Docker
• npm run deploy:prod - Deploy to Synology

server/package.json:

• npm run dev - Start backend (loads .env automatically)
• npm run validate - Check environment configuration

Key Design Decisions

1. Vite Mode Names: Used docker-local instead of local because Vite reserves .local suffix
2. Single CORS Origin: Each deployment target has exactly one frontend URL for security
3. Explicit Deployment Target: Backend requires DEPLOYMENT_TARGET to prevent misconfiguration
4. Automatic Verification: Build process validates embedded URLs before deployment
5. Simplified Targets: Removed internal/external confusion - just "local" and "production"

Next Steps for Production Deployment

The production deployment to Synology requires manual setup or SSH automation.

Option 1: Manual Deployment (Recommended for First Time)

After running ./deploy.sh --target production --skip-tests locally to build:

# 1. Ensure .env.production is on the Synology server
scp server/.env.production user@10.0.0.81:/volume1/docker/pokedex-online/server/.env

# 2. Copy built frontend
rsync -avz dist/ user@10.0.0.81:/volume1/docker/pokedex-online/dist/

# 3. Copy server code
rsync -avz --exclude node_modules server/ user@10.0.0.81:/volume1/docker/pokedex-online/server/

# 4. Copy Docker configuration
scp docker-compose.production.yml nginx.conf Dockerfile.frontend user@10.0.0.81:/volume1/docker/pokedex-online/
scp server/Dockerfile user@10.0.0.81:/volume1/docker/pokedex-online/server/

# 5. SSH to Synology and deploy
ssh user@10.0.0.81
cd /volume1/docker/pokedex-online
docker compose -f docker-compose.production.yml up -d --build

Option 2: Add SSH Automation to deploy.sh

To enable automated SSH deployment, the deploy_to_server() function in deploy.sh needs to be enhanced with:

• SSH connection to 10.0.0.81
• File transfer via rsync
• Remote Docker commands
• Health check verification

This would replicate the functionality that was in deploy-pokedex.js but using the new environment structure.

Deployment Commands Reference

# Development (Vite dev server + backend)
cd code/websites/pokedex.online
npm run dev:full

# Local Docker Testing
cd code/websites/pokedex.online
./deploy.sh --target local

# Production Deployment
cd code/websites/pokedex.online
./deploy.sh --target production

# From root directory
npm run pokedex:dev           # Dev mode
npm run pokedex:docker:local  # Local Docker
npm run pokedex:deploy:prod   # Production