Shatteredvoid/STARTUP_GUIDE.md

# Shattered Void MMO - Startup System Guide

This guide covers the comprehensive startup system for the Shattered Void MMO, providing multiple ways to launch and manage the game services.

## Quick Start

The easiest way to start the game:

```bash
# Simple startup with all default settings
./start.sh

# Or using npm
npm run game
```

## Startup Options

### Shell Script (Recommended)

The `start.sh` script provides the most user-friendly interface:

```bash
# Development mode (default)
./start.sh

# Production mode
./start.sh --env production

# Debug mode with verbose logging
./start.sh --debug --verbose

# Backend only (no frontend)
./start.sh --no-frontend

# Custom port
./start.sh --port 8080

# Skip database checks (useful for testing)
./start.sh --no-database --skip-preflight
```

### NPM Scripts

```bash
# Comprehensive startup with full system validation
npm run start:game

# Environment-specific startup
npm run start:dev        # Development mode
npm run start:prod       # Production mode
npm run start:staging    # Staging mode

# Quick startup (shell script)
npm run start:quick

# Debug mode
npm run start:debug

# Backend only
npm run start:backend-only
```

### Direct Node.js

```bash
# Direct startup (bypasses some safety checks)
node start-game.js

# With environment
NODE_ENV=production node start-game.js
```

## Configuration

### Environment Variables

The startup system respects these environment variables:

```bash
# Core settings
NODE_ENV=development|production|staging|testing
PORT=3000                           # Backend port
FRONTEND_PORT=5173                  # Frontend port
HOST=0.0.0.0                       # Host binding

# Service toggles
ENABLE_FRONTEND=true|false          # Enable/disable frontend
DISABLE_DATABASE=true|false         # Skip database
DISABLE_REDIS=true|false           # Skip Redis
ENABLE_HEALTH_MONITORING=true|false # Health checks

# Startup behavior
SKIP_PREFLIGHT=true|false          # Skip system checks
VERBOSE_STARTUP=true|false         # Detailed logging
AUTO_MIGRATE=true|false            # Auto-run migrations
AUTO_SEED=true|false               # Auto-run seeds

# Visual settings
DISABLE_BANNER=true|false          # Hide startup banner
DISABLE_COLORS=true|false          # Disable colored output
```

### Configuration File

Advanced configuration is available in `config/startup.config.js`:

```javascript
// Example: Custom timeout settings
const config = {
  backend: {
    startupTimeout: 30000,     // 30 seconds
    healthEndpoint: '/health'
  },
  database: {
    migrationTimeout: 60000,   // 60 seconds
    autoMigrate: true
  },
  healthMonitoring: {
    interval: 30000,           // 30 seconds
    alertThresholds: {
      responseTime: 5000,      // 5 seconds
      memoryUsage: 80          // 80%
    }
  }
};
```

## System Components

### 1. Pre-flight Checks (`scripts/startup-checks.js`)

Validates system requirements before startup:

- ✅ Node.js version (18+)
- ✅ NPM availability
- ✅ Environment configuration
- ✅ Directory structure
- ✅ Package dependencies
- ✅ Port availability
- ✅ Database configuration
- ✅ Redis configuration (optional)
- ✅ Log directories
- ✅ Frontend dependencies (optional)
- ✅ System memory (1GB+ recommended)
- ✅ Disk space (<90% usage)
- ✅ File permissions

Test individually:
```bash
npm run system:check
```

### 2. Database Validation (`scripts/database-validator.js`)

Comprehensive database health checks:

- 🔗 Connectivity testing
- 📦 Migration status and auto-execution
- 🏗️ Schema structure validation
- 🌱 Seed data verification
- 🔍 Data integrity checks
- 📊 Performance metrics

Test individually:
```bash
npm run db:validate
```

### 3. Health Monitoring (`scripts/health-monitor.js`)

Real-time service monitoring:

- 🏥 Service health checks
- 📈 Performance metrics
- 🚨 Alert system
- 📊 Uptime tracking
- 💾 System resource monitoring

Test individually:
```bash
npm run health:check
```

### 4. Main Orchestrator (`start-game.js`)

Central startup coordination:

- 🎭 Phase-based startup
- ⏱️ Timeout management
- 🔄 Retry logic
- 📝 Comprehensive logging
- 🛑 Graceful shutdown
- 📊 Performance metrics
- 🔧 Node.js version compatibility detection
- 📦 Automatic frontend fallback for older Node.js versions

## Node.js Version Compatibility

