diff --git a/docker-compose-azerothcore-database.env b/docker-compose-azerothcore-database.env index 501792a..ef76867 100644 --- a/docker-compose-azerothcore-database.env +++ b/docker-compose-azerothcore-database.env @@ -1,5 +1,11 @@ # AZEROTHCORE DATABASE LAYER ENVIRONMENT +# DEPLOYMENT CONFIGURATION +# Storage root path - local: ./storage, production: /nfs/containers or custom mount +STORAGE_ROOT=./storage +# Storage configuration for database layer +STORAGE_PATH=${STORAGE_ROOT}/azerothcore + # SERVER CONFIGURATION # Timezone TZ=UTC @@ -50,12 +56,6 @@ MYSQL_HEALTHCHECK_START_PERIOD=120s # External database port MYSQL_EXTERNAL_PORT=64306 -# DEPLOYMENT CONFIGURATION -# Storage root path - local: ./storage, production: /nfs/containers or custom mount -STORAGE_ROOT=./storage -# Storage configuration for database layer -STORAGE_PATH=${STORAGE_ROOT}/azerothcore - # CONTAINER NAMES # Database layer container names CONTAINER_MYSQL=ac-mysql @@ -70,8 +70,8 @@ NETWORK_GATEWAY=172.20.0.1 # BACKUP CONFIGURATION # Host volume paths for backup -HOST_BACKUP_PATH=./backups -HOST_BACKUP_SCRIPTS_PATH=./scripts +HOST_BACKUP_PATH=${STORAGE_PATH}/backups +HOST_BACKUP_SCRIPTS_PATH=${STORAGE_PATH}/scripts # Backup settings BACKUP_CRON_SCHEDULE="0 3 * * *" diff --git a/docker-compose-azerothcore-optional.env b/docker-compose-azerothcore-optional.env deleted file mode 100644 index f2697f5..0000000 --- a/docker-compose-azerothcore-optional.env +++ /dev/null @@ -1,53 +0,0 @@ -# ============================================== -# AZEROTHCORE OPTIONAL SERVICES ENVIRONMENT -# ============================================== -# Environment variables for modules and monitoring services - -# ============================================== -# DOCKER IMAGES (REQUIRED) -# ============================================== -# Optional service images -AC_ELUNA_IMAGE=acore/eluna-ts:master -ALPINE_GIT_IMAGE=alpine/git:latest - -# ============================================== -# IMAGE PULL POLICY (REQUIRED) -# ============================================== -IMAGE_PULL_POLICY=if_not_present - -# ============================================== -# DEPLOYMENT CONFIGURATION (REQUIRED) -# ============================================== -# Storage root path - local: ./storage, production: /nfs/containers or custom mount -STORAGE_ROOT=./storage -# Storage configuration (unified with other layers) -STORAGE_PATH=${STORAGE_ROOT}/azerothcore - -# Deployment mode -DEPLOYMENT_MODE=local - -# ============================================== -# CONTAINER NAMES (REQUIRED) -# ============================================== -# Optional service container names -CONTAINER_ELUNA=ac-eluna -CONTAINER_MODULES=ac-modules - -# Reference to core services (for external linking) -CONTAINER_WORLDSERVER=ac-worldserver - -# ============================================== -# NETWORK SETTINGS (REQUIRED) -# ============================================== -# Network must already exist from database layer -NETWORK_NAME=azerothcore - -# ============================================== -# CUSTOM MODULE SETTINGS -# ============================================== -# Module Management (1 = enabled, 0 = disabled) -MODULE_PLAYERBOTS=1 -MODULE_AOE_LOOT=0 -MODULE_LEARN_SPELLS=0 -MODULE_FIREWORKS=0 -MODULE_INDIVIDUAL_PROGRESSION=0 \ No newline at end of file diff --git a/docker-compose-azerothcore-optional.yml b/docker-compose-azerothcore-optional.yml deleted file mode 100644 index a49f72a..0000000 --- a/docker-compose-azerothcore-optional.yml +++ /dev/null @@ -1,86 +0,0 @@ -# ============================================== -# AZEROTHCORE OPTIONAL SERVICES LAYER -# ============================================== -# Modules, monitoring, and additional services -# Deploy this layer AFTER core services are running - -services: - # Optional: Eluna Lua Engine - ac-eluna: - image: ${AC_ELUNA_IMAGE} - pull_policy: ${IMAGE_PULL_POLICY} - container_name: ${CONTAINER_ELUNA} - external_links: - - ${CONTAINER_WORLDSERVER}:${CONTAINER_WORLDSERVER} - restart: unless-stopped - networks: - - azerothcore - - # Module Management Service - ac-modules: - image: ${ALPINE_GIT_IMAGE} - pull_policy: ${IMAGE_PULL_POLICY} - container_name: ${CONTAINER_MODULES} - user: "0:0" # Run as root to handle NFS permissions - volumes: - - ${STORAGE_PATH}/modules:/modules - environment: - - MODULE_PLAYERBOTS=${MODULE_PLAYERBOTS} - - MODULE_AOE_LOOT=${MODULE_AOE_LOOT} - - MODULE_LEARN_SPELLS=${MODULE_LEARN_SPELLS} - - MODULE_FIREWORKS=${MODULE_FIREWORKS} - - MODULE_INDIVIDUAL_PROGRESSION=${MODULE_INDIVIDUAL_PROGRESSION} - - DEPLOYMENT_MODE=${DEPLOYMENT_MODE} - entrypoint: ["/bin/sh", "-c"] - command: - - | - echo 'Initializing module management...' - cd /modules - - if [ "$DEPLOYMENT_MODE" = "portainer" ]; then - echo 'Simple module setup for Portainer deployment...' - mkdir -p mod-playerbots - echo '✅ Playerbot module directory created' - else - echo 'Advanced module setup for local development...' - # Install Playerbots if enabled - if [ "$MODULE_PLAYERBOTS" = "1" ] && [ ! -d "mod-playerbots" ]; then - echo 'Installing mod-playerbots...' - git clone https://github.com/liyunfan1223/mod-playerbots.git mod-playerbots - fi - - # Install AOE Loot if enabled - if [ "$MODULE_AOE_LOOT" = "1" ] && [ ! -d "mod-aoe-loot" ]; then - echo 'Installing mod-aoe-loot...' - git clone https://github.com/azerothcore/mod-aoe-loot.git mod-aoe-loot - fi - - # Install Learn Spells if enabled - if [ "$MODULE_LEARN_SPELLS" = "1" ] && [ ! -d "mod-learn-spells" ]; then - echo 'Installing mod-learn-spells...' - git clone https://github.com/azerothcore/mod-learn-spells.git mod-learn-spells - fi - - # Install Fireworks on Level if enabled - if [ "$MODULE_FIREWORKS" = "1" ] && [ ! -d "mod-fireworks-on-level" ]; then - echo 'Installing mod-fireworks-on-level...' - git clone https://github.com/azerothcore/mod-fireworks-on-level.git mod-fireworks-on-level - fi - - # Install Individual Progression if enabled - if [ "$MODULE_INDIVIDUAL_PROGRESSION" = "1" ] && [ ! -d "mod-individual-progression" ]; then - echo 'Installing mod-individual-progression...' - git clone https://github.com/azerothcore/mod-individual-progression.git mod-individual-progression - fi - fi - - echo 'Module management complete. Keeping container alive...' - tail -f /dev/null - restart: "no" - networks: - - azerothcore - -networks: - azerothcore: - external: true - name: ${NETWORK_NAME} \ No newline at end of file diff --git a/docker-compose-azerothcore-tools.yml b/docker-compose-azerothcore-tools.yml index 878cbb1..8c3453c 100644 --- a/docker-compose-azerothcore-tools.yml +++ b/docker-compose-azerothcore-tools.yml @@ -82,7 +82,7 @@ services: ports: - "${INFLUXDB_EXTERNAL_PORT:-8087}:8086" volumes: - - ${STORAGE_PATH:-./storage/azerothcore}/azerothcore/influxdb:/var/lib/influxdb2 + - ${STORAGE_PATH:-./storage/azerothcore}/influxdb:/var/lib/influxdb2 restart: unless-stopped networks: - azerothcore @@ -110,7 +110,7 @@ services: ports: - "${GF_EXTERNAL_PORT:-3001}:3000" volumes: - - ${STORAGE_PATH:-./storage/azerothcore}/azerothcore/grafana:/var/lib/grafana + - ${STORAGE_PATH:-./storage/azerothcore}/grafana:/var/lib/grafana entrypoint: ["/bin/bash", "-c"] command: - | diff --git a/docs/MODULE_COMPATIBILITY.md b/docs/MODULE_COMPATIBILITY.md deleted file mode 100644 index 6ae9952..0000000 --- a/docs/MODULE_COMPATIBILITY.md +++ /dev/null @@ -1,186 +0,0 @@ -# AzerothCore Module Compatibility Guide - -## Overview - -This document tracks the compatibility status of AzerothCore modules with the automated module management system. - -## Module Status Legend - -- ✅ **COMPATIBLE**: Module compiles and links successfully -- ⚠️ **TESTING**: Module requires testing for compatibility -- ❌ **INCOMPATIBLE**: Module has known compilation or linking issues -- 🔧 **REQUIRES_CONFIG**: Module needs configuration before compilation -- 🚨 **CRITICAL**: Module has special requirements or limitations - -## Module Compatibility Matrix - -### Core Modules (High Priority) - -| Module | Status | Notes | -|--------|--------|-------| -| mod-aoe-loot | ⚠️ | Ready for testing | -| mod-learn-spells | ⚠️ | Ready for testing | -| mod-autobalance | ⚠️ | Ready for testing | -| mod-solo-lfg | ⚠️ | Ready for testing | -| mod-transmog | ⚠️ | Ready for testing | - -### Quality of Life Modules - -| Module | Status | Notes | -|--------|--------|-------| -| mod-ahbot | ❌ | **LINKING ERROR**: `undefined reference to 'Addmod_ahbotScripts()'` | -| mod-npc-buffer | ⚠️ | Ready for testing | -| mod-dynamic-xp | ⚠️ | Ready for testing | -| mod-breaking-news-override | ⚠️ | Ready for testing | - -### Advanced Modules - -| Module | Status | Notes | -|--------|--------|-------| -| mod-playerbots | 🚨 | **CRITICAL**: Requires custom AzerothCore branch (liyunfan1223/azerothcore-wotlk/tree/Playerbot) | -| mod-individual-progression | 🔧 | Auto-configures accounts for individual progression | -| mod-1v1-arena | ⚠️ | Ready for testing | -| mod-phased-duels | ⚠️ | Ready for testing | - -### Server Management Modules - -| Module | Status | Notes | -|--------|--------|-------| -| mod-boss-announcer | ⚠️ | Ready for testing | -| mod-account-achievements | ⚠️ | Ready for testing | -| mod-eluna | ⚠️ | Lua scripting engine integration | - -### Additional Modules - -| Module | Status | Notes | -|--------|--------|-------| -| mod-auto-revive | ⚠️ | Ready for testing | -| mod-gain-honor-guard | ⚠️ | Ready for testing | -| mod-time-is-time | ⚠️ | Ready for testing | -| mod-pocket-portal | ⚠️ | Ready for testing | -| mod-random-enchants | ⚠️ | Ready for testing | -| mod-solocraft | ⚠️ | Ready for testing | -| mod-pvp-titles | ⚠️ | Ready for testing | -| mod-npc-beastmaster | ⚠️ | Ready for testing | -| mod-npc-enchanter | ⚠️ | Ready for testing | -| mod-instance-reset | ⚠️ | Ready for testing | -| mod-quest-count-level | ⚠️ | Ready for testing | - -## Known Issues - -### mod-ahbot (AuctionHouse Bot) -- **Error**: `undefined reference to 'Addmod_ahbotScripts()'` -- **Cause**: Module script loader function not properly exported -- **Solution**: - 1. Check module version compatibility with AzerothCore - 2. Update to latest module version - 3. Report issue to module maintainer -- **Workaround**: Disable module until fixed - -### mod-playerbots (Player Bots) -- **Issue**: Requires custom AzerothCore branch -- **Requirement**: `liyunfan1223/azerothcore-wotlk/tree/Playerbot` -- **Impact**: Incompatible with standard AzerothCore builds -- **Solution**: Use separate deployment for playerbot functionality - -## Testing Procedure - -### Safe Module Testing - -1. **Enable Single Module**: - ```bash - # Edit docker-compose-azerothcore-services.env - MODULE_AOE_LOOT=1 # Enable one module - ``` - -2. **Test Compilation**: - ```bash - ./scripts/rebuild-with-modules.sh - ``` - -3. **Monitor Build**: - - Watch for compilation errors - - Check for linking issues - - Verify successful completion - -4. **Test Functionality**: - - Start services - - Test module features in-game - - Check server logs for errors - -### Batch Testing (Advanced) - -1. **Enable Compatible Group**: - ```bash - # Enable related modules together - MODULE_AOE_LOOT=1 - MODULE_LEARN_SPELLS=1 - MODULE_AUTOBALANCE=1 - ``` - -2. **Document Results**: - - Update compatibility matrix - - Note any conflicts between modules - - Report issues to module maintainers - -## Module Management Best Practices - -### 1. Incremental Testing -- Enable modules one at a time initially -- Test core functionality before enabling more -- Document compatibility results - -### 2. Environment Management -- Keep baseline with all modules disabled -- Create separate environments for testing -- Use git branches for different module configurations - -### 3. Compatibility Tracking -- Update this document with test results -- Track module versions that work together -- Note AzerothCore version compatibility - -### 4. Performance Considerations -- Monitor server performance with modules enabled -- Test with realistic player loads -- Consider module interaction effects - -## Contributing - -### Reporting Issues -1. Document exact error messages -2. Include module versions and AzerothCore version -3. Provide reproduction steps -4. Submit to module maintainer and this repository - -### Updating Compatibility -1. Test modules thoroughly -2. Update status in compatibility matrix -3. Document any special requirements -4. Submit pull request with findings - -## Quick Reference - -### Enable a Module -```bash -# 1. Edit environment file -MODULE_NAME=1 - -# 2. Rebuild if needed -./scripts/rebuild-with-modules.sh - -# 3. Restart services -docker compose -f docker-compose-azerothcore-services.yml restart -``` - -### Disable All Modules (Safe State) -```bash -# All modules are currently disabled in the environment file -# This provides a stable baseline for testing -``` - -### Check Module Status -```bash -# View current module configuration -grep "^MODULE_" docker-compose-azerothcore-services.env -``` \ No newline at end of file diff --git a/docs/MODULE_MANAGEMENT.md b/docs/MODULE_MANAGEMENT.md deleted file mode 100644 index 3b4b32d..0000000 --- a/docs/MODULE_MANAGEMENT.md +++ /dev/null @@ -1,273 +0,0 @@ -# AzerothCore Module Management System - -This document describes the automated module management system for AzerothCore Docker deployments. - -## Overview - -The module management system provides: -- ✅ Automated Git-based module installation -- ✅ Automatic database script execution (SQL imports) -- ✅ Configuration file management (.conf.dist → .conf) -- ✅ Module state tracking and rebuild detection -- ✅ Comprehensive rebuild automation -- ✅ Pre-compilation configuration analysis - -## Architecture - -### Components - -1. **Module Manager Container** (`ac-modules`) - - Handles module downloading, SQL execution, and state tracking - - Runs as one-time setup during stack initialization - - Monitors module configuration changes - -2. **Rebuild Detection System** - - Tracks module enable/disable state changes - - Automatically detects when compilation is required - - Provides detailed rebuild instructions - -3. **Automated Rebuild Script** (`scripts/rebuild-with-modules.sh`) - - Orchestrates full compilation workflow - - Integrates with source-based Docker builds - - Handles module synchronization - -## Module Types - -### Pre-built Compatible -**None currently available** - All 28 analyzed modules require C++ compilation. - -### Compilation Required -All current modules require source-based compilation: -- mod-playerbots (🚨 CRITICAL: Requires custom AzerothCore branch) -- mod-aoe-loot (⚠️ Ready for testing) -- mod-learn-spells (⚠️ Ready for testing) -- mod-fireworks-on-level (⚠️ Ready for testing) -- mod-individual-progression (🔧 Auto-configures accounts) -- mod-ahbot (❌ KNOWN ISSUE: Linking error - disabled) -- All other modules (⚠️ Ready for testing) - -See `MODULE_COMPATIBILITY.md` for detailed compatibility status. - -## Configuration - -### Environment Variables - -Modules are controlled via environment variables in `docker-compose-azerothcore-services.env`: - -```bash -# Enable/disable modules (1 = enabled, 0 = disabled) -MODULE_PLAYERBOTS=1 -MODULE_AOE_LOOT=1 -MODULE_LEARN_SPELLS=1 -# ... etc -``` - -### Critical Module Requirements - -#### mod-playerbots -- **INCOMPATIBLE** with standard AzerothCore -- Requires custom branch: `liyunfan1223/azerothcore-wotlk/tree/Playerbot` -- Will not function with standard compilation - -#### mod-individual-progression -- Auto-configures new accounts for individual progression -- Requires account creation after server setup - -## Database Integration - -### Automatic SQL Execution - -The system automatically executes SQL scripts for enabled modules: - -```bash -# SQL execution locations searched: -/modules/mod-name/data/sql/world/*.sql → acore_world database -/modules/mod-name/data/sql/auth/*.sql → acore_auth database -/modules/mod-name/data/sql/characters/*.sql → acore_characters database -/modules/mod-name/data/sql/*.sql → acore_world database (fallback) -/modules/mod-name/sql/*.sql → acore_world database (alternative) -``` - -### Error Handling - -- ✅ Uses proper MySQL client with SSL verification disabled -- ✅ Implements exit code checking (not stderr redirection) -- ✅ Provides detailed success/failure feedback -- ✅ Continues processing if optional scripts fail - -## Rebuild System - -### Detection Logic - -1. **Module State Tracking** - - Creates hash of all module enable/disable states - - Stores in `/modules/.modules_state` - - Compares current vs previous state on each run - -2. **Change Detection** - ```bash - # First run - 📝 First run - establishing module state baseline - - # No changes - ✅ No module changes detected - - # Changes detected - 🔄 Module configuration has changed - rebuild required - ``` - -### Rebuild Requirements - -When modules are enabled, the system provides: - -```bash -🚨 REBUILD REQUIRED 🚨 -Module configuration has changed. To integrate C++ modules into AzerothCore: - -1. Stop current services: - docker compose -f docker-compose-azerothcore-services.yml down - -2. Build with source-based compilation: - docker compose -f /tmp/acore-dev-test/docker-compose.yml build - docker compose -f /tmp/acore-dev-test/docker-compose.yml up -d - -3. Or use the automated rebuild script (if available): - ./scripts/rebuild-with-modules.sh -``` - -### Automated Rebuild Script - -The `rebuild-with-modules.sh` script provides: - -1. **Pre-flight Checks** - - Verifies source repository availability - - Counts enabled modules - - Confirms rebuild necessity - -2. **Build Process** - - Stops current services - - Syncs modules to source build - - Executes `docker compose build --no-cache` - - Starts services with compiled modules - -3. **Error Handling** - - Build failure detection - - Service startup verification - - Detailed status reporting - -## Usage Examples - -### Enable New Module - -1. Edit `docker-compose-azerothcore-services.env`: - ```bash - MODULE_TRANSMOG=1 - ``` - -2. Restart module manager: - ```bash - docker compose -f docker-compose-azerothcore-services.yml up ac-modules - ``` - -3. Follow rebuild instructions or run: - ```bash - ./scripts/rebuild-with-modules.sh - ``` - -### Disable Module - -1. Edit environment file: - ```bash - MODULE_TRANSMOG=0 - ``` - -2. Restart and rebuild (module code will be removed from compilation) - -### Bulk Module Management - -Enable multiple modules simultaneously: -```bash -# Edit .env file with multiple changes -MODULE_AUTOBALANCE=1 -MODULE_TRANSMOG=1 -MODULE_SOLO_LFG=1 - -# Single rebuild handles all changes -./scripts/rebuild-with-modules.sh -``` - -## Troubleshooting - -### Common Issues - -1. **SQL Execution Failures** - - Check MySQL container health - - Verify database credentials - - Review specific SQL script syntax - -2. **Build Failures** - - Ensure adequate disk space (>10GB recommended) - - Check module compatibility - - Review Docker build logs - -3. **Module Not Loading** - - Verify module appears in compilation output - - Check worldserver logs for load errors - - Confirm configuration files copied correctly - -### Performance Considerations - -- **Build Time**: 15-45 minutes depending on system performance -- **Storage**: Source builds require ~5-10GB additional space -- **Memory**: Compilation may require 4GB+ RAM -- **CPU**: Multi-core systems significantly faster - -## Technical Implementation - -### Module Installation Flow - -``` -1. Environment Variable Check → Module Enabled? - ↓ -2. Git Clone/Pull → Download Latest Module Source - ↓ -3. SQL Script Discovery → Find Database Scripts - ↓ -4. Database Connection → Execute Scripts with Error Handling - ↓ -5. Configuration Files → Copy .conf.dist to .conf - ↓ -6. State Tracking → Update Module State Hash - ↓ -7. Rebuild Detection → Compare Previous vs Current State - ↓ -8. User Notification → Provide Rebuild Instructions -``` - -### Database Script Execution - -```sql --- Example execution pattern: -mysql --skip-ssl-verify -h ac-database -P 3306 -u root -p"password" acore_world < module.sql - --- Success detection via exit codes: -if [ $? -eq 0 ]; then - echo "✅ Successfully executed $(basename $sql_file)" -else - echo "❌ Failed to execute $sql_file" -fi -``` - -## Future Enhancements - -- [ ] Support for pure configuration modules (no compilation) -- [ ] Module dependency resolution -- [ ] Incremental compilation for faster rebuilds -- [ ] Integration with CI/CD pipelines -- [ ] Module version management and rollback -- [ ] Health checks for module functionality - -## Support - -For issues with specific modules, refer to their individual GitHub repositories. -For system-level issues, check Docker Compose logs and module manager output. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 2bd43b0..0000000 --- a/docs/README.md +++ /dev/null @@ -1,98 +0,0 @@ -# AzerothCore Module Management Documentation - -This directory contains comprehensive documentation for the AzerothCore automated module management system. - -## Documentation Overview - -### 📖 [MODULE_MANAGEMENT.md](MODULE_MANAGEMENT.md) -**Complete system guide** covering: -- Architecture overview and components -- Module installation and configuration -- Database integration and SQL execution -- Rebuild detection and automation -- Usage examples and troubleshooting - -### 📋 [MODULE_COMPATIBILITY.md](MODULE_COMPATIBILITY.md) -**Module compatibility matrix** including: -- Status of all 28 analyzed modules -- Known issues and compatibility notes -- Testing procedures and best practices -- Troubleshooting guide for specific modules - -## Quick Start - -### 1. Enable a Module -```bash -# Edit environment file -vim docker-compose-azerothcore-services.env -# Set MODULE_NAME=1 - -# Rebuild if C++ compilation required -./scripts/rebuild-with-modules.sh - -# Restart services -docker compose -f docker-compose-azerothcore-services.yml restart -``` - -### 2. Check Module Status -```bash -# View current configuration -grep "^MODULE_" docker-compose-azerothcore-services.env - -# Check for rebuild requirements -docker compose -f docker-compose-azerothcore-services.yml up ac-modules -``` - -### 3. Safe Testing Approach -1. Start with all modules disabled (current state) -2. Enable one module at a time -3. Test compilation and functionality -4. Document results in compatibility matrix - -## Directory Structure - -``` -docs/ -├── README.md # This overview file -├── MODULE_MANAGEMENT.md # Complete system documentation -└── MODULE_COMPATIBILITY.md # Module compatibility matrix - -scripts/ -└── rebuild-with-modules.sh # Automated rebuild script - -docker-compose-azerothcore-services.yml # Main service configuration -docker-compose-azerothcore-services.env # Module configuration -``` - -## System Features - -- ✅ **Automatic Module Detection**: Downloads and analyzes all available modules -- ✅ **State Tracking**: Hash-based change detection triggers rebuilds automatically -- ✅ **SQL Integration**: Executes module database scripts automatically -- ✅ **Configuration Management**: Handles .conf file setup -- ✅ **Rebuild Automation**: Complete source-based compilation workflow -- ✅ **Compatibility Analysis**: Documents module requirements and issues - -## Support - -### For Module-Specific Issues -- Check the compatibility matrix in `MODULE_COMPATIBILITY.md` -- Refer to individual module GitHub repositories -- Test modules incrementally - -### For System Issues -- Review `MODULE_MANAGEMENT.md` troubleshooting section -- Check Docker logs: `docker compose logs ac-modules` -- Verify environment configuration - -## Contributing - -When testing modules: -1. Update compatibility status in `MODULE_COMPATIBILITY.md` -2. Document any special requirements or configuration -3. Report issues to module maintainers -4. Submit pull requests with compatibility findings - ---- - -**Note**: All modules are currently disabled for a stable baseline. Enable and test modules individually to ensure compatibility with your specific AzerothCore setup. \ No newline at end of file diff --git a/readme.md b/readme.md index 0d305b7..9af8247 100644 --- a/readme.md +++ b/readme.md @@ -81,62 +81,97 @@ This project provides a production-ready AzerothCore deployment using Docker/Pod This deployment includes a **comprehensive automated module management system** that supports 28 AzerothCore modules with: -- ✅ **Automatic module installation and removal** +- ✅ **Automatic Git-based module installation** - ✅ **State tracking with rebuild detection** - ✅ **SQL script execution for database setup** -- ✅ **Configuration file management** +- ✅ **Configuration file management (.conf.dist → .conf)** - ✅ **Source-based compilation integration** +- ✅ **Hash-based change detection triggers rebuilds automatically** - ✅ **Compatibility analysis and documentation** All modules are automatically downloaded from GitHub when enabled and include proper configuration files. +### Module Management Architecture + +The system consists of three key components: + +1. **Module Manager Container** (`ac-modules`) + - Handles module downloading, SQL execution, and state tracking + - Runs as one-time setup during stack initialization + - Monitors module configuration changes + +2. **Rebuild Detection System** + - Tracks module enable/disable state changes + - Automatically detects when compilation is required + - Provides detailed rebuild instructions + +3. **Automated Rebuild Script** (`scripts/rebuild-with-modules.sh`) + - Orchestrates full compilation workflow + - Integrates with source-based Docker builds + - Handles module synchronization + +### Module Status Legend + +- ✅ **COMPATIBLE**: Module compiles and links successfully +- ⚠️ **TESTING**: Module requires testing for compatibility +- ❌ **INCOMPATIBLE**: Module has known compilation or linking issues +- 🔧 **REQUIRES_CONFIG**: Module needs configuration before compilation +- 🚨 **CRITICAL**: Module has special requirements or limitations + +**Important**: All 28 analyzed modules require C++ compilation - none are compatible with pre-built containers. + +### Core Modules (High Priority) + +| Module | Status | Description | Repository | README | +|--------|--------|-------------|------------|--------| +| **AoE Loot** | ⚠️ | Area of effect looting feature | [mod-aoe-loot](https://github.com/azerothcore/mod-aoe-loot) | [📖](https://github.com/azerothcore/mod-aoe-loot/blob/master/.github/README.md) | +| **Learn Spells** | ⚠️ | Automatic spell learning | [mod-learn-spells](https://github.com/azerothcore/mod-learn-spells) | [📖](https://github.com/azerothcore/mod-learn-spells/blob/master/README.md) | +| **AutoBalance** | ⚠️ | Dynamic difficulty scaling for dungeons/raids | [mod-autobalance](https://github.com/azerothcore/mod-autobalance) | [📖](https://github.com/azerothcore/mod-autobalance/blob/master/README.md) | +| **Solo LFG** | ⚠️ | Solo dungeon finder system | [mod-solo-lfg](https://github.com/azerothcore/mod-solo-lfg) | [📖](https://github.com/azerothcore/mod-solo-lfg/blob/master/README.md) | +| **Transmog** | ⚠️ | Transmogrification system | [mod-transmog](https://github.com/azerothcore/mod-transmog) | [📖](https://github.com/azerothcore/mod-transmog/blob/master/README.md) | + ### Quality of Life Modules -| Module | Description | Repository | README | Post-Install Notes | -|--------|-------------|------------|--------|-------------------| -| **AutoBalance** | Dynamic difficulty scaling for dungeons/raids | [mod-autobalance](https://github.com/azerothcore/mod-autobalance) | [📖](https://github.com/azerothcore/mod-autobalance/blob/master/README.md) | Requires AutoBalance.conf configuration | -| **AHBot** | Auction House bot for populated auctions | [mod-ahbot](https://github.com/azerothcore/mod-ahbot) | [📖](https://github.com/azerothcore/mod-ahbot/blob/master/README.md) | Requires mod_ahbot.conf configuration | -| **Transmog** | Transmogrification system | [mod-transmog](https://github.com/azerothcore/mod-transmog) | [📖](https://github.com/azerothcore/mod-transmog/blob/master/README.md) | Requires transmog.conf configuration | -| **NPC Buffer** | Buff NPC services | [mod-npc-buffer](https://github.com/azerothcore/mod-npc-buffer) | [📖](https://github.com/azerothcore/mod-npc-buffer/blob/master/README.md) | Requires npc_buffer.conf configuration | -| **AoE Loot** | Area of effect looting feature | [mod-aoe-loot](https://github.com/azerothcore/mod-aoe-loot) | [📖](https://github.com/azerothcore/mod-aoe-loot/blob/master/.github/README.md) | No additional configuration required | -| **Learn Spells** | Automatic spell learning | [mod-learn-spells](https://github.com/azerothcore/mod-learn-spells) | [📖](https://github.com/azerothcore/mod-learn-spells/blob/master/README.md) | Requires mod_learnspells.conf configuration | -| **Auto Revive** | Auto-revive functionality for GMs | [mod-auto-revive](https://github.com/azerothcore/mod-auto-revive) | [📖](https://github.com/azerothcore/mod-auto-revive/blob/master/README.md) | Requires AutoRevive.conf configuration | -| **NPC Enchanter** | NPC-based gear enchantment services | [mod-npc-enchanter](https://github.com/azerothcore/mod-npc-enchanter) | [📖](https://github.com/azerothcore/mod-npc-enchanter/blob/master/README.md) | Requires npc_enchanter.conf configuration | -| **Instance Reset** | NPC-based instance reset functionality | [mod-instance-reset](https://github.com/azerothcore/mod-instance-reset) | [📖](https://github.com/azerothcore/mod-instance-reset/blob/master/README.md) | Requires instance-reset.conf configuration | +| Module | Status | Description | Repository | README | +|--------|--------|-------------|------------|--------| +| **AHBot** | ❌ | Auction House bot for populated auctions - **LINKING ERROR** | [mod-ahbot](https://github.com/azerothcore/mod-ahbot) | [📖](https://github.com/azerothcore/mod-ahbot/blob/master/README.md) | +| **NPC Buffer** | ⚠️ | Buff NPC services | [mod-npc-buffer](https://github.com/azerothcore/mod-npc-buffer) | [📖](https://github.com/azerothcore/mod-npc-buffer/blob/master/README.md) | +| **Dynamic XP** | ⚠️ | Configurable experience rates | [mod-dynamic-xp](https://github.com/azerothcore/mod-dynamic-xp) | [📖](https://github.com/azerothcore/mod-dynamic-xp/blob/master/README.md) | +| **Breaking News** | ⚠️ | Server announcement system | [mod-breaking-news-override](https://github.com/azerothcore/mod-breaking-news-override) | [📖](https://github.com/azerothcore/mod-breaking-news-override/blob/master/README.md) | +| **Auto Revive** | ⚠️ | Auto-revive functionality for GMs | [mod-auto-revive](https://github.com/azerothcore/mod-auto-revive) | [📖](https://github.com/azerothcore/mod-auto-revive/blob/master/README.md) | +| **NPC Enchanter** | ⚠️ | NPC-based gear enchantment services | [mod-npc-enchanter](https://github.com/azerothcore/mod-npc-enchanter) | [📖](https://github.com/azerothcore/mod-npc-enchanter/blob/master/README.md) | +| **Instance Reset** | ⚠️ | NPC-based instance reset functionality | [mod-instance-reset](https://github.com/azerothcore/mod-instance-reset) | [📖](https://github.com/azerothcore/mod-instance-reset/blob/master/README.md) | -### Gameplay Enhancement Modules +### Advanced Modules -| Module | Description | Repository | README | Post-Install Notes | -|--------|-------------|------------|--------|-------------------| -| **Individual Progression** | Custom character progression system | [mod-individual-progression](https://github.com/ZhengPeiRu21/mod-individual-progression) | [📖](https://github.com/ZhengPeiRu21/mod-individual-progression/blob/master/README.md) | Complex SQL imports required | -| **Dynamic XP** | Configurable experience rates | [mod-dynamic-xp](https://github.com/azerothcore/mod-dynamic-xp) | [📖](https://github.com/azerothcore/mod-dynamic-xp/blob/master/README.md) | Requires Individual-XP.conf configuration | -| **Solo LFG** | Solo dungeon finder system | [mod-solo-lfg](https://github.com/azerothcore/mod-solo-lfg) | [📖](https://github.com/azerothcore/mod-solo-lfg/blob/master/README.md) | Requires SoloLfg.conf configuration | -| **1v1 Arena** | Arena combat system | [mod-1v1-arena](https://github.com/azerothcore/mod-1v1-arena) | [📖](https://github.com/azerothcore/mod-1v1-arena/blob/master/README.md) | Database tables auto-created | -| **Phased Duels** | Isolated dueling system | [mod-phased-duels](https://github.com/azerothcore/mod-phased-duels) | [📖](https://github.com/azerothcore/mod-phased-duels/blob/master/README.md) | No additional configuration required | -| **Solocraft** | Solo dungeon scaling | [mod-solocraft](https://github.com/azerothcore/mod-solocraft) | [📖](https://github.com/azerothcore/mod-solocraft/blob/master/.github/README.md) | Requires Solocraft.conf configuration | -| **Random Enchants** | Random item enchantments | [mod-random-enchants](https://github.com/azerothcore/mod-random-enchants) | [📖](https://github.com/azerothcore/mod-random-enchants/blob/master/README.md) | Requires RandomEnchants.conf configuration | -| **Level Grant** | Quest-based level granting | [mod-quest-count-level](https://github.com/michaeldelago/mod-quest-count-level) | [📖](https://github.com/michaeldelago/mod-quest-count-level/blob/main/README.md) | Requires levelGrant.conf configuration | +| Module | Status | Description | Repository | README | +|--------|--------|-------------|------------|--------| +| **Playerbots** | 🚨 | AI-controlled bot system - **REQUIRES CUSTOM BRANCH** | [mod-playerbots](https://github.com/liyunfan1223/mod-playerbots) | [📖](https://github.com/liyunfan1223/mod-playerbots/blob/master/README.md) | +| **Individual Progression** | 🔧 | Custom character progression system | [mod-individual-progression](https://github.com/ZhengPeiRu21/mod-individual-progression) | [📖](https://github.com/ZhengPeiRu21/mod-individual-progression/blob/master/README.md) | +| **1v1 Arena** | ⚠️ | Arena combat system | [mod-1v1-arena](https://github.com/azerothcore/mod-1v1-arena) | [📖](https://github.com/azerothcore/mod-1v1-arena/blob/master/README.md) | +| **Phased Duels** | ⚠️ | Isolated dueling system | [mod-phased-duels](https://github.com/azerothcore/mod-phased-duels) | [📖](https://github.com/azerothcore/mod-phased-duels/blob/master/README.md) | +| **Solocraft** | ⚠️ | Solo dungeon scaling | [mod-solocraft](https://github.com/azerothcore/mod-solocraft) | [📖](https://github.com/azerothcore/mod-solocraft/blob/master/.github/README.md) | +| **Random Enchants** | ⚠️ | Random item enchantments | [mod-random-enchants](https://github.com/azerothcore/mod-random-enchants) | [📖](https://github.com/azerothcore/mod-random-enchants/blob/master/README.md) | ### Server Management Modules -| Module | Description | Repository | README | Post-Install Notes | -|--------|-------------|------------|--------|-------------------| -| **Breaking News Override** | Server announcement system | [mod-breaking-news-override](https://github.com/azerothcore/mod-breaking-news-override) | [📖](https://github.com/azerothcore/mod-breaking-news-override/blob/master/README.md) | No additional configuration required | -| **Boss Announcer** | Raid boss kill notifications | [mod-boss-announcer](https://github.com/azerothcore/mod-boss-announcer) | [📖](https://github.com/azerothcore/mod-boss-announcer/blob/master/README.md) | No additional configuration required | -| **Account Achievements** | Cross-character achievements | [mod-account-achievements](https://github.com/azerothcore/mod-account-achievements) | [📖](https://github.com/azerothcore/mod-account-achievements/blob/master/README.md) | Database tables auto-created | -| **Gain Honor Guard** | Honor system for killing guards | [mod-gain-honor-guard](https://github.com/azerothcore/mod-gain-honor-guard) | [📖](https://github.com/azerothcore/mod-gain-honor-guard/blob/master/.github/README.md) | Requires GainHonorGuard.conf configuration | -| **PvP Titles** | Honor-based PvP title system | [mod-pvp-titles](https://github.com/azerothcore/mod-pvp-titles) | [📖](https://github.com/azerothcore/mod-pvp-titles/blob/master/README.md) | Requires mod_pvptitles.conf configuration | -| **Pocket Portal** | Teleportation portal system | [mod-pocket-portal](https://github.com/azerothcore/mod-pocket-portal) | [📖](https://github.com/azerothcore/mod-pocket-portal/blob/master/README.md) | Requires pocketportal.conf configuration | +| Module | Status | Description | Repository | README | +|--------|--------|-------------|------------|--------| +| **Boss Announcer** | ⚠️ | Raid boss kill notifications | [mod-boss-announcer](https://github.com/azerothcore/mod-boss-announcer) | [📖](https://github.com/azerothcore/mod-boss-announcer/blob/master/README.md) | +| **Account Achievements** | ⚠️ | Cross-character achievements | [mod-account-achievements](https://github.com/azerothcore/mod-account-achievements) | [📖](https://github.com/azerothcore/mod-account-achievements/blob/master/README.md) | +| **Eluna** | ⚠️ | Lua scripting engine integration | [mod-eluna](https://github.com/azerothcore/mod-eluna) | [📖](https://github.com/azerothcore/mod-eluna/blob/master/README.md) | +| **Gain Honor Guard** | ⚠️ | Honor system for killing guards | [mod-gain-honor-guard](https://github.com/azerothcore/mod-gain-honor-guard) | [📖](https://github.com/azerothcore/mod-gain-honor-guard/blob/master/.github/README.md) | +| **PvP Titles** | ⚠️ | Honor-based PvP title system | [mod-pvp-titles](https://github.com/azerothcore/mod-pvp-titles) | [📖](https://github.com/azerothcore/mod-pvp-titles/blob/master/README.md) | +| **Pocket Portal** | ⚠️ | Teleportation portal system | [mod-pocket-portal](https://github.com/azerothcore/mod-pocket-portal) | [📖](https://github.com/azerothcore/mod-pocket-portal/blob/master/README.md) | -### Core System Modules +### Additional Modules -| Module | Description | Repository | README | Post-Install Notes | -|--------|-------------|------------|--------|-------------------| -| **Playerbots** | AI-controlled bot system | [mod-playerbots](https://github.com/liyunfan1223/mod-playerbots) | [📖](https://github.com/liyunfan1223/mod-playerbots/blob/master/README.md) | Enabled by default, extensive configuration | -| **Fireworks** | Fireworks on level up | [mod-fireworks-on-level](https://github.com/azerothcore/mod-fireworks-on-level) | [📖](https://github.com/azerothcore/mod-fireworks-on-level/blob/master/README.md) | No additional configuration required | -| **Eluna** | Lua scripting engine | [mod-eluna](https://github.com/azerothcore/mod-eluna) | [📖](https://github.com/azerothcore/mod-eluna/blob/master/README.md) | Requires mod_LuaEngine.conf configuration | -| **Time Is Time** | Realistic day/night cycle | [mod-TimeIsTime](https://github.com/dunjeon/mod-TimeIsTime) | [📖](https://github.com/dunjeon/mod-TimeIsTime/blob/main/README.md) | Requires mod-time_is_time.conf configuration | -| **NPC Beastmaster** | Cross-class pet system | [mod-npc-beastmaster](https://github.com/azerothcore/mod-npc-beastmaster) | [📖](https://github.com/azerothcore/mod-npc-beastmaster/blob/master/README.md) | Requires npc_beastmaster.conf configuration | +| Module | Status | Description | Repository | README | +|--------|--------|-------------|------------|--------| +| **Time Is Time** | ⚠️ | Realistic day/night cycle | [mod-TimeIsTime](https://github.com/dunjeon/mod-TimeIsTime) | [📖](https://github.com/dunjeon/mod-TimeIsTime/blob/main/README.md) | +| **NPC Beastmaster** | ⚠️ | Cross-class pet system | [mod-npc-beastmaster](https://github.com/azerothcore/mod-npc-beastmaster) | [📖](https://github.com/azerothcore/mod-npc-beastmaster/blob/master/README.md) | +| **Fireworks** | ⚠️ | Fireworks on level up | [mod-fireworks-on-level](https://github.com/azerothcore/mod-fireworks-on-level) | [📖](https://github.com/azerothcore/mod-fireworks-on-level/blob/master/README.md) | +| **Level Grant** | ⚠️ | Quest-based level granting | [mod-quest-count-level](https://github.com/michaeldelago/mod-quest-count-level) | [📖](https://github.com/michaeldelago/mod-quest-count-level/blob/main/README.md) | ### Module Configuration @@ -149,39 +184,88 @@ MODULE_TRANSMOG=1 ``` After enabling/disabling modules: -1. Restart the module container: `docker-compose up -d ac-modules` +1. Run the module manager: `docker compose -f docker-compose-azerothcore-services.yml up ac-modules` 2. **Enabled modules** will be automatically downloaded to `storage/azerothcore/modules/` 3. **Disabled modules** will be automatically removed from the modules directory 4. **Configuration files** (`.conf.dist`) are automatically managed: - **Enabled modules**: Config files copied to `storage/azerothcore/config/` - **Disabled modules**: Config files removed from config directory -5. **Important**: Modules require server recompilation to be active -6. Some modules require database imports (check individual module README files) +5. **SQL scripts** are automatically executed for database setup +6. **Important**: All modules require server recompilation to be active - use `./scripts/rebuild-with-modules.sh` + +### Safe Module Testing Procedure + +1. **Enable Single Module**: + ```bash + # Edit docker-compose-azerothcore-services.env + MODULE_AOE_LOOT=1 # Enable one module + ``` + +2. **Test Compilation**: + ```bash + ./scripts/rebuild-with-modules.sh + ``` + +3. **Monitor Build**: + - Watch for compilation errors + - Check for linking issues + - Verify successful completion + +4. **Test Functionality**: + - Start services + - Test module features in-game + - Check server logs for errors ### Module Management Behavior The module management system provides complete automation: - **Enable Module** (`MODULE_NAME=1`): - - Downloads module source code if not present + - Downloads module source code via Git if not present - Copies `.conf.dist` files to config directory + - Executes SQL scripts for database setup + - Updates module state tracking for rebuild detection - **Disable Module** (`MODULE_NAME=0`): - Removes module directory completely - Removes associated configuration files + - Updates state hash to trigger rebuild detection - **Module Persistence**: Only enabled modules and their configs remain - **Clean Slate**: Disabling and re-enabling ensures fresh download and config -- **Zero Manual Setup**: No need to manually copy configuration files +- **Zero Manual Setup**: No need to manually copy configuration files or run SQL scripts + +### Known Issues and Limitations + +#### ❌ mod-ahbot (AuctionHouse Bot) +- **Error**: `undefined reference to 'Addmod_ahbotScripts()'` +- **Cause**: Module script loader function not properly exported +- **Status**: Disabled by default until fixed +- **Workaround**: Report issue to module maintainer + +#### 🚨 mod-playerbots (Player Bots) +- **Issue**: Requires custom AzerothCore branch +- **Requirement**: `liyunfan1223/azerothcore-wotlk/tree/Playerbot` +- **Impact**: Incompatible with standard AzerothCore builds +- **Solution**: Use separate deployment for playerbot functionality + +#### 🔧 mod-individual-progression +- **Note**: Auto-configures accounts for individual progression +- **Requirement**: Account creation after server setup ### Post-Installation Requirements -⚠️ **Critical**: Most modules require additional steps after download: +⚠️ **Critical**: All modules require source-based compilation: -1. **Server Recompilation**: Modules need to be compiled into the server -2. **Configuration Files**: Copy `.conf` files to config directory -3. **Database Imports**: Some modules include SQL files for database schema -4. **Module-Specific Setup**: Check each module's README for specific requirements +1. **Server Recompilation**: All modules need C++ compilation - use `./scripts/rebuild-with-modules.sh` +2. **Module State Tracking**: System automatically detects when rebuilds are required +3. **Rebuild Detection**: Hash-based change detection triggers rebuild notifications +4. **Database Integration**: SQL scripts are executed automatically during module installation -See the [AzerothCore Module Documentation](https://www.azerothcore.org/wiki/installing-a-module) for complete installation procedures. +### Module Documentation + +For detailed module management documentation, see: +- **Complete System Guide**: [docs/MODULE_MANAGEMENT.md](docs/MODULE_MANAGEMENT.md) +- **Compatibility Matrix**: [docs/MODULE_COMPATIBILITY.md](docs/MODULE_COMPATIBILITY.md) +- **Quick Start Guide**: [docs/README.md](docs/README.md) ## Requirements @@ -314,7 +398,21 @@ No manual data extraction is required, but ensure you have sufficient disk space docker compose --env-file docker-compose-azerothcore-tools.env -f docker-compose-azerothcore-tools.yml up -d ``` -### Step 3: Create Admin Account +### Step 3: Run Post-Installation Configuration + +Configure the server with production database settings and realm information: + +```bash +# Run automated post-installation setup +./scripts/post-install-setup.sh + +# This script will: +# 1. Update .conf files with production database settings +# 2. Update realmlist table with server address and port +# 3. Restart services to apply changes +``` + +### Step 4: Create Admin Account Once the worldserver is running: @@ -330,7 +428,7 @@ server info # Detach from console without stopping: Ctrl+P, Ctrl+Q ``` -### Step 4: Configure Game Client +### Step 5: Configure Game Client Edit your WoW 3.3.5a client's `realmlist.wtf`: ``` @@ -719,6 +817,10 @@ The `scripts/` directory contains automation tools for deployment, health checki | `cleanup.sh` | Multi-level resource cleanup | `./cleanup.sh [--soft\|--hard\|--nuclear] [--dry-run]` | | `backup.sh` | Manual database backup | `./backup.sh` | | `restore.sh` | Database restoration | `./restore.sh ` | +| `post-install-setup.sh` | Complete automated post-installation configuration | `./post-install-setup.sh` | +| `update-config.sh` | Update .conf files with production database settings | `./update-config.sh` | +| `update-realmlist.sh` | Update realmlist table with server address and port | `./update-realmlist.sh` | +| `rebuild-with-modules.sh` | Automated module compilation and rebuild | `./rebuild-with-modules.sh` | ### Deployment and Health Check Script