mirror of
https://github.com/uprightbass360/AzerothCore-RealmMaster.git
synced 2026-01-21 12:37:06 +00:00
adding module functionality and final setup
This commit is contained in:
uprightbass360
270
MODULE_MANAGEMENT.md
Normal file
270
MODULE_MANAGEMENT.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# 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** (`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
|
||||
- mod-learn-spells
|
||||
- mod-fireworks-on-level
|
||||
- mod-individual-progression (Auto-configures accounts)
|
||||
- All other modules...
|
||||
|
||||
## 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):
|
||||
./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
|
||||
./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
|
||||
./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.
|
||||
Reference in New Issue
Block a user