FragginWagon
161b758a1b
- Created new markdown file for Support Ticket - 3224942 with a link to the support page. - Added a separate markdown file for Supprt Tickets with the same link. - Updated workspace files to include new markdown files and attachments. - Added various attachments related to the support ticket, including images and PDFs.
227 lines
8.5 KiB
Markdown
227 lines
8.5 KiB
Markdown
# 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
|
||
```
|