🚀 Update deployment instructions in documentation
This commit is contained in:
188
code/websites/pokedex.online/DEPLOYMENT.md
Normal file
188
code/websites/pokedex.online/DEPLOYMENT.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user