189 lines
4.6 KiB
Markdown
189 lines
4.6 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)
|
|
|
|
## 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 --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:
|
|
|
|
```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
|
|
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:
|
|
|
|
```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
|