nchebrov/AzerothCore-RealmMaster
1
0
Fork 0
mirror of https://github.com/uprightbass360/AzerothCore-RealmMaster.git synced 2026-01-13 00:58:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Organization and docs

Browse Source
This commit is contained in:
uprightbass360
2025-10-02 00:41:14 -04:00
parent ba541fbf78
commit 80af54180f
8 changed files with 165 additions and 759 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docker-compose-azerothcore-database.env
View File

@@ -1,5 +1,11 @@
# AZEROTHCORE DATABASE LAYER ENVIRONMENT # 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 # SERVER CONFIGURATION
# Timezone # Timezone
TZ=UTC TZ=UTC
@@ -50,12 +56,6 @@ MYSQL_HEALTHCHECK_START_PERIOD=120s
# External database port # External database port
MYSQL_EXTERNAL_PORT=64306 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 # CONTAINER NAMES
# Database layer container names # Database layer container names
CONTAINER_MYSQL=ac-mysql CONTAINER_MYSQL=ac-mysql
@@ -70,8 +70,8 @@ NETWORK_GATEWAY=172.20.0.1
# BACKUP CONFIGURATION # BACKUP CONFIGURATION
# Host volume paths for backup # Host volume paths for backup
HOST_BACKUP_PATH=./backups HOST_BACKUP_PATH=${STORAGE_PATH}/backups
HOST_BACKUP_SCRIPTS_PATH=./scripts HOST_BACKUP_SCRIPTS_PATH=${STORAGE_PATH}/scripts
# Backup settings # Backup settings
BACKUP_CRON_SCHEDULE="0 3 * * *" BACKUP_CRON_SCHEDULE="0 3 * * *"

53
docker-compose-azerothcore-optional.env
View File

@@ -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

86
docker-compose-azerothcore-optional.yml
View File

@@ -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}

4
docker-compose-azerothcore-tools.yml
View File

@@ -82,7 +82,7 @@ services:
ports: ports:
- "${INFLUXDB_EXTERNAL_PORT:-8087}:8086" - "${INFLUXDB_EXTERNAL_PORT:-8087}:8086"
volumes: volumes:
- ${STORAGE_PATH:-./storage/azerothcore}/azerothcore/influxdb:/var/lib/influxdb2 - ${STORAGE_PATH:-./storage/azerothcore}/influxdb:/var/lib/influxdb2
restart: unless-stopped restart: unless-stopped
networks: networks:
- azerothcore - azerothcore
@@ -110,7 +110,7 @@ services:
ports: ports:
- "${GF_EXTERNAL_PORT:-3001}:3000" - "${GF_EXTERNAL_PORT:-3001}:3000"
volumes: volumes:
- ${STORAGE_PATH:-./storage/azerothcore}/azerothcore/grafana:/var/lib/grafana - ${STORAGE_PATH:-./storage/azerothcore}/grafana:/var/lib/grafana
entrypoint: ["/bin/bash", "-c"] entrypoint: ["/bin/bash", "-c"]
command: command:
- | - |

186
docs/MODULE_COMPATIBILITY.md
View File

