mirror of
https://github.com/uprightbass360/AzerothCore-RealmMaster.git
synced 2026-01-13 00:58:34 +00:00
updates to use hosted scripts
This commit is contained in:
Deckard
361
scripts/GITHUB-HOSTED-SCRIPTS.md
Normal file
361
scripts/GITHUB-HOSTED-SCRIPTS.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# GitHub-Hosted Service Scripts Documentation
|
||||
|
||||
This document describes the GitHub-hosted scripts that are automatically downloaded and executed by Docker containers during AzerothCore deployment.
|
||||
|
||||
## Overview
|
||||
|
||||
The AzerothCore Docker deployment uses a hybrid script management approach:
|
||||
- **Local Scripts**: Run from your environment for setup and management
|
||||
- **GitHub-Hosted Scripts**: Downloaded at runtime by containers for service operations
|
||||
|
||||
This pattern ensures Portainer compatibility while maintaining flexibility and maintainability.
|
||||
|
||||
## GitHub-Hosted Scripts
|
||||
|
||||
### 🗂️ `download-client-data.sh`
|
||||
**Purpose**: Downloads and extracts WoW 3.3.5a client data files (~15GB)
|
||||
|
||||
**Features**:
|
||||
- Intelligent caching system to avoid re-downloads
|
||||
- Progress monitoring during extraction
|
||||
- Integrity verification of downloaded files
|
||||
- Fallback URLs for reliability
|
||||
- Automatic directory structure validation
|
||||
|
||||
**Container Usage**: `ac-client-data` service
|
||||
**Volumes Required**:
|
||||
- `/cache` - For caching downloaded files
|
||||
- `/azerothcore/data` - For extracted game data
|
||||
|
||||
**Environment Variables**:
|
||||
```bash
|
||||
# Automatically set by container, no manual configuration needed
|
||||
```
|
||||
|
||||
**Process Flow**:
|
||||
1. Fetches latest release info from wowgaming/client-data
|
||||
2. Checks cache for existing files
|
||||
3. Downloads if not cached or corrupted
|
||||
4. Extracts with progress monitoring
|
||||
5. Validates directory structure (maps, vmaps, mmaps, dbc)
|
||||
|
||||
---
|
||||
|
||||
### 🔧 `manage-modules.sh`
|
||||
**Purpose**: Comprehensive AzerothCore module management and configuration
|
||||
|
||||
**Features**:
|
||||
- Dynamic module installation based on environment variables
|
||||
- Automatic removal of disabled modules
|
||||
- Configuration file management (.conf.dist → .conf)
|
||||
- SQL script execution for module databases
|
||||
- Module state tracking for rebuild detection
|
||||
- Integration with external SQL script library
|
||||
|
||||
**Container Usage**: `ac-modules` service
|
||||
**Volumes Required**:
|
||||
- `/modules` - Module installation directory
|
||||
- `/azerothcore/env/dist/etc` - Configuration files
|
||||
|
||||
**Environment Variables**:
|
||||
```bash
|
||||
# Git Configuration
|
||||
GIT_EMAIL=your-email@example.com
|
||||
GIT_PAT=your-github-token
|
||||
GIT_USERNAME=your-username
|
||||
|
||||
# Module Toggle Variables (1=enabled, 0=disabled)
|
||||
MODULE_PLAYERBOTS=1
|
||||
MODULE_AOE_LOOT=1
|
||||
MODULE_LEARN_SPELLS=1
|
||||
MODULE_FIREWORKS=1
|
||||
MODULE_INDIVIDUAL_PROGRESSION=1
|
||||
MODULE_AHBOT=1
|
||||
MODULE_AUTOBALANCE=1
|
||||
MODULE_TRANSMOG=1
|
||||
MODULE_NPC_BUFFER=1
|
||||
MODULE_DYNAMIC_XP=1
|
||||
MODULE_SOLO_LFG=1
|
||||
MODULE_1V1_ARENA=1
|
||||
MODULE_PHASED_DUELS=1
|
||||
MODULE_BREAKING_NEWS=1
|
||||
MODULE_BOSS_ANNOUNCER=1
|
||||
MODULE_ACCOUNT_ACHIEVEMENTS=1
|
||||
MODULE_AUTO_REVIVE=1
|
||||
MODULE_GAIN_HONOR_GUARD=1
|
||||
MODULE_ELUNA=1
|
||||
MODULE_TIME_IS_TIME=1
|
||||
MODULE_POCKET_PORTAL=1
|
||||
MODULE_RANDOM_ENCHANTS=1
|
||||
MODULE_SOLOCRAFT=1
|
||||
MODULE_PVP_TITLES=1
|
||||
MODULE_NPC_BEASTMASTER=1
|
||||
MODULE_NPC_ENCHANTER=1
|
||||
MODULE_INSTANCE_RESET=1
|
||||
MODULE_LEVEL_GRANT=1
|
||||
MODULE_ARAC=1
|
||||
MODULE_ASSISTANT=1
|
||||
MODULE_REAGENT_BANK=1
|
||||
MODULE_BLACK_MARKET_AUCTION_HOUSE=1
|
||||
|
||||
# Database Configuration
|
||||
CONTAINER_MYSQL=ac-mysql
|
||||
MYSQL_ROOT_PASSWORD=your-password
|
||||
DB_AUTH_NAME=acore_auth
|
||||
DB_WORLD_NAME=acore_world
|
||||
DB_CHARACTERS_NAME=acore_characters
|
||||
```
|
||||
|
||||
**Process Flow**:
|
||||
1. Sets up Git configuration for module downloads
|
||||
2. Removes disabled modules from `/modules` directory
|
||||
3. Clones enabled modules from GitHub repositories
|
||||
4. Installs module configuration files
|
||||
5. Executes module SQL scripts via `manage-modules-sql.sh`
|
||||
6. Tracks module state changes for rebuild detection
|
||||
7. Downloads rebuild script for user convenience
|
||||
|
||||
---
|
||||
|
||||
### 🗄️ `manage-modules-sql.sh`
|
||||
**Purpose**: SQL script execution functions for module database setup
|
||||
|
||||
**Features**:
|
||||
- Systematic SQL file discovery and execution
|
||||
- Support for multiple database targets (auth, world, characters)
|
||||
- Error handling and logging
|
||||
- MariaDB client installation if needed
|
||||
|
||||
**Container Usage**: Sourced by `manage-modules.sh`
|
||||
**Dependencies**: Requires MariaDB/MySQL client tools
|
||||
|
||||
**Function**: `execute_module_sql_scripts()`
|
||||
- Executes SQL for all enabled modules
|
||||
- Searches common SQL directories (`data/sql/`, `sql/`)
|
||||
- Handles auth, world, and character database scripts
|
||||
|
||||
---
|
||||
|
||||
### 🚀 `mysql-startup.sh`
|
||||
**Purpose**: MySQL initialization with backup restoration support
|
||||
|
||||
**Features**:
|
||||
- NFS-compatible permission handling
|
||||
- Automatic backup detection and restoration
|
||||
- Support for multiple backup formats (daily, hourly, legacy)
|
||||
- Configurable MySQL parameters
|
||||
- Background restore operations
|
||||
|
||||
**Container Usage**: `ac-mysql` service
|
||||
**Volumes Required**:
|
||||
- `/var/lib/mysql-runtime` - Runtime MySQL data (tmpfs)
|
||||
- `/backups` - Backup storage directory
|
||||
|
||||
**Environment Variables**:
|
||||
```bash
|
||||
MYSQL_CHARACTER_SET=utf8mb4
|
||||
MYSQL_COLLATION=utf8mb4_unicode_ci
|
||||
MYSQL_MAX_CONNECTIONS=500
|
||||
MYSQL_INNODB_BUFFER_POOL_SIZE=1G
|
||||
MYSQL_INNODB_LOG_FILE_SIZE=256M
|
||||
MYSQL_ROOT_PASSWORD=your-password
|
||||
```
|
||||
|
||||
**Process Flow**:
|
||||
1. Creates and configures runtime MySQL directory
|
||||
2. Scans for available backups (daily → hourly → legacy)
|
||||
3. Starts MySQL in background if restore needed
|
||||
4. Downloads and executes restore script from GitHub
|
||||
5. Runs MySQL normally if no restore required
|
||||
|
||||
---
|
||||
|
||||
### ⏰ `backup-scheduler.sh`
|
||||
**Purpose**: Enhanced backup scheduler with hourly and daily schedules
|
||||
|
||||
**Features**:
|
||||
- Configurable backup timing
|
||||
- Separate hourly and daily backup retention
|
||||
- Automatic backup script downloading
|
||||
- Collision avoidance between backup types
|
||||
- Initial backup execution
|
||||
|
||||
**Container Usage**: `ac-backup` service
|
||||
**Volumes Required**:
|
||||
- `/backups` - Backup storage directory
|
||||
|
||||
**Environment Variables**:
|
||||
```bash
|
||||
BACKUP_DAILY_TIME=03 # Hour for daily backups (UTC)
|
||||
BACKUP_RETENTION_DAYS=7 # Daily backup retention
|
||||
BACKUP_RETENTION_HOURS=48 # Hourly backup retention
|
||||
MYSQL_HOST=ac-mysql
|
||||
MYSQL_ROOT_PASSWORD=your-password
|
||||
```
|
||||
|
||||
**Process Flow**:
|
||||
1. Downloads backup scripts from GitHub
|
||||
2. Waits for MySQL to be available
|
||||
3. Executes initial daily backup
|
||||
4. Runs continuous scheduler loop
|
||||
5. Executes hourly/daily backups based on time
|
||||
|
||||
---
|
||||
|
||||
### 🏗️ `db-init.sh`
|
||||
**Purpose**: Database creation and initialization
|
||||
|
||||
**Features**:
|
||||
- MySQL readiness validation
|
||||
- Legacy backup restoration support
|
||||
- AzerothCore database creation
|
||||
- Character set and collation configuration
|
||||
|
||||
**Container Usage**: `ac-db-init` service
|
||||
|
||||
**Environment Variables**:
|
||||
```bash
|
||||
MYSQL_HOST=ac-mysql
|
||||
MYSQL_USER=root
|
||||
MYSQL_ROOT_PASSWORD=your-password
|
||||
DB_AUTH_NAME=acore_auth
|
||||
DB_WORLD_NAME=acore_world
|
||||
DB_CHARACTERS_NAME=acore_characters
|
||||
MYSQL_CHARACTER_SET=utf8mb4
|
||||
MYSQL_COLLATION=utf8mb4_unicode_ci
|
||||
DB_WAIT_RETRIES=60
|
||||
DB_WAIT_SLEEP=5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 📥 `db-import.sh`
|
||||
**Purpose**: Database schema import operations
|
||||
|
||||
**Features**:
|
||||
- Database availability verification
|
||||
- Dynamic configuration file generation
|
||||
- AzerothCore dbimport execution
|
||||
- Extended timeout handling
|
||||
|
||||
**Container Usage**: `ac-db-import` service
|
||||
|
||||
**Environment Variables**:
|
||||
```bash
|
||||
CONTAINER_MYSQL=ac-mysql
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_USER=root
|
||||
MYSQL_ROOT_PASSWORD=your-password
|
||||
DB_AUTH_NAME=acore_auth
|
||||
DB_WORLD_NAME=acore_world
|
||||
DB_CHARACTERS_NAME=acore_characters
|
||||
```
|
||||
|
||||
## Script Deployment Pattern
|
||||
|
||||
### Download Pattern
|
||||
All GitHub-hosted scripts use this consistent pattern:
|
||||
```bash
|
||||
# Install curl if needed
|
||||
apk add --no-cache curl # Alpine
|
||||
# OR
|
||||
apt-get update && apt-get install -y curl # Debian/Ubuntu
|
||||
|
||||
# Download script
|
||||
curl -fsSL https://raw.githubusercontent.com/uprightbass360/acore-compose/main/scripts/SCRIPT_NAME.sh -o /tmp/SCRIPT_NAME.sh
|
||||
|
||||
# Make executable and run
|
||||
chmod +x /tmp/SCRIPT_NAME.sh
|
||||
/tmp/SCRIPT_NAME.sh
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
- All scripts use `set -e` for immediate exit on errors
|
||||
- Network failures trigger retries or fallback mechanisms
|
||||
- Missing dependencies are automatically installed
|
||||
- Detailed logging with emoji indicators for easy monitoring
|
||||
|
||||
### Security Considerations
|
||||
- Scripts are downloaded from the official repository
|
||||
- HTTPS is used for all downloads
|
||||
- File integrity is verified where applicable
|
||||
- Minimal privilege escalation (only when necessary)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Script Download Failures**:
|
||||
```bash
|
||||
# Check network connectivity
|
||||
ping raw.githubusercontent.com
|
||||
|
||||
# Manual download test
|
||||
curl -v https://raw.githubusercontent.com/uprightbass360/acore-compose/main/scripts/download-client-data.sh
|
||||
```
|
||||
|
||||
**Module Installation Issues**:
|
||||
```bash
|
||||
# Check module environment variables
|
||||
docker exec ac-modules env | grep MODULE_
|
||||
|
||||
# Verify Git authentication
|
||||
docker exec ac-modules git config --list
|
||||
```
|
||||
|
||||
**Database Connection Issues**:
|
||||
```bash
|
||||
# Test MySQL connectivity
|
||||
docker exec ac-db-init mysql -h ac-mysql -u root -p[password] -e "SELECT 1;"
|
||||
|
||||
# Check database container status
|
||||
docker logs ac-mysql
|
||||
```
|
||||
|
||||
### Manual Script Testing
|
||||
|
||||
You can download and test any GitHub-hosted script manually:
|
||||
|
||||
```bash
|
||||
# Create test environment
|
||||
mkdir -p /tmp/script-test
|
||||
cd /tmp/script-test
|
||||
|
||||
# Download script
|
||||
curl -fsSL https://raw.githubusercontent.com/uprightbass360/acore-compose/main/scripts/SCRIPT_NAME.sh -o test-script.sh
|
||||
|
||||
# Review script content
|
||||
cat test-script.sh
|
||||
|
||||
# Set required environment variables
|
||||
export MYSQL_ROOT_PASSWORD=testpass
|
||||
# ... other variables as needed
|
||||
|
||||
# Execute (with caution - some scripts modify filesystem)
|
||||
chmod +x test-script.sh
|
||||
./test-script.sh
|
||||
```
|
||||
|
||||
## Benefits of GitHub-Hosted Pattern
|
||||
|
||||
### ✅ Portainer Compatibility
|
||||
- Only requires `docker-compose.yml` and `.env` files
|
||||
- No additional file dependencies
|
||||
- Works with any Docker Compose deployment method
|
||||
|
||||
### ✅ Maintainability
|
||||
- Scripts can be updated without rebuilding containers
|
||||
- Version control for all service logic
|
||||
- Easy rollback to previous versions
|
||||
|
||||
### ✅ Consistency
|
||||
- Same scripts across all environments
|
||||
- Centralized script management
|
||||
- Reduced configuration drift
|
||||
|
||||
### ✅ Reliability
|
||||
- Fallback mechanisms for network failures
|
||||
- Automatic dependency installation
|
||||
- Comprehensive error handling
|
||||
|
||||
This pattern makes the AzerothCore deployment both powerful and portable, suitable for everything from local development to production Portainer deployments.
|
||||
Reference in New Issue
Block a user