AzerothCore-RealmMaster/README.md

AzerothCore RealmMaster

A complete containerized deployment of AzerothCore WoW 3.3.5a (Wrath of the Lich King) private server with 68 enhanced modules and intelligent automation.

🚀 Quick Start

Prerequisites

• Docker with Docker Compose
• 16GB+ RAM and 32GB+ storage
• Linux/macOS/WSL2 (Windows with WSL2 recommended)

Three Simple Steps

# 1. Get the code
git clone https://github.com/uprightbass360/AzerothCore-RealmMaster.git
cd AzerothCore-RealmMaster

# 2. Configure your server
./setup.sh

# 3. Build (if using modules/playerbots) and deploy
./build.sh    # Optional - only if you enabled C++ modules or playerbots
./deploy.sh   # Always required

First deployment takes 30-60 minutes for database setup and client data download. Subsequent starts are much faster.

See Local Deployment for detailed walkthrough.

---

📋 What Gets Installed Automatically

✅ Core Server Components

• AzerothCore 3.3.5a - WotLK server application
• MySQL 8.0 - Database with intelligent initialization and restoration
• Smart Module System - Automated module management and source builds (compiles the mod-playerbots fork whenever modules need C++ changes)
• phpMyAdmin - Web-based database administration
• Keira3 - Game content editor and developer tools

✅ Available Enhanced Modules

All modules are automatically downloaded, configured, and SQL scripts executed when enabled. Browse the complete collection of 93 modules organized by category:

🤖 Automation

Module	Description
mod-ollama-chat	Connects playerbots to an Ollama LLM so they can chat with humans organically
mod-player-bot-level-brackets	Keeps bot levels spread evenly across configured brackets
mod-playerbots	Adds scriptable playerbot characters that can form dungeon parties, raid, and PvP with humans
npcbot-extended-commands	Provides gear templates, transmog clearing, and chat features for NPC bots

✨ Quality of Life

Module	Description
mod-aoe-loot	Lets characters loot multiple corpses with one click for faster farming
mod-auto-revive	Automatically resurrects characters on death—handy for casual PvE or testing realms
mod-fireworks-on-level	Spawns celebratory fireworks whenever a player dings a new level
mod-instance-reset	Adds commands to reset instances quickly—useful for testing or events
mod-learn-spells	Teaches class spells automatically at the correct level to streamline leveling
mod-solo-lfg	A solo-friendly queue that lets every player run dungeons without needing a premade group

⚔️ Gameplay Enhancement

Module	Description
DungeonRespawn	Teleports dead players back to the dungeon entrance instead of a distant graveyard
StatBooster	Lets players refine gear stats by rerolling random enchantments with special materials
horadric-cube-for-world-of-warcraft	Diablo II-inspired crafting system with item synthesis and transmutation
lua-hardcoremode	Implements hardcore mode system allowing activation via NPC token
mod-TimeIsTime	Adds experimental time-twisting mechanics suited for custom events
mod-autobalance	Adjusts creature health and damage in real time to keep fights tuned for the current party size
mod-challenge-modes	Implements keystone-style timed runs with leaderboards and scaling modifiers
mod-duel-reset	Adds some duel reset features
mod-solocraft	Automatically scales dungeon and raid encounters for solo players or small teams

🏪 NPC Services

Module	Description
azerothcore-lua-multivendor	Enables multiple NPC merchants with database integration
mod-assistant	Spawns an all-purpose assistant NPC with heirlooms, professions, and convenience commands
mod-npc-beastmaster	Adds an NPC who can teach, reset, and manage hunter pets for convenience
mod-npc-buffer	Provides a ready-to-use buff NPC who hands out class buffs, food, and utility spells
mod-npc-enchanter	Introduces an enchanting vendor who applies enchants directly for a fee
mod-npc-free-professions	Makes a ProfessionsNPC who gives 2 free professions (full with recipes) to player
mod-npc-talent-template	An NPC that allows players to instantly apply pre-configured character templates that gear up, gem, set talents, and apply glyphs for any class
mod-reagent-bank	Lets players stash crafting reagents with a dedicated banker NPC
mod-transmog	Adds a transmogrification vendor so players can restyle gear without changing stats

⚡ PvP

Module	Description
mod-1v1-arena	Creates a structured 1v1 ranked arena ladder for duel enthusiasts
mod-arena-replay	Allows you to watch a replay of rated arena games
mod-gain-honor-guard	Awards honor when players kill city guards, spicing up world PvP raids
mod-phased-duels	Moves duelers into their own phase to block interference and griefing
mod-pvp-titles	Restores classic honor titles with a configurable ranking ladder
ultimate-full-loot-pvp	Spawns loot chests containing gear and gold when players die in PvP

📈 Progression

Module	Description
mod-dynamic-xp	Tweaks XP gain based on population or custom rules to keep leveling flexible
mod-individual-progression	Tracks each character through Vanilla → TBC → WotLK progression, unlocking content sequentially
mod-item-level-up	Creates an item that allows you to level up (id = 701001)
mod-progression-system	Allows for the automatic loading of scripts and SQL files based on level brackets
mod-promotion-azerothcore	Allows player to receive a promotion consisting of a level 90 character, backpacks, gold, armor, and a mount
mod-quest-count-level	Enables leveling exclusively through questing by awarding tokens after quest completion
mod-weekend-xp	XP module that allows server owner to select how much XP players can receive on the weekend via config file
mod-zone-difficulty	Support module for mod-progression-system, handles nerfs and debuffs per zone