The system automatically detects Node.js version compatibility and handles Vite development server limitations:

### Vite Development Server Requirements

- **Node.js 20+**: Full Vite development server support
- **Node.js 18-19**: Automatic fallback to built frontend static server
- **Node.js <18**: Not supported

### Automatic Fallback Behavior

When Node.js version is incompatible with Vite 7.x (requires `crypto.hash()` from Node.js 20+):

1. **Detection**: System detects Node.js version during startup
2. **Warning**: Clear warning about version compatibility
3. **Fallback**: Automatically serves built frontend from `/frontend/dist/`
4. **Status**: Frontend shows as "static" mode in startup summary

```bash
# Example startup output with Node.js 18.x
Node.js version: v18.19.1
Node.js v18.19.1 is not compatible with Vite 7.x (requires Node.js 20+)
crypto.hash() function is not available in this Node.js version
Attempting to serve built frontend as fallback...
Built frontend fallback started in 5ms

║ ✅ Frontend:5173 (static)                                 ║
```

### Configuration Options

Control fallback behavior with environment variables:

```bash
# Disable frontend fallback (fail if Vite incompatible)
FRONTEND_FALLBACK=false ./start.sh

# Force use built frontend even with compatible Node.js
# (automatically happens if Vite dev server fails for any reason)
```

### Building Frontend for Fallback

Ensure built frontend is available:

```bash
# Build frontend for production/fallback use
cd frontend
npm run build

# Verify build exists
ls -la dist/
```

## Startup Phases

The startup system follows these phases:

1. **🔍 Pre-flight Checks** - System validation
2. **🗄️ Database Validation** - DB connectivity and migrations
3. **🖥️ Backend Server Startup** - Express server launch
4. **🌐 Frontend Server Startup** - React dev server (if enabled)
5. **🏥 Health Monitoring** - Service monitoring activation

Each phase includes:
- ⏱️ Timing metrics
- 🔄 Retry logic
- ❌ Error handling
- 📊 Progress reporting

## Service Management

### Starting Services

```bash
# Full stack (backend + frontend + monitoring)
./start.sh

# Backend only
./start.sh --no-frontend

# Skip health monitoring
./start.sh --no-health

# Database-free mode (for testing)
./start.sh --no-database
```

### Stopping Services

```bash
# Graceful shutdown
Ctrl+C

# Force stop (if needed)
pkill -f start-game.js
```

### Service Status

The startup system provides real-time status:

```
╔═══════════════════════════════════════════════════════════════╗
║                        STARTUP SUMMARY                       ║
╠═══════════════════════════════════════════════════════════════╣
║ Total Duration: 2847ms                                        ║
║                                                               ║
║ Services Status:                                              ║
║ ✅ Preflight                                                  ║
║ ✅ Database                                                   ║
║ ✅ Backend:3000                                               ║
║ ✅ Frontend:5173                                              ║
║ ✅ HealthMonitor                                              ║
╚═══════════════════════════════════════════════════════════════╝
```

## Troubleshooting

### Common Issues

1. **Port already in use**
   ```bash
   # Use different port
   ./start.sh --port 8080
   
   # Or kill existing process
   lsof -ti:3000 | xargs kill
   ```

2. **Database connection failed**
   ```bash
   # Check PostgreSQL status
   sudo systemctl status postgresql
   
   # Start PostgreSQL
   sudo systemctl start postgresql
   
   # Create database
   createdb shattered_void_dev
   ```

3. **Missing dependencies**
   ```bash
   # Install dependencies
   npm install
   
   # Install frontend dependencies
   cd frontend && npm install
   ```

4. **Migration issues**
   ```bash
   # Reset database
   npm run db:reset
   
   # Manual migration
   npm run db:migrate
   ```

5. **Vite development server fails (Node.js compatibility)**
   ```bash
   # Check Node.js version
   node --version
   
   # If Node.js < 20, system will automatically fallback
   # To upgrade Node.js:
   # Using nvm:
   nvm install 20
   nvm use 20
   
   # Using package manager:
   # Ubuntu/Debian: sudo apt update && sudo apt install nodejs
   # MacOS: brew install node@20
   
   # Verify fallback works by ensuring frontend is built:
   cd frontend && npm run build
   ```

6. **Frontend fallback not working**
   ```bash
   # Ensure frontend is built
   cd frontend
   npm install
   npm run build
   
   # Verify build directory exists
   ls -la dist/
   
   # Check if Express is available (should be in package.json)
   npm list express
   ```

