nchebrov/AzerothCore-RealmMaster
1
0
Fork 0
mirror of https://github.com/uprightbass360/AzerothCore-RealmMaster.git synced 2026-01-13 09:07:20 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
8e7959d7fe57db35e88897648b99bed799a910c0
AzerothCore-RealmMaster/README.md
uprightbass360 8e7959d7fe made profiles better
2025-11-05 01:27:26 -05:00

53 KiB
Raw Blame History

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

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

🏗️ 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/
  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:

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
Reference in New Issue View Git Blame Copy Permalink