💰 Economy

Module	Description
acore-exchangenpc	Spawns a customizable NPC vendor that exchanges materials based on settings
azerothcore-global-mail-banking-auctions	Allows access to bank, mailbox, and auction house from anywhere via chat commands
azerothcore-lua-ah-bot	Automated auction house bot for buying and selling items
dynamic-trader	Provides auction house alternative with dynamic pricing
lottery-lua	Implements customizable lottery system where players can win prizes
mod-ahbot	Populates the auction house with configurable buying/selling behavior to keep markets active
mod-black-market	Backports the Mists-era Black Market Auction House via Eluna scripts
mod-random-enchants	Rolls randomized stat bonuses on loot to add Diablo-style gear chasing

👥 Social

Module	Description
acore-discordnotifier	Relays in-game chat events to Discord channels
acore-tempannouncements	Allows GMs to create temporary server announcements that repeat at intervals
activechat	Populates artificial world and guild chat to make servers feel more lively
mod-boss-announcer	Broadcasts dramatic messages when raid bosses fall to your players
mod-breaking-news-override	Replaces the client breaking-news panel with server-managed announcements
mod-global-chat	Simple global chat for AzerothCore enabling worldserver-wide messaging functionality

👤 Account-Wide

Module	Description
azerothcore-eluna-accountwide	Shares achievements, currency, mounts, and reputation across account characters
mod-account-achievements	Shares achievements across characters on the same account for persistent milestones
mod-account-mounts	Goes through the list of characters on an account to obtain playerGuids and store mount spells that all characters know

🎨 Customization

Module	Description
azerothcore-transmog-3.3.5a	Transmogrification system built with AIO and Eluna for changing equipment appearance
mod-arac	Unlocks every race/class pairing so players can roll any combination
mod-morphsummon	Change appearance of summoned permanent creatures
mod-worgoblin	Enables Worgen and Goblin characters with DB/DBC adjustments

📜 Scripting

Module	Description
acore-eventscripts	Lua scripts that spawn custom NPCs with scripted combat and community events
eluna-scripts	Collection of Lua scripts for creating custom gameplay mechanics and features
eluna-ts	Adds a TS-to-Lua workflow so Eluna scripts can be authored with modern tooling
mod-aio	Pure Lua server-client communication system for bidirectional data transmission
mod-ale	Adds Eluna Lua scripting engine for creating custom gameplay mechanics

🔧 Admin Tools

Module	Description
acore-carboncopy	Enables creating character copies at specific progression points for twinking
acore-sendandbind	Allows admins to send soulbound items to players via command
acore-zonecheck	Checks player zones and automatically removes players from restricted areas
mod-antifarming	Port of the AntiFarming Script from SymbolixDEV's repo to AzerothCore
mod-keep-out	Keeps players who are non-GM from entering a zone/map
mod-server-auto-shutdown	Establishes a daily restart with configurable time, notification period, and custom messages
mod-spell-regulator	Modify the percentage of the spells by regulating in the best way
mod-who-logged	Outputs to the console when a player logs into the world

💎 Premium/VIP

Module	Description
mod-acore-subscriptions	Handles the subscription logic, no longer requires modules or services to have subscription logic in their code
mod-premium	Adds Premium account features to players
mod-system-vip	System offering VIP features and benefits to players

🎮 Mini-Games

Module	Description
aio-blackjack	Implements a Blackjack game for players to gamble against an NPC dealer
mod-pocket-portal	Gives players a portal gadget for quick travel to configured destinations
mod-tic-tac-toe	Allows players to play Tic Tac Toe between players and against different AI

🏰 Content

Module	Description
mod-azerothshard	Bundles AzerothShard tweaks: utility NPCs, scripted events, and gameplay improvements
mod-bg-slaveryvalley	Adds the Slavery Valley battleground complete with objectives and queue hooks
mod-guildhouse	Phased guild house system allowing guild members to visit their private guild house
mod-war-effort	Brings back the war effort of the two factions for the opening of the gates of Ahn'Qiraj
treasure-chest-system	Allows GMs to create and manage treasure chests with custom loot

🎁 Rewards

Module	Description
acore-levelupreward	Rewards players with in-game mail when reaching certain levels
acore-recruitafriend	Implements Recruit-a-Friend system with rewards for reaching level milestones
mod-resurrection-scroll	Allows users to grant rested XP bonuses to players who have not logged in X days
mod-reward-played-time	Adds items for players that have stayed logged in for x amount of time
prestige-and-draft-mode	Enables characters to reset to level one for prestige rewards with optional spell selection

🛠️ Developer Tools

Module	Description
skeleton-module	Provides a minimal AzerothCore module scaffold for building new features

✅ Automated Configuration

• Intelligent Database Setup - Smart backup detection, restoration, and conditional schema import
• Backup Management - Automated hourly/daily backups with intelligent restoration
• Module Integration - Automatic source builds when C++ modules are enabled
• Realmlist Configuration - Server address and port setup
• Service Orchestration - Profile-based deployment (standard/playerbots/modules)
• Health Monitoring - Container health checks and restart policies

✅ Lua Scripting Environment