### Debug Mode

Enable comprehensive debugging:

```bash
# Maximum verbosity
./start.sh --debug --verbose

# Or with environment variables
DEBUG=* VERBOSE_STARTUP=true ./start.sh
```

### Logs

Access different log streams:

```bash
# Combined logs
npm run logs

# Error logs only
npm run logs:error

# Startup logs
npm run logs:startup

# Audit logs
npm run logs:audit
```

### Health Check Endpoints

Once running, access health information:

```bash
# Backend health
curl http://localhost:3000/health

# Health monitoring data (if debug endpoints enabled)
curl http://localhost:3000/debug/health
```

## Production Deployment

### Production Mode

```bash
# Production startup
./start.sh --env production

# Or with npm
npm run start:prod
```

Production mode changes:
- 🚫 Frontend disabled (serves pre-built assets)
- ⚡ Faster health check intervals
- 🔒 Enhanced security checks
- 📊 Performance monitoring enabled
- 🚨 Stricter error handling

### Environment Variables for Production

```bash
NODE_ENV=production
DISABLE_FRONTEND=true          # Use nginx/CDN for frontend
ENABLE_HEALTH_MONITORING=true
LOG_LEVEL=warn
CRASH_REPORTING=true
PERFORMANCE_REPORTING=true
```

### Docker Integration

The startup system works with Docker:

```bash
# Build Docker image
npm run docker:build

# Run with Docker Compose
npm run docker:run
```

## Development Tips

### Quick Development Cycle

```bash
# Fast startup without full checks
SKIP_PREFLIGHT=true ./start.sh --no-frontend

# Backend only with auto-restart
npm run dev
```

### Testing the Startup System

```bash
# Test all components
npm run system:check    # Pre-flight checks
npm run db:validate     # Database validation
npm run health:check    # Health monitoring

# Test specific scenarios
./start.sh --no-database --skip-preflight  # Minimal startup
./start.sh --debug --log-file startup.log  # Full logging
```

### Customizing the Startup

Modify `config/startup.config.js` for custom behavior:

```javascript
module.exports = {
  backend: {
    startupTimeout: 45000,  // Longer timeout
    port: 8080             // Different default port
  },
  preflightChecks: {
    enabled: false         // Skip checks in development
  }
};
```

## API Reference

### Startup Script Options

| Option | Environment Variable | Description |
|--------|---------------------|-------------|
| `--env ENV` | `NODE_ENV` | Set environment mode |
| `--port PORT` | `PORT` | Backend server port |
| `--frontend-port PORT` | `FRONTEND_PORT` | Frontend server port |
| `--no-frontend` | `ENABLE_FRONTEND=false` | Disable frontend |
| `--no-health` | `ENABLE_HEALTH_MONITORING=false` | Disable health monitoring |
| `--no-database` | `DISABLE_DATABASE=true` | Skip database |
| `--no-redis` | `DISABLE_REDIS=true` | Skip Redis |
| `--skip-preflight` | `SKIP_PREFLIGHT=true` | Skip system checks |
| `--verbose` | `VERBOSE_STARTUP=true` | Enable verbose logging |
| `--debug` | `DEBUG=*` | Enable debug mode |
| `--no-colors` | `DISABLE_COLORS=true` | Disable colored output |

### NPM Scripts Reference

| Script | Description |
|--------|-------------|
| `npm run game` | Quick startup (shell script) |
| `npm run start:game` | Full startup with validation |
| `npm run start:dev` | Development mode |
| `npm run start:prod` | Production mode |
| `npm run start:debug` | Debug mode |
| `npm run start:backend-only` | Backend only |
| `npm run system:check` | Run system checks |
| `npm run health:check` | Test health monitoring |
| `npm run db:validate` | Validate database |

## Contributing

When modifying the startup system:

1. **Test all scenarios** - Test with different combinations of flags
2. **Update documentation** - Keep this guide current
3. **Maintain backward compatibility** - Don't break existing workflows
4. **Add comprehensive logging** - Help with debugging
5. **Follow error handling patterns** - Use the established error classes

The startup system is designed to be:
- 🛡️ **Robust** - Handles failures gracefully
- 🔧 **Configurable** - Adapts to different environments
- 📊 **Observable** - Provides comprehensive monitoring
- 🚀 **Fast** - Optimized startup performance
- 🎯 **User-friendly** - Clear interface and error messages

---

For more information, see the individual component documentation or run `./start.sh --help`.