AzerothCore RealmMaster

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

Table of Contents

• Quick Start
• What You Get
• Getting Started
  • Local Deployment
  • Remote Deployment
  • Post-Installation Steps
• Complete Module Catalog
• Management & Operations
  • Common Workflows
  • Management Commands
  • Database Operations
• Advanced Configuration
  • Architecture Overview
  • Build System
  • Custom Configuration
• Script Reference
• Troubleshooting
• Credits & Next Steps

---

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. Deploy (if using modules/playerbots) and deploy
./build.sh    # Optional - Will be triggered if required in deploy. c++ modules require compilation
./deploy.sh   # Always required - Supports ssh remote deploy or local
./status.sh   # Optional - Shows health and accesibility of all containers and current user data

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

See Getting Started for detailed walkthrough.

---

What You Get

✅ Core Server Components

• AzerothCore 3.3.5a - WotLK server application with 93+ enhanced modules
• MySQL 8.0 - Database with intelligent initialization and restoration
• Smart Module System - Automated module management and source builds
• phpMyAdmin - Web-based database administration
• Keira3 - Game content editor and developer tools

✅ 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
• Service Orchestration - Profile-based deployment (standard/playerbots/modules)

---

Getting Started

Complete walkthrough for deploying on your local machine or remote server.

Local Deployment

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

• Define JSON presets in profiles/*.json. Each file contains:

  • modules (array, required) – list of MODULE_* identifiers to enable.
  • label (string, optional) – text shown in the setup menu (emoji welcome).
  • description (string, optional) – short help text for maintainers.
  • order (number, optional) – determines the menu position (lower appears first). Example:

  {
    "modules": ["MODULE_ELUNA", "MODULE_SOLO_LFG", "MODULE_SOLOCRAFT"],
    "label": "⭐ Suggested Modules",
    "description": "Baseline solo-friendly quality of life mix",
    "order": 1
  }
  

• 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.json – default solo-friendly QoL stack.
  • profiles/playerbots-suggested-modules.json – suggested stack plus playerbots.
  • profiles/playerbots-only.json – playerbot-focused profile (adjust --playerbot-max-bots).

• Custom example:

  • profiles/sam.json – Sam's playerbot-focused profile (set --playerbot-max-bots 3000 when using this preset).

Post-Installation Steps

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!)

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

Configure Server for Public Access

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

See Next Steps After Installation for detailed setup and administration guidance.

---

Complete Module Catalog

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

---

Management & Operations

Essential commands and workflows for operating your AzerothCore server.

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

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

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

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

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/

---

Advanced Configuration

Technical details for advanced users and system administrators.

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.

Build System

The build system is optimized for development and production deployments with Docker multi-stage builds and caching.

Build Configuration:

• Automated dependency resolution and compilation
• Multi-stage Docker builds for optimal image sizes
• Build artifact caching for faster rebuilds
• Support for custom patches and modifications

Custom Configuration

Advanced customization options for specialized deployments and development environments.

Configuration Options:

• Environment-specific overrides in docker-compose.override.yml
• Custom module loading and configuration
• Database schema modifications and patches
• Network and security configuration

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 profile, check profiles directory
./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)

---

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

Credits & Next Steps

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

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