FragginWagon
fee8fe2551
- Created docker-compose.docker-local.yml for local testing of frontend and backend services. - Added .env.development for development environment configuration. - Introduced .env.docker-local for local Docker environment settings. - Added .env.production for production environment configuration for Synology deployment.
360 lines
8.9 KiB
Markdown
360 lines
8.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Standard internal deployment
|
|
./deploy.sh --target internal
|
|
|
|
# External deployment with custom ports
|
|
./deploy.sh --target external --port 8080
|
|
|
|
# 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
|
|
|
|
```bash
|
|
# 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 --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:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Clean and rebuild
|
|
rm -rf dist node_modules
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### Container Won't Start
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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/`:
|
|
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
ssh GregRJacobs@10.0.0.81 -p 2323
|
|
cd /volume1/docker/pokedex.online
|
|
docker compose down
|
|
```
|
|
|
|
**2. Restore from Backup (Local)**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
./deploy.sh --skip-tests --target internal
|
|
```
|
|
|
|
### Quick Restart
|
|
|
|
If you just need to restart existing containers without code changes:
|
|
|
|
```bash
|
|
# On the server
|
|
cd /volume1/docker/pokedex.online
|
|
docker compose restart
|
|
```
|
|
|
|
### Git-Based Rollback
|
|
|
|
Roll back to a previous commit:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|