Initial commit

apps/startup-scripts/README.md

@@ -0,0 +1,685 @@
+# AzerothCore Startup Scripts
+
+A comprehensive suite of scripts for managing AzerothCore server instances with advanced session management, automatic restart capabilities, and production-ready service management.
+
+## 📋 Table of Contents
+
+- [Overview](#overview)
+- [Components](#components)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Detailed Usage](#detailed-usage)
+- [Multiple Realms Setup](#multiple-realms-setup)
+- [Service Management](#service-management)
+- [Troubleshooting](#troubleshooting)
+
+## 🎯 Overview
+
+The AzerothCore startup scripts provide multiple approaches to running server instances:
+
+1. **Development/Testing**: Simple execution for debugging and development
+2. **Production with Restarts**: Automatic restart on crashes with crash detection
+3. **Background Services**: Production-ready service management with PM2 or systemd
+4. **Session Management**: Interactive console access via tmux/screen
+
+All scripts are integrated into the `acore.sh` dashboard for easy access.
+
+### 📦 Automatic Deployment
+
+**Important**: When you compile AzerothCore using the acore dashboard (`./acore.sh compiler build`), all startup scripts are automatically copied from `apps/startup-scripts/src/` to your `bin/` folder. This means:
+
+- ✅ **Portable Deployment**: You can copy the entire `bin/` folder to different servers
+- ✅ **Self-Contained**: All restart and service management tools travel with your binaries  
+- ✅ **No Additional Setup**: Scripts work immediately after deployment
+- ✅ **Production Ready**: Deploy to production servers without needing the full source code
+
+This makes it easy to deploy your compiled binaries along with the management scripts to production environments where you may not have the full AzerothCore source code.
+
+## 🔧 Components
+
+### Core Scripts
+
+- **`run-engine`**: Advanced script with session management and configuration priority
+- **`simple-restarter`**: Wrapper around starter with restart functionality (legacy compatibility)
+- **`starter`**: Basic binary execution with optional GDB support
+- **`service-manager.sh`**: Production service management with PM2/systemd
+
+### Configuration
+
+- **`conf.sh.dist`**: Default configuration template
+- **`conf.sh`**: User configuration (create from .dist)
+- **`gdb.conf`**: GDB debugging configuration
+
+### Examples
+
+- **`restarter-auth.sh`**: Auth server restart example
+- **`restarter-world.sh`**: World server restart example
+- **`starter-auth.sh`**: Auth server basic start example
+- **`starter-world.sh`**: World server basic start example
+
+## 🚀 Quick Start
+
+### 1. Basic Server Start (Development)
+
+```bash
+# Start authserver directly
+./starter /path/to/bin authserver
+
+# Start worldserver with config
+./starter /path/to/bin worldserver "" /path/to/worldserver.conf
+```
+
+### 2. Start with Auto-Restart
+
+```bash
+# Using simple-restarter (legacy)
+./simple-restarter /path/to/bin authserver
+
+# Using run-engine (recommended)
+./run-engine restart authserver --bin-path /path/to/bin
+```
+
+### 3. Production Service Management
+
+```bash
+# Create and start a service
+./service-manager.sh create auth authserver --bin-path /path/to/bin
+
+# List all services
+./service-manager.sh list
+
+# Stop a service
+./service-manager.sh stop auth
+```
+
+### 4. Using acore.sh Dashboard
+
+```bash
+# Interactive dashboard
+./acore.sh
+
+# Direct commands
+./acore.sh run-authserver    # Start authserver with restart
+./acore.sh run-worldserver   # Start worldserver with restart
+./acore.sh service-manager   # Access service manager
+```
+
+## ⚙️ Configuration
+
+### Configuration Priority (Highest to Lowest)
+
+1. **`conf.sh`** - User configuration file
+2. **Command line arguments** - Runtime parameters
+3. **Environment variables** - `RUN_ENGINE_*` variables
+4. **`conf.sh.dist`** - Default configuration
+
+### Creating Configuration
+
+```bash
+# Copy default configuration
+cp scripts/conf.sh.dist scripts/conf.sh
+
+# Edit your configuration
+nano scripts/conf.sh
+```
+
+### Key Configuration Options
+
+```bash
+# Binary settings
+export BINPATH="/path/to/azerothcore/bin"
+export SERVERBIN="worldserver"  # or "authserver"
+export CONFIG="/path/to/worldserver.conf"
+
+# Session management
+export SESSION_MANAGER="tmux"  # none|auto|tmux|screen
+export SESSION_NAME="ac-world"
+
+# Interactive mode control
+export AC_DISABLE_INTERACTIVE="0"  # Set to 1 to disable interactive prompts (useful for non-interactive services)
+
+# Debugging
+export GDB_ENABLED="1"  # 0 or 1
+export GDB="/path/to/gdb.conf"
+
+# Logging
+export LOGS_PATH="/path/to/logs"
+export CRASHES_PATH="/path/to/crashes"
+export LOG_PREFIX_NAME="realm1"
+```
+
+## 📖 Detailed Usage
+
+### 1. Run Engine
+
+The `run-engine` is the most advanced script with multiple operation modes:
+
+#### Basic Execution
+```bash
+# Start server once
+./run-engine start worldserver --bin-path /path/to/bin
+
+# Start with configuration file
+./run-engine start worldserver --config ./conf-world.sh
+
+# Start with specific server config
+./run-engine start worldserver --server-config /path/to/worldserver.conf
+```
+
+#### Restart Mode
+```bash
+# Automatic restart on crash
+./run-engine restart worldserver --bin-path /path/to/bin
+
+# Restart with session management
+./run-engine restart worldserver --session-manager tmux
+```
+
+#### Session Management
+```bash
+# Start in tmux session
+./run-engine start worldserver --session-manager tmux
+
+# Attach to existing session
+tmux attach-session -t worldserver
+
+# Start in screen session
+./run-engine start worldserver --session-manager screen
+
+# Attach to screen session
+screen -r worldserver
+```
+
+#### Configuration Options
+```bash
+./run-engine restart worldserver \
+  --bin-path /path/to/bin \
+  --server-config /path/to/worldserver.conf \
+  --session-manager tmux \
+  --gdb-enabled 1 \
+  --logs-path /path/to/logs \
+  --crashes-path /path/to/crashes
+```
+
+### 2. Simple Restarter
+
+Legacy-compatible wrapper with restart functionality:
+
+```bash
+# Basic restart
+./simple-restarter /path/to/bin worldserver
+
+# With full parameters
+./simple-restarter \
+  /path/to/bin \
+  worldserver \
+  ./gdb.conf \
+  /path/to/worldserver.conf \
+  /path/to/system.log \
+  /path/to/system.err \
+  1 \
+  /path/to/crashes
+```
+
+**Parameters:**
+1. Binary path (required)
+2. Binary name (required)
+3. GDB configuration file (optional)
+4. Server configuration file (optional)
+5. System log file (optional)
+6. System error file (optional)
+7. GDB enabled flag (0/1, optional)
+8. Crashes directory path (optional)
+
+### 3. Starter
+
+Basic execution script without restart functionality:
+
+```bash
+# Simple start
+./starter /path/to/bin worldserver
+
+# With GDB debugging
+./starter /path/to/bin worldserver ./gdb.conf /path/to/worldserver.conf "" "" 1
+```
+
+### 4. Service Manager
+
+Production-ready service management:
+
+#### Creating Services
+```bash
+# Auto-detect provider (PM2 or systemd)
+./service-manager.sh create auth authserver --bin-path /path/to/bin
+
+# Force PM2
+./service-manager.sh create world worldserver --provider pm2 --bin-path /path/to/bin
+
+# Force systemd
+./service-manager.sh create world worldserver --provider systemd --bin-path /path/to/bin
+
+# Create service with restart policy
+./service-manager.sh create world worldserver --bin-path /path/to/bin --restart-policy always
+```
+
+#### Restart Policies
+
+Services support two restart policies:
+
+- **`on-failure`** (default): Restart only on crashes or errors (exit code != 0, only works with PM2 or systemd without tmux/screen)
+- **`always`**: Restart on any exit, including clean shutdown (exit code 0)
+
+**Important**: When using `--restart-policy always`, the in-game command `server shutdown X` will behave like `server restart X` - the service will automatically restart after shutdown. Only the shutdown message differs from a restart message.
+
+```bash
+# Service that restarts only on crashes (default behavior)
+./service-manager.sh create auth authserver --bin-path /path/to/bin --restart-policy on-failure
+
+# Service that always restarts (even on manual shutdown)
+./service-manager.sh create world worldserver --bin-path /path/to/bin --restart-policy always
+
+# Update existing service restart policy
+./service-manager.sh update worldserver --restart-policy always
+```
+
+#### Service Operations
+```bash
+# Start/stop services
+./service-manager.sh start auth
+./service-manager.sh stop world
+./service-manager.sh restart auth
+
+# View logs
+./service-manager.sh logs world
+./service-manager.sh logs world --follow
+
+# Attach to console (interactive)
+./service-manager.sh attach world
+
+# List services
+./service-manager.sh list
+./service-manager.sh list pm2
+./service-manager.sh list systemd
+
+# Delete service
+./service-manager.sh delete auth
+```
+
+#### Health and Console Commands
+
+Use these commands to programmatically check service health and interact with the console (used by CI workflows):
+
+```bash
+# Check if service is currently running (exit 0 if running)
+./service-manager.sh is-running world
+
+# Print current uptime in seconds (fails if not running)
+./service-manager.sh uptime-seconds world
+
+# Wait until uptime >= 10s (optional timeout 240s)
+./service-manager.sh wait-uptime world 10 240
+
+# Send a console command (uses pm2 send or tmux/screen)
+./service-manager.sh send world "server info"
+
+# Show provider, configs and run-engine settings
+./service-manager.sh show-config world
+```
+
+Notes:
+- For `send`, PM2 provider uses `pm2 send` with the process ID; systemd provider requires a session manager (tmux/screen). If no attachable session is configured, the command fails.
+- `wait-uptime` fails with a non-zero exit code if the service does not reach the requested uptime within the timeout window.
+
+#### Service Configuration
+```bash
+# Update service settings
+./service-manager.sh update world --session-manager screen --gdb-enabled 1
+
+# Edit configuration
+./service-manager.sh edit world
+
+# Restore missing services from registry
+./service-manager.sh restore
+```
+
+## 🌍 Multiple Realms Setup
+
+### Method 1: Using Service Manager (Recommended)
+
+```bash
+# Create multiple world server instances with different restart policies
+./service-manager.sh create world1 worldserver \
+  --bin-path /path/to/bin \
+  --server-config /path/to/worldserver-realm1.conf \
+  --restart-policy on-failure
+
+./service-manager.sh create world2 worldserver \
+  --bin-path /path/to/bin \
+  --server-config /path/to/worldserver-realm2.conf \
+  --restart-policy always
+
+# Single auth server for all realms (always restart for stability)
+./service-manager.sh create auth authserver \
+  --bin-path /path/to/bin \
+  --server-config /path/to/authserver.conf \
+  --restart-policy always
+```
+
+### Method 2: Using Run Engine with Different Configurations
+
+Create separate configuration files for each realm:
+
+**conf-realm1.sh:**
+```bash
+export BINPATH="/path/to/bin"
+export SERVERBIN="worldserver"
+export CONFIG="/path/to/worldserver-realm1.conf"
+export SESSION_NAME="ac-realm1"
+export LOG_PREFIX_NAME="realm1"
+export LOGS_PATH="/path/to/logs/realm1"
+```
+
+**conf-realm2.sh:**
+```bash
+export BINPATH="/path/to/bin"
+export SERVERBIN="worldserver"
+export CONFIG="/path/to/worldserver-realm2.conf"
+export SESSION_NAME="ac-realm2"
+export LOG_PREFIX_NAME="realm2"
+export LOGS_PATH="/path/to/logs/realm2"
+```
+
+Start each realm:
+```bash
+./run-engine restart worldserver --config ./conf-realm1.sh
+./run-engine restart worldserver --config ./conf-realm2.sh
+```
+
+### Method 3: Using Examples with Custom Configurations
+
+Copy and modify the example scripts:
+
+```bash
+# Copy examples
+cp examples/restarter-world.sh restarter-realm1.sh
+cp examples/restarter-world.sh restarter-realm2.sh
+
+# Edit each script to point to different configuration files
+# Then run:
+./restarter-realm1.sh
+./restarter-realm2.sh
+```
+
+## 🛠️ Service Management
+
+### Service Registry and Persistence
+
+The service manager includes a comprehensive registry system that tracks all created services and enables automatic restoration:
+
+#### Service Registry Features
+
+- **Automatic Tracking**: All services are automatically registered when created
+- **Cross-Reboot Persistence**: PM2 services are configured with startup persistence
+- **Service Restoration**: Missing services can be detected and restored from registry
+- **Migration Support**: Legacy service configurations can be migrated to the new format
+
+#### Using the Registry
+
+```bash
+# Check for missing services and restore them
+./service-manager.sh restore
+
+# List all registered services (includes status)
+./service-manager.sh list
+
+# Services are automatically added to registry on creation
+./service-manager.sh create auth authserver --bin-path /path/to/bin
+```
+
+#### Custom Configuration Directories
+
+You can customize where service configurations and PM2/systemd files are stored:
+
+```bash
+# Set custom directories
+export AC_SERVICE_CONFIG_DIR="/path/to/your/project/services"
+
+# Now all service operations will use these custom directories
+./service-manager.sh create auth authserver --bin-path /path/to/bin
+```
+
+This is particularly useful for:
+- **Version Control**: Keep service configurations in your project repository
+- **Multiple Projects**: Separate service configurations per project
+- **Team Collaboration**: Share service setups across development teams
+
+#### Service Configuration Portability
+
+The service manager automatically stores binary and configuration paths as relative paths when they are located under the `AC_SERVICE_CONFIG_DIR`, making service configurations portable across environments:
+
+```bash
+# Set up a portable project structure
+export AC_SERVICE_CONFIG_DIR="/opt/myproject/services"
+mkdir -p "$AC_SERVICE_CONFIG_DIR"/{bin,etc}
+
+# Copy your binaries and configs
+cp /path/to/compiled/authserver "$AC_SERVICE_CONFIG_DIR/bin/"
+cp /path/to/authserver.conf "$AC_SERVICE_CONFIG_DIR/etc/"
+
+# Create service - paths under AC_SERVICE_CONFIG_DIR will be stored as relative
+./service-manager.sh create auth authserver \
+  --bin-path "$AC_SERVICE_CONFIG_DIR/bin" \
+  --server-config "$AC_SERVICE_CONFIG_DIR/etc/authserver.conf"
+
+# Registry will contain relative paths like "bin/authserver" and "etc/authserver.conf"
+# instead of absolute paths, making the entire directory portable
+```
+
+**Benefits:**
+- **Environment Independence**: Move the entire services directory between machines
+- **Container Friendly**: Perfect for Docker volumes and bind mounts
+- **Backup/Restore**: Archive and restore complete service configurations
+- **Development/Production Parity**: Same relative structure across environments
+
+**How it works:**
+- Paths under `AC_SERVICE_CONFIG_DIR` are automatically stored as relative paths
+- Paths outside `AC_SERVICE_CONFIG_DIR` are stored as absolute paths for safety
+- When services are restored or started, relative paths are resolved from `AC_SERVICE_CONFIG_DIR`
+- If `AC_SERVICE_CONFIG_DIR` is not set, all paths are stored as absolute paths (traditional behavior)
+
+#### Migration from Legacy Format
+
+If you have existing services in the old format, use the migration script:
+
+```bash
+# Migrate existing registry to new format
+./migrate-registry.sh
+
+# The script will:
+# - Detect old format automatically
+# - Create a backup of the old registry
+# - Convert to new format with proper tracking
+# - Preserve all existing service information
+```
+
+### PM2 Services
+
+When using PM2 as the service provider:
+
+* [PM2 CLI Documentation](https://pm2.io/docs/runtime/reference/pm2-cli/)
+
+**Automatic PM2 Persistence**: The service manager automatically configures PM2 for persistence across reboots by:
+- Running `pm2 startup` to set up the startup script
+- Running `pm2 save` after each service creation/modification
+- This ensures your services automatically start when the system reboots
+
+NOTE: pm2 cannot run tmux/screen sessions, but you can always use the `attach` command to connect to the service console because pm2 supports interactive mode.
+
+### Environment Variables
+
+The startup scripts recognize several environment variables for configuration and runtime behavior:
+
+#### Configuration Directory Variables
+
+- **`AC_SERVICE_CONFIG_DIR`**: Override the default configuration directory for services registry and configurations
+  - Default: `${XDG_CONFIG_HOME:-$HOME/.config}/azerothcore/services`
+  - Used for storing service registry and run-engine configurations
+
+#### Service Detection Variables
+
+- **`AC_LAUNCHED_BY_PM2`**: Set to `1` when launched by PM2 (automatically set by service-manager)
+  - Disables the use of the `unbuffer` command for output capture
+  - Enables non-interactive mode to prevent prompts
+  - More robust than relying on PM2's internal variables
+  
+- **`AC_DISABLE_INTERACTIVE`**: Controls interactive mode (0=enabled, 1=disabled)
+  - Automatically set based on execution context
+  - Prevents AzerothCore from showing interactive prompts in service environments
+
+#### Configuration Variables
+
+- **`RUN_ENGINE_*`**: See [Configuration](#configuration) section for complete list
+- **`SERVICE_MODE`**: Set to `true` to enable service-specific behavior
+- **`SESSION_MANAGER`**: Override session manager choice (tmux, screen, none, auto)
+
+### Systemd Services
+
+When using systemd as the service provider:
+
+```bash
+# Systemd commands
+systemctl --user status acore-auth     # Check status
+systemctl --user logs acore-auth       # View logs
+systemctl --user restart acore-auth    # Restart
+systemctl --user enable acore-auth     # Enable auto-start
+
+# For system services (requires sudo)
+sudo systemctl status acore-auth
+sudo systemctl enable acore-auth
+```
+
+**Enhanced systemd Integration:**
+- **Automatic Service Type**: When using session managers (tmux/screen), services are automatically configured with `Type=forking` for proper daemon behavior
+- **Smart ExecStop**: Services with session managers get automatic `ExecStop` commands to properly terminate tmux/screen sessions when stopping the service
+- **Non-Interactive Mode**: Services without session managers automatically set `AC_DISABLE_INTERACTIVE=1` to prevent hanging on prompts
+
+### Session Management in Services
+
+Services can be configured with session managers for interactive access:
+
+```bash
+# Create service with tmux
+./service-manager.sh create world worldserver \
+  --bin-path /path/to/bin \
+  --session-manager tmux
+
+# Attach to the session
+./service-manager.sh attach world
+# or directly:
+tmux attach-session -t worldserver
+```
+
+## 🎮 Integration with acore.sh Dashboard
+
+The startup scripts are fully integrated into the AzerothCore dashboard:
+
+### Direct Commands
+
+```bash
+# Run servers with simple restart (development/testing)
+./acore.sh run-worldserver   # Option 11 or 'rw'
+./acore.sh run-authserver    # Option 12 or 'ra'
+
+# Access service manager (production)
+./acore.sh service-manager   # Option 15 or 'sm'
+
+# Examples:
+./acore.sh rw               # Quick worldserver start
+./acore.sh ra               # Quick authserver start
+./acore.sh sm create auth authserver --bin-path /path/to/bin
+```
+
+### What Happens Behind the Scenes
+
+- **run-worldserver/run-authserver**: Calls `simple-restarter` with appropriate binary
+- **service-manager**: Provides full access to the service management interface
+- Scripts automatically use the correct binary path from your build configuration
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### 1. Binary Not Found
+```bash
+Error: Binary '/path/to/bin/worldserver' not found
+```
+**Solution**: Check binary path and ensure servers are compiled
+```bash
+# Check if binary exists
+ls -la /path/to/bin/worldserver
+
+# Compile if needed
+./acore.sh compiler build
+```
+
+#### 2. Configuration File Issues
+```bash
+Error: Configuration file not found
+```
+**Solution**: Create configuration from template
+```bash
+cp scripts/conf.sh.dist scripts/conf.sh
+# Edit conf.sh with correct paths
+```
+
+#### 3. Session Manager Not Available
+```bash
+Warning: tmux not found, falling back to direct execution
+```
+**Solution**: Install required session manager
+```bash
+# Ubuntu/Debian
+sudo apt install tmux screen
+
+# CentOS/RHEL
+sudo yum install tmux screen
+```
+
+#### 4. Permission Issues (systemd)
+```bash
+Failed to create systemd service
+```
+**Solution**: Check user permissions or use --system flag
+```bash
+# For user services (no sudo required)
+./service-manager.sh create auth authserver --bin-path /path/to/bin
+
+# For system services (requires sudo)
+./service-manager.sh create auth authserver --bin-path /path/to/bin --system
+```
+
+#### 5. PM2 Not Found
+```bash
+Error: PM2 is not installed
+```
+**Solution**: Install PM2
+```bash
+npm install -g pm2
+# or
+sudo npm install -g pm2
+```
+
+#### 7. Registry Out of Sync
+```bash
+# If the service registry shows services that don't actually exist
+```
+**Solution**: Use registry sync or restore
+```bash
+# Check and restore missing services (also cleans up orphaned entries)
+./service-manager.sh restore
+
+# If you have a very old registry format, migrate it
+./migrate-registry.sh
+```
+
+