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
- [x] Create `.env.development`
- [x] Create `.env.local`
- [x] Create `.env.production`
- [x] Delete root `.env.example`
- [x] Delete `server/.env`

### Phase 2: Deployment Scripts
- [x] Refactor `deploy.sh` to use `local/production` targets
- [x] Create `scripts/verify-build.js`
- [x] Update build process to auto-verify

### Phase 3: Backend Validation
- [x] Add `DEPLOYMENT_TARGET` to env-validator.js
- [x] Implement environment mismatch detection
- [x] Update CORS to single origin per target

### Phase 4: Docker Configuration
- [x] Create `docker-compose.local.yml`
- [x] Update `docker-compose.production.yml`
- [x] Update `nginx.conf` server_name

### Phase 5: Scripts Consolidation
- [x] Update pokedex.online package.json
- [x] Update server package.json
- [x] Update root package.json
- [x] 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:

```bash
# 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

```bash
# 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
```