• Eluna Engine - Built-in Lua scripting support with TypeScript compilation
• Script Auto-loading - Scripts automatically loaded from storage/lua_scripts/
• Development Tools - Script reloading with .reload eluna command
• Volume Mounting - Hot-reload development environment

---

🏗️ Local Deployment

Complete walkthrough for deploying on your local machine.

Step 1: Initial Setup

1.1 Clone the Repository

git clone https://github.com/uprightbass360/AzerothCore-RealmMaster.git
cd AzerothCore-RealmMaster

1.2 Run Interactive Setup

./setup.sh

The setup wizard will guide you through:

• Server Configuration: IP address, ports, timezone
• Module Selection: Choose from 30+ available modules or use presets
• Storage Paths: Configure NFS/local storage locations
• Playerbot Settings: Max bots, account limits (if enabled)
• Backup Settings: Retention policies for automated backups
• Permissions: User/group IDs for file ownership

Setup Output: Creates .env file with your configuration

Step 2: Build Images (if using C++ modules or playerbots)

./build.sh

Skip this step if:

• You're using only Lua/data modules
• You want vanilla AzerothCore without playerbots

Required when:

• Playerbots enabled (MODULE_PLAYERBOTS=1)
• Any C++ module enabled (check needs_build: true in config/modules.json)

Build process:

1. Clones AzerothCore source to local-storage/source/
2. Downloads and stages enabled modules
3. Compiles server binaries with modules
4. Creates Docker images tagged as <project-name>:authserver-modules-latest, etc.
5. Takes 20-60 minutes depending on hardware

Step 3: Deploy Services

./deploy.sh

Deployment flow:

1. Validates environment configuration
2. Auto-selects Docker Compose profile:
   • services-standard - Vanilla AzerothCore
   • services-playerbots - Playerbot build
   • services-modules - Custom C++ modules build
3. Starts services in dependency order:
   • Database layer (ac-mysql, ac-db-init, ac-db-import, ac-backup)
   • Module management (ac-modules, ac-post-install)
   • Client data (ac-client-data)
   • Game servers (ac-authserver, ac-worldserver)
4. Tails worldserver logs (Ctrl+C to detach safely)

First deployment takes longer due to:

• Database schema import (~5-10 minutes)
• Client data download (~15GB, ~10-30 minutes)
• Module SQL execution

Subsequent deployments restore from backups and skip imports.

Step 4: Create Admin Account

# Attach to worldserver console
docker attach ac-worldserver

# Create admin account
account create admin yourpassword
account set gmlevel admin 3 -1

# Detach: Ctrl+P, Ctrl+Q (NOT Ctrl+C - that stops the server!)

Step 5: Connect Game Client

Edit realmlist.wtf in your WoW 3.3.5a client folder:

set realmlist 127.0.0.1

For custom ports:

set realmlist 127.0.0.1 8215

Step 6: Access Management Tools

• phpMyAdmin: http://localhost:8081 - Database administration
• Keira3: http://localhost:4201 - World database editor

Credentials:

• Username: root
• Password: From MYSQL_ROOT_PASSWORD in .env

---

🚀 Remote Deployment

Deploy your configured realm to a remote server while building images locally.

Remote Deployment Workflow

Step 1: Configure & Build Locally

# Interactive configuration with module selection
./setup.sh

# Build custom images (if using C++ modules or playerbots)
./build.sh --yes

Step 2: Package & Transfer to Remote Host

You can deploy remotely in two ways:

Option A: Interactive (Recommended)

./deploy.sh
# When prompted, select "2) Remote host (package for SSH deployment)"
# Follow prompts for hostname, username, and paths

Option B: Non-Interactive

./deploy.sh --yes \
  --remote-host your-server.com \
  --remote-user youruser \
  --remote-project-dir /home/youruser/AzerothCore-RealmMaster

Optional flags:

• --remote-port 2222 - Custom SSH port
• --remote-identity ~/.ssh/custom_key - Specific SSH key
• --remote-skip-storage - Don't sync storage directory (fresh install on remote)

Step 3: Deploy on Remote Host

ssh your-server.com
cd /home/youruser/AzerothCore-RealmMaster
./deploy.sh --yes --no-watch

The remote deployment uses the images you built locally (no rebuild needed).

Step 4: Verify Deployment

./status.sh
# Check service logs
docker logs ac-worldserver -f

What Gets Transferred

The remote deployment process transfers:

• ✅ Docker images (exported to local-storage/images/)
• ✅ Project files (scripts, configs, docker-compose.yml, .env)
• ✅ Storage directory (unless --remote-skip-storage is used)
• ❌ Build artifacts (source code, compilation files stay local)

Module Presets