@@ -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
```

273
docs/MODULE_MANAGEMENT.md
View File

@@ -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.

98
docs/README.md
View File

@@ -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.

208
readme.md
View File

@@ -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: 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** - ✅ **State tracking with rebuild detection**
- ✅ **SQL script execution for database setup** - ✅ **SQL script execution for database setup**
- ✅ **Configuration file management** - ✅ **Configuration file management (.conf.dist → .conf)**
- ✅ **Source-based compilation integration** - ✅ **Source-based compilation integration**
- ✅ **Hash-based change detection triggers rebuilds automatically**
- ✅ **Compatibility analysis and documentation** - ✅ **Compatibility analysis and documentation**
All modules are automatically downloaded from GitHub when enabled and include proper configuration files. 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 ### Quality of Life Modules
| Module | Description | Repository | README | Post-Install Notes | | Module | Status | Description | Repository | README |
|--------|-------------|------------|--------|-------------------| |--------|--------|-------------|------------|--------|
| **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 - **LINKING ERROR** | [mod-ahbot](https://github.com/azerothcore/mod-ahbot) | [📖](https://github.com/azerothcore/mod-ahbot/blob/master/README.md) |
| **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 | | **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) |
| **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 | | **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) |
| **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 | | **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) |
| **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 | | **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) |
| **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 | | **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) |
| **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 | | **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) |
| **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 |
### Gameplay Enhancement Modules ### Advanced Modules
| Module | Description | Repository | README | Post-Install Notes | | Module | Status | Description | Repository | README |
|--------|-------------|------------|--------|-------------------| |--------|--------|-------------|------------|--------|
| **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 | | **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) |
| **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 | | **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) |
| **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) |
| **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) |
| **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) |
| **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) |
| **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 |
### Server Management Modules ### Server Management Modules
| Module | Description | Repository | README | Post-Install Notes | | Module | Status | Description | Repository | README |
|--------|-------------|------------|--------|-------------------| |--------|--------|-------------|------------|--------|
| **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) |
| **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) |
| **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 | | **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) | Requires GainHonorGuard.conf configuration | | **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) | Requires mod_pvptitles.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) |
| **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 | | **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 | | Module | Status | Description | Repository | README |
|--------|-------------|------------|--------|-------------------| |--------|--------|-------------|------------|--------|
| **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 | | **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) |
| **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 | | **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) |
| **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 | | **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) |
| **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 | | **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) |
| **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 Configuration ### Module Configuration
@@ -149,39 +184,88 @@ MODULE_TRANSMOG=1
``` ```
After enabling/disabling modules: 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/` 2. **Enabled modules** will be automatically downloaded to `storage/azerothcore/modules/`
3. **Disabled modules** will be automatically removed from the modules directory 3. **Disabled modules** will be automatically removed from the modules directory
4. **Configuration files** (`.conf.dist`) are automatically managed: 4. **Configuration files** (`.conf.dist`) are automatically managed:
- **Enabled modules**: Config files copied to `storage/azerothcore/config/` - **Enabled modules**: Config files copied to `storage/azerothcore/config/`
- **Disabled modules**: Config files removed from config directory - **Disabled modules**: Config files removed from config directory
5. **Important**: Modules require server recompilation to be active 5. **SQL scripts** are automatically executed for database setup
6. Some modules require database imports (check individual module README files) 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 ### Module Management Behavior
The module management system provides complete automation: The module management system provides complete automation:
- **Enable Module** (`MODULE_NAME=1`): - **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 - 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`): - **Disable Module** (`MODULE_NAME=0`):
- Removes module directory completely - Removes module directory completely
- Removes associated configuration files - Removes associated configuration files
- Updates state hash to trigger rebuild detection
- **Module Persistence**: Only enabled modules and their configs remain - **Module Persistence**: Only enabled modules and their configs remain
- **Clean Slate**: Disabling and re-enabling ensures fresh download and config - **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 ### 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 1. **Server Recompilation**: All modules need C++ compilation - use `./scripts/rebuild-with-modules.sh`
2. **Configuration Files**: Copy `.conf` files to config directory 2. **Module State Tracking**: System automatically detects when rebuilds are required
3. **Database Imports**: Some modules include SQL files for database schema 3. **Rebuild Detection**: Hash-based change detection triggers rebuild notifications
4. **Module-Specific Setup**: Check each module's README for specific requirements 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 ## 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 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: Once the worldserver is running:
@@ -330,7 +428,7 @@ server info
# Detach from console without stopping: Ctrl+P, Ctrl+Q # 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`: 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]` | | `cleanup.sh` | Multi-level resource cleanup | `./cleanup.sh [--soft\|--hard\|--nuclear] [--dry-run]` |
| `backup.sh` | Manual database backup | `./backup.sh` | | `backup.sh` | Manual database backup | `./backup.sh` |
| `restore.sh` | Database restoration | `./restore.sh <backup_directory>` | | `restore.sh` | Database restoration | `./restore.sh <backup_directory>` |
| `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 ### Deployment and Health Check Script