# 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