• Drop comma-separated module lists into profiles/*.conf (for example profiles/playerbot-modules.conf).
• setup.sh automatically adds these presets to the module menu and enables the listed modules when selected or when --module-config <name> is provided.
• Built-in presets:
  • profiles/suggested-modules.conf – default solo-friendly QoL stack.
  • profiles/playerbots-suggested-modules.conf – suggested stack plus playerbots.
  • profiles/playerbot-only.conf – playerbot-focused profile (adjust --playerbot-max-bots).
• Custom example:
  • profiles/sam.conf – Sam's playerbot-focused profile (set --playerbot-max-bots 3000 when using this preset).

---

🏗️ Architecture Overview

Container Profiles

flowchart TB
    subgraph init["🔧 Initialization"]
        direction LR
        volinit["ac-volume-init<br/>Docker Volume Permissions"]
        storinit["ac-storage-init<br/>Storage Directory Permissions"]
    end

    subgraph database["💾 Database Layer"]
        direction LR
        mysql["ac-mysql<br/>MySQL 8.0<br/>:64306"]
        dbinit["ac-db-init<br/>Database Creation"]
        dbimport["ac-db-import<br/>Schema Import"]
        backup["ac-backup<br/>Automated Backups"]
    end

    subgraph clientdata["📦 Client Data"]
        client["ac-client-data<br/>WoW Assets (~15GB)"]
    end

    subgraph modmgmt["⚙️ Module Management"]
        direction LR
        modmgr["ac-modules<br/>Downloader & SQL"]
        postinst["ac-post-install<br/>Configuration"]
    end

    subgraph services["🎮 Game Services"]
        direction TB
        subgraph standard["services-standard"]
            direction LR
            auth1["ac-authserver<br/>:3784"]
            world1["ac-worldserver<br/>:8215, :7778"]
        end
        subgraph playerbots["services-playerbots"]
            direction LR
            auth2["ac-authserver-playerbots<br/>:3784"]
            world2["ac-worldserver-playerbots<br/>:8215, :7778"]
        end
        subgraph mods["services-modules"]
            direction LR
            auth3["ac-authserver-modules<br/>:3784"]
            world3["ac-worldserver-modules<br/>:8215, :7778"]
        end
    end

    subgraph tools["🛠️ Management Tools"]
        direction LR
        pma["ac-phpmyadmin<br/>:8081"]
        keira["ac-keira3<br/>:4201"]
    end

    init -.-> database
    database -.-> modmgmt
    database -.-> clientdata
    modmgmt -.-> services
    clientdata -.-> services
    database -.-> tools

    style init fill:#f5f5f5,stroke:#999,color:#000
    style database fill:#e1ffe1,stroke:#4caf50,color:#000
    style clientdata fill:#f0e1ff,stroke:#9c27b0,color:#000
    style modmgmt fill:#ffe1e1,stroke:#f44336,color:#000
    style services fill:#fff4e1,stroke:#ff9800,color:#000
    style tools fill:#e1f5ff,stroke:#2196f3,color:#000
    style standard fill:#fff9e1,color:#000
    style playerbots fill:#fff9e1,color:#000
    style mods fill:#fff9e1,color:#000

Profile Notes:

• Initialization: Auto-runs, no profile needed
• Database Layer: profile: db
• Client Data: profile: client-data or client-data-bots
• Module Management: profile: modules
• Game Services: ONE of services-standard, services-playerbots, or services-modules
• Management Tools: profile: tools

Service Inventory & Ports

Service / Container	Role	Ports (host → container)	Profile
ac-mysql	MySQL 8.0 database	64306 → 3306	db
ac-db-init	Database schema initialization	–	db
ac-db-import	Database content import	–	db
ac-backup	Automated backup system	–	db
ac-authserver	Auth server (standard)	3784 → 3724	services-standard
ac-worldserver	World server (standard)	8215 → 8085, 7778 → 7878	services-standard
ac-authserver-playerbots	Playerbots auth	3784 → 3724	services-playerbots
ac-worldserver-playerbots	Playerbots world	8215 → 8085, 7778 → 7878	services-playerbots
ac-authserver-modules	Custom build auth	3784 → 3724	services-modules
ac-worldserver-modules	Custom build world	8215 → 8085, 7778 → 7878	services-modules
ac-client-data	Client data fetcher	–	client-data
ac-modules	Module manager	–	modules
ac-post-install	Post-installation configuration	–	Auto-start
ac-phpmyadmin	Database admin UI	8081 → 80	tools
ac-keira3	Game content editor	4201 → 8080	tools

Storage Structure

The project uses a dual-storage approach for optimal performance:

Primary Storage (STORAGE_PATH - default: NFS mount or shared storage)

storage/
├── config/           # Server configuration files (.conf)
├── logs/             # Server log files
├── modules/          # Downloaded module source code
├── lua_scripts/      # Eluna Lua scripts (auto-loaded)
├── install-markers/  # Module installation state tracking
└── backups/          # Automated database backups
    ├── daily/        # Daily backups (retained per BACKUP_RETENTION_DAYS)
    └── hourly/       # Hourly backups (retained per BACKUP_RETENTION_HOURS)

Local Storage (STORAGE_PATH_LOCAL - default: ./local-storage)

local-storage/
├── mysql-data/           # MySQL persistent data (tmpfs runtime + persistent snapshot)
├── client-data-cache/    # Downloaded WoW client data archives
├── source/               # AzerothCore source repository (created during builds)
│   └── azerothcore-playerbots/  # Playerbot fork (when playerbots enabled)
└── images/               # Exported Docker images for remote deployment

Docker Volumes

• ac-client-data - Unpacked game client data (DBC, maps, vmaps, mmaps)
• client-data-cache - Temporary storage for client data downloads

This separation ensures database and build artifacts stay on fast local storage while configuration, modules, and backups can be shared across hosts via NFS.

---

🛠️ Management Commands

Health Monitoring

# Check realm status
./status.sh

# Watch services continuously
./status.sh --watch

# View service logs
docker logs ac-worldserver -f
docker logs ac-authserver -f

# Check module management
docker logs ac-modules --tail 50

Web Tools Access

Once deployed, access the management tools in your browser:

# Database Management (phpMyAdmin)
http://YOUR_SERVER_IP:8081

# World Database Editor (Keira3)
http://YOUR_SERVER_IP:4201

# Replace YOUR_SERVER_IP with your actual server address
# Example: http://192.168.1.100:4201

Note: Initial Keira3 startup may show database connection errors until the world database import completes. This is expected behavior.

Module Management

# Reconfigure modules via interactive setup
./setup.sh

# Build custom images with enabled modules
./build.sh                          # Interactive build (prompts for confirmation)
./build.sh --yes                    # Auto-confirm build
./build.sh --force                  # Force rebuild regardless of state

# Deploy with automatic profile selection
./deploy.sh                         # Auto-detects and deploys correct profile
./deploy.sh --profile standard      # Force standard AzerothCore
./deploy.sh --profile playerbots    # Force playerbots branch
./deploy.sh --profile modules       # Force custom modules build

# Lower-level module operations
./scripts/stage-modules.sh                    # Download enabled modules
./scripts/setup-source.sh                     # Initialize AzerothCore source
./scripts/copy-module-configs.sh              # Create module .conf files
./scripts/manage-modules-sql.sh               # Execute module SQL scripts

# Management tools
./scripts/deploy-tools.sh                     # Launch phpMyAdmin + Keira3

Database Operations

# Access database via phpMyAdmin
open http://localhost:8081

# Direct MySQL access
docker exec -it ac-mysql mysql -u root -p

# Manual backup operations
./scripts/backup.sh                              # Create immediate backup
./scripts/restore.sh YYYYMMDD_HHMMSS            # Restore from specific backup

# User data backup/import utilities
./scripts/backup-export.sh [output_dir]                 # Export user accounts & characters
./scripts/backup-import.sh [backup_dir]                 # Import user data from backup

# View available backups
ls -la storage/backups/

Container Management

# Start specific services
./scripts/start-containers.sh                           # Start all configured containers

# Stop services gracefully
./scripts/stop-containers.sh                            # Stop all containers

# Monitor service health
./status.sh                                     # Check realm status
./status.sh --watch                            # Watch services continuously
./status.sh --once                             # Single status check

Deployment Verification

# Quick health check
./scripts/verify-deployment.sh --skip-deploy --quick

# Full deployment verification
./scripts/verify-deployment.sh

---

📜 Script Reference

Core Deployment Scripts

setup.sh - Interactive Environment Configuration

Interactive .env generator with module selection, server configuration, and deployment profiles.

./setup.sh                                      # Interactive configuration
./setup.sh --module-config sam                 # Use predefined module preset
./setup.sh --playerbot-max-bots 3000          # Set playerbot limits

Features:

• Server address and port configuration
• Module selection with presets
• Storage path configuration (NFS/local)
• Playerbot configuration
• Backup retention settings
• User/group permission settings

build.sh - Custom Image Builder

Compiles AzerothCore with enabled C++ modules and creates deployment-ready Docker images.

./build.sh                                      # Interactive build
./build.sh --yes                               # Auto-confirm all prompts
./build.sh --force                             # Force rebuild regardless of state
./build.sh --source-path /custom/path         # Use custom source path
./build.sh --skip-source-setup                # Skip source repo setup

What it does:

• Clones/updates AzerothCore source repository
• Stages enabled modules into source tree
• Compiles server binaries with modules
• Builds and tags Docker images (<project>:authserver-modules-latest, etc.)
• Updates build state markers

deploy.sh - Deployment Orchestrator

Module-aware deployment with automatic profile selection and optional remote deployment.

./deploy.sh                                     # Interactive deployment
./deploy.sh --yes                              # Auto-confirm deployment
./deploy.sh --profile standard                 # Force standard AzerothCore
./deploy.sh --profile playerbots               # Force playerbots branch
./deploy.sh --profile modules                  # Force custom modules build
./deploy.sh --no-watch                         # Don't tail worldserver logs
./deploy.sh --keep-running                     # Deploy and exit immediately

# Remote deployment
./deploy.sh --remote-host server.com \
            --remote-user username \
            --remote-project-dir /path/to/project

Automated workflow:

1. Loads environment configuration
2. Detects required profile based on enabled modules
3. Triggers build if C++ modules or playerbots enabled
4. Launches Docker Compose with appropriate profiles
5. Optionally migrates stack to remote host

cleanup.sh - Project Cleanup Utility

Comprehensive cleanup with multiple destruction levels and safety checks.

./cleanup.sh                                   # Interactive cleanup
./cleanup.sh --soft                           # Stop containers only
./cleanup.sh --hard                           # Remove containers, networks, volumes
./cleanup.sh --nuclear                        # Full cleanup including images
./cleanup.sh --preserve-backups               # Retain backup data during cleanup
./cleanup.sh --dry-run                        # Preview cleanup actions

Container Lifecycle Management

scripts/start-containers.sh - Service Startup

Starts all configured containers using appropriate profiles.

scripts/stop-containers.sh - Graceful Shutdown

Stops all containers with proper cleanup and data protection.

status.sh - Service Health Monitoring

./status.sh                                    # Single status check with summary
./status.sh --watch                           # Continuous monitoring mode
./status.sh --once                            # Script-friendly single check

Database & Backup Management

scripts/backup-export.sh - User Data Export

Exports user accounts and character data for migration or backup purposes.

./scripts/backup-export.sh                            # Export to ExportBackup_<timestamp>/
./scripts/backup-export.sh /path/to/backup/dir       # Export to specific directory

Output Structure:

ExportBackup_YYYYMMDD_HHMMSS/
├── acore_auth.sql.gz         # User accounts
├── acore_characters.sql.gz   # Character data
└── manifest.json             # Backup metadata

scripts/backup-import.sh - User Data Import

Restores user accounts and characters from backup while preserving world data.

./scripts/backup-import.sh                            # Import from ImportBackup/
./scripts/backup-import.sh /path/to/backup           # Import from specific directory

Required Files:

• acore_auth.sql[.gz] - User accounts (required)
• acore_characters.sql[.gz] - Character data (required)
• acore_world.sql[.gz] - World data (optional)

Module Management Scripts

scripts/stage-modules.sh - Module Staging

Downloads and stages enabled modules for source integration.

./scripts/stage-modules.sh                    # Stage all enabled modules

Called automatically by build.sh. Downloads enabled modules from GitHub and prepares them for compilation.

scripts/setup-source.sh - Source Repository Setup

Initializes or updates AzerothCore source repositories for compilation.

./scripts/setup-source.sh                     # Setup source for current configuration

Automatically clones the appropriate AzerothCore fork (main or playerbot) based on configuration.

scripts/manage-modules.sh - Module Management Container

Internal script that runs inside the ac-modules container to handle module lifecycle:

• Downloads module source code
• Executes module SQL scripts
• Manages module configuration files
• Tracks installation state

config/modules.json & scripts/modules.py

Central module registry and management system:

• config/modules.json - Declarative manifest defining all 30+ supported modules with metadata:
  • Repository URLs
  • Module type (cpp, data, lua)
  • Build requirements
  • SQL scripts and config files
  • Dependencies
• scripts/modules.py - Python helper that reads the manifest and .env to:
  • Generate modules.env with enabled module lists
  • Determine if rebuild is required
  • Provide module metadata to shell scripts

This centralized approach eliminates duplicate module definitions across scripts.

scripts/manage-modules-sql.sh - Module Database Integration

Executes module-specific SQL scripts for database schema updates.

scripts/copy-module-configs.sh - Configuration File Management

Creates module .conf files from .dist.conf templates for active modules.

./scripts/copy-module-configs.sh              # Create missing module configs

Post-Deployment Automation

scripts/auto-post-install.sh - Post-Installation Configuration

Automated post-deployment tasks including module configuration, service verification, and initial setup.

./scripts/auto-post-install.sh                # Run post-install tasks

Automated Tasks:

1. Module configuration file creation
2. Service health verification
3. Database connectivity testing
4. Initial realm configuration

Advanced Deployment Tools

scripts/migrate-stack.sh - Remote Deployment Migration

Exports and transfers locally built images to remote hosts via SSH.

./scripts/migrate-stack.sh \
  --host docker-server \
  --user sam \
  --project-dir /home/sam/AzerothCore-RealmMaster

./scripts/migrate-stack.sh \
  --host remote.example.com \
  --user deploy \
  --port 2222 \
  --identity ~/.ssh/deploy_key \
  --skip-storage

What it does:

1. Exports module images to local-storage/images/acore-modules-images.tar
2. Syncs project files (.env, docker-compose.yml, scripts) via rsync/scp
3. Syncs storage directory (unless --skip-storage)
4. Imports images on remote host

Note: Typically called via ./deploy.sh --remote-host rather than directly.

scripts/deploy-tools.sh - Management Tools Deployment

Deploys web-based management tools (phpMyAdmin, Keira3) independently.

./scripts/deploy-tools.sh                     # Deploy management tools only

scripts/verify-deployment.sh - Deployment Validation

Comprehensive deployment verification with health checks and service validation.

./scripts/verify-deployment.sh                        # Full deployment verification
./scripts/verify-deployment.sh --skip-deploy         # Verify existing deployment
./scripts/verify-deployment.sh --quick               # Quick health check only

Backup System Scripts

scripts/backup-scheduler.sh - Automated Backup Service

Runs inside the backup container to provide scheduled database backups.

Features:

• Hourly backups (retained for 6 hours)
• Daily backups (retained for 3 days)
• Automatic cleanup based on retention policies
• Database detection (includes playerbots if present)

---

---

🔄 Common Workflows

Changing Module Configuration

# 1. Reconfigure modules
./setup.sh

# 2. Rebuild if you changed C++ modules
./build.sh --yes

# 3. Redeploy with new configuration
./deploy.sh

Updating to Latest Code

# Pull latest changes
git pull origin main

# Rebuild images (if using modules/playerbots)
./build.sh --force

# Restart services
docker compose down
./deploy.sh

Managing Services

# Check service status
./status.sh

# View logs
docker logs ac-worldserver -f
docker logs ac-authserver -f
docker logs ac-mysql -f

# Restart specific service
docker compose restart ac-worldserver

# Stop all services
./scripts/stop-containers.sh

# Start services
./scripts/start-containers.sh

Database Management

# Backup user data
./scripts/backup-export.sh

# Restore user data
./scripts/backup-import.sh /path/to/backup

# Access database directly
docker exec -it ac-mysql mysql -u root -p

Cleaning Up

# Soft cleanup (stop containers only)
./cleanup.sh --soft

# Hard cleanup (remove containers and networks)
./cleanup.sh --hard

# Nuclear cleanup (everything including images and data)
./cleanup.sh --nuclear --preserve-backups

---

🔧 Advanced Configuration

Module-Specific Requirements

Some modules require additional manual configuration after deployment:

mod-playerbots

• Requires playerbots-specific AzerothCore branch
• Automatically handled when MODULE_PLAYERBOTS=1 is set in setup

mod-individual-progression

• Client patches required: patch-V.mpq (found in module storage)
• Server config: Add EnablePlayerSettings = 1 and DBC.EnforceItemAttributes = 0 to worldserver.conf

mod-transmog / mod-npc-* modules

• NPC spawning required: Use GM commands to spawn service NPCs
• Examples:

  .npc add 190010    # Transmog NPC (mod-transmog)
  .npc add 601016    # Buff NPC (mod-npc-buffer)
  .npc add 601026    # Beastmaster NPC "White Fang" (mod-npc-beastmaster)
  .npc add 601015    # Enchanter NPC (mod-npc-enchanter)
  .npc add 290011    # Reagent Bank NPC (mod-reagent-bank)
  .npc add 500030    # Guild House vendor (mod-guildhouse)
  .npc add 601072    # Morph Summon NPC (mod-morphsummon)
  .npc add 98500     # Arena Replay NPC (mod-arena-replay)
  .npc add 100155    # Tic-Tac-Toe game NPC (mod-tic-tac-toe)
  .npc add 1128001   # Mythic Mode NPC (mod-zone-difficulty, spawns in raids/heroic dungeons)
  .npc add 1128002   # Mythic Rewards NPC (mod-zone-difficulty)
  

mod-arac (All Races All Classes)

• Client patches required: Patch-A.MPQ (found in module storage)
• Installation: Players must copy to WoW/Data/ directory
• Server-side: DBC files automatically applied during module installation

Profile Selection

The deployment system uses Docker Compose profiles to manage different configurations:

Profile	When Used	Image Source
services-standard	No C++ modules, no playerbots	Upstream acore/* images
services-playerbots	MODULE_PLAYERBOTS=1 + no other C++ modules	Project-built <name>:*-playerbots
services-modules	Any C++ module enabled (incl. playerbots + others)	Project-built <name>:*-modules-latest

Profile selection is automatic - deploy.sh analyzes your .env and selects the appropriate profile.

Build System

When builds are required:

• Playerbots enabled (MODULE_PLAYERBOTS=1)
• Any C++ module enabled (see needs_build: true in config/modules.json)

Build workflow (./build.sh):

1. Clones AzerothCore source to local-storage/source/
   • Uses mod-playerbots fork when playerbots enabled
   • Uses main AzerothCore otherwise
2. Stages enabled C++ modules into modules/ directory within source
3. Compiles binaries using Dockerized build environment
4. Creates and tags images:
   • <project>:authserver-playerbots / authserver-modules-latest
   • <project>:worldserver-playerbots / worldserver-modules-latest
   • <project>:client-data-playerbots (playerbots only)
   • <project>:db-import-playerbots (playerbots only)

Build time: 20-60 minutes depending on hardware and module count

MySQL Runtime Storage & Timezone Data

• MYSQL_RUNTIME_TMPFS_SIZE controls the in-memory datadir used by the MySQL container. Increase this value if you see No space left on device errors inside /var/lib/mysql-runtime.
• MYSQL_INNODB_REDO_LOG_CAPACITY increases redo log headroom (defaults to 512M). Raise it further if logs report log_checkpointer lag.
• HOST_ZONEINFO_PATH should point to a host directory containing timezone definitions (defaults to /usr/share/zoneinfo). The path is mounted read-only so the container can load timezone tables without extra image customization. Set it to a valid directory on your host if your OS stores zoneinfo elsewhere.

---

🔧 Troubleshooting

Common Issues

Containers failing to start

# Check container logs
docker logs <container_name>

# Verify network connectivity
docker network ls | grep azerothcore

# Check port conflicts
ss -tulpn | grep -E "(3784|8215|8081|4201)"

Module not working

# Check if module is enabled in environment
grep MODULE_NAME .env

# Verify module installation
ls storage/modules/

# Check module-specific configuration
ls storage/config/mod_*.conf*

Database connection issues

# Verify MySQL is running and responsive
docker exec ac-mysql mysql -u root -p -e "SELECT 1;"

# Check database initialization
docker logs ac-db-init
docker logs ac-db-import

Source rebuild issues

# Check rebuild logs
docker logs ac-modules | grep -A20 -B5 "rebuild"

# Verify source path exists
ls -la "${STORAGE_PATH_LOCAL:-./local-storage}/source/azerothcore/"

# Force source setup
./scripts/setup-source.sh

Getting Help

1. Check service status: ./status.sh --watch
2. Review logs: docker logs <service-name> -f
3. Verify configuration: Check .env file for proper module toggles
4. Clean deployment: Stop all services and redeploy with ./deploy.sh

Backup and Restoration System

The stack includes an intelligent backup and restoration system:

Automated Backup Schedule

• Hourly backups: Retained for 6 hours (configurable via BACKUP_RETENTION_HOURS)
• Daily backups: Retained for 3 days (configurable via BACKUP_RETENTION_DAYS)
• Automatic cleanup: Old backups removed based on retention policies

Smart Backup Detection

• Multiple format support: Detects daily, hourly, and legacy timestamped backups
• Priority-based selection: Automatically selects the most recent available backup
• Integrity validation: Verifies backup files before attempting restoration

Intelligent Startup Process

• Automatic restoration: Detects and restores from existing backups on startup
• Conditional import: Skips database import when backup restoration succeeds
• Data protection: Prevents overwriting restored data with fresh schema

Backup Structure

storage/backups/
├── daily/
│   └── YYYYMMDD_HHMMSS/          # Daily backup directories
│       ├── acore_auth.sql.gz
│       ├── acore_characters.sql.gz
│       ├── acore_world.sql.gz
│       └── manifest.json
└── hourly/
    └── YYYYMMDD_HHMMSS/          # Hourly backup directories
        ├── acore_auth.sql.gz
        ├── acore_characters.sql.gz
        └── acore_world.sql.gz

# User data import/export
ExportBackup_YYYYMMDD_HHMMSS/     # Created by scripts/backup-export.sh
├── acore_auth.sql.gz             # User accounts
├── acore_characters.sql.gz       # Character data
└── manifest.json

ImportBackup/                     # Used by scripts/backup-import.sh
├── acore_auth.sql[.gz]           # Required: accounts
├── acore_characters.sql[.gz]     # Required: characters
└── acore_world.sql[.gz]          # Optional: world data

---

📚 Advanced Deployment Options

Custom Environment Configuration

# Setup with specific module preset
./setup.sh --module-config sam --playerbot-max-bots 3000

# Build with custom source path
./build.sh --source-path /path/to/custom/azerothcore --force

# Deploy with specific options
./deploy.sh --profile modules --no-watch --keep-running

Manual Source Management

# Initialize/update AzerothCore source repository
./scripts/setup-source.sh

# Stage modules into source tree (called by build.sh)
./scripts/stage-modules.sh

# Build images from prepared source
./build.sh --skip-source-setup

Manual Service Control

# Stop all services
docker compose --profile db --profile services-standard \
  --profile services-playerbots --profile services-modules \
  --profile client-data --profile modules --profile tools down

# Start specific profile
docker compose --profile db --profile services-playerbots --profile tools up -d

# Restart after configuration changes
docker compose restart ac-worldserver ac-authserver

Force Rebuild

# Force complete rebuild (ignores build state markers)
./build.sh --force

# Clean build artifacts and rebuild
rm -rf local-storage/source local-storage/images
./build.sh

---

🧭 Ownership Hardening TODO

• MySQL container: prototype running as ${CONTAINER_USER} (or via Docker userns remap/custom entrypoint) so shared ${STORAGE_PATH} data stays user-owned while preserving required init privileges.

---

🎯 Next Steps After Installation

In-Game Setup

1. Create GM Account

   docker attach ac-worldserver
   account create <username> <password>
   account set gmlevel <username> 3 -1
   

2. Test Modules - Verify enabled modules are working:

   • Solo LFG: Queue for a dungeon solo
   • Transmog: Use .npc add 190010 to spawn transmog NPC
   • Playerbots: Use .bot add command (if enabled)
   • See "Module-Specific Requirements" section for complete list of NPC spawn commands

3. Configure Realmlist - Update server address in database:

   UPDATE acore_auth.realmlist
   SET address = 'your-public-ip', port = 8215
   WHERE id = 1;
   

Server Administration

1. Set Up Monitoring

   # Watch server status continuously
   ./status.sh --watch
   
   # Monitor logs
   docker logs ac-worldserver -f
   

2. Configure Backups

   • Review retention settings in .env:
     • BACKUP_RETENTION_DAYS=3
     • BACKUP_RETENTION_HOURS=6
   • Test backup/restore:

     ./scripts/backup-export.sh
     ./scripts/backup-import.sh /path/to/backup
     

3. Customize Modules

   • Edit module configs in storage/config/mod_*.conf
   • Restart worldserver: docker compose restart ac-worldserver

4. Add Lua Scripts

   • Place scripts in storage/lua_scripts/
   • Auto-loaded on worldserver start
   • Reload with .reload eluna in-game

Performance Tuning

1. Database Optimization

   • Adjust MYSQL_INNODB_BUFFER_POOL_SIZE in .env
   • Increase MYSQL_RUNTIME_TMPFS_SIZE for larger datasets

2. Playerbot Scaling (if enabled)

   • Tune PLAYERBOT_MAX_BOTS in .env
   • Monitor memory usage: docker stats ac-worldserver

3. Network Configuration

   • Open firewall ports:
     • 3784 (authserver)
     • 8215 (worldserver)
   • Configure NAT/port forwarding for public access

---

📄 Project Credits

This project builds upon:

• AzerothCore - Core server application
• AzerothCore Module Community - Enhanced gameplay modules

Key Features

• ✅ Fully Automated Setup - Interactive configuration and deployment
• ✅ Intelligent Module System - Automatic source builds and profile selection
• ✅ Automated Backups - Health checks, scheduled backups, and monitoring
• ✅ Docker-Based - Containerized deployment for easy setup and portability
• ✅ Comprehensive Documentation - Clear setup and troubleshooting guides