AzerothCore-RealmMaster/docs/GETTING_STARTED.md

Getting Started with AzerothCore RealmMaster

This guide provides a complete walkthrough for deploying AzerothCore RealmMaster on your local machine or remote server.

Note: All :port and credential information is based on default configuration and should be updated based on your settings. If you have any suggestions about how to make this documentation better, please file an issue and I will look into it.

Prerequisites

Before you begin, ensure you have:

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

Quick Overview

AzerothCore RealmMaster provides three deployment options:

1. Local Deployment - Deploy and run on your local machine
2. Remote Deployment - Build locally, deploy to a remote server
3. Standard/Playerbots/Modules - Choose your feature set

---

Local Deployment

Complete setup and deployment 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 hundreds of official modules (348 in manifest; 221 currently supported) or use presets
• Module Definitions: Customize defaults in config/module-manifest.json and optional presets under config/module-profiles/
• 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 (modules with "type": "cpp" in config/module-manifest.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)
• --remote-clean-containers - Stop/remove existing ac-* containers and project images during migration
• --remote-skip-env - Leave the remote .env untouched (won't upload local one)
• --remote-preserve-containers - Do not stop/remove existing ac-* containers/images during migration
• --remote-storage-path /mnt/acore-storage - Override STORAGE_PATH on the remote host (local-storage stays per .env)
• --remote-container-user 1001:1001 - Override CONTAINER_USER on the remote host (uid:gid)
  • Note: do not combine --remote-clean-containers with --remote-preserve-containers; the flags are mutually exclusive.

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 config/module-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:

  • config/module-profiles/RealmMaster.json – 33-module baseline used for testing.
  • config/module-profiles/suggested-modules.json – light AzerothCore QoL stack without playerbots.
  • config/module-profiles/playerbots-suggested-modules.json – suggested QoL stack plus playerbots.
  • config/module-profiles/azerothcore-vanilla.json – pure AzerothCore (no optional modules).
  • config/module-profiles/playerbots-only.json – playerbot prerequisites only (tune bot counts separately).
  • config/module-profiles/all-modules.json – enable everything currently marked supported/active (not recommended).

• Module metadata lives in config/module-manifest.json; update that file if you need to add new modules or change repositories/branches.

---

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;

Spawn Custom NPCs

The server includes 14 custom NPCs providing enhanced functionality. Use GM commands to spawn them at appropriate locations:

# Quick reference - spawn essential NPCs
.npc add 199999    # Kaylub - Free Professions
.npc add 601015    # Beauregard - Enchanter
.npc add 601016    # Buffmaster - Player Buffs
.npc add 601026    # White Fang - BeastMaster
.npc add 190010    # Warpweaver - Transmog

# See complete guide with coordinates and functions

📖 For complete spawn commands, coordinates, and NPC functionality details, see docs/NPCS.md

---

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/bash/stop-containers.sh

# Start services
./scripts/bash/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/bash/stage-modules.sh                    # Download enabled modules
./scripts/bash/setup-source.sh                     # Initialize AzerothCore source
./scripts/bash/copy-module-configs.sh              # Create module .conf files
./scripts/bash/manage-modules-sql.sh               # Execute module SQL scripts

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

Container Management

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

# Stop services gracefully
./scripts/bash/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/bash/verify-deployment.sh --skip-deploy --quick

# Full deployment verification
./scripts/bash/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
# Export user accounts & characters to a named directory
./scripts/bash/backup-export.sh storage/backups/ExportBackup_manual_$(date +%Y%m%d_%H%M%S)

# Import data from a directory that contains the SQL dumps
./scripts/bash/backup-import.sh --backup-dir storage/backups/ExportBackup_20241029_120000 --password azerothcore123

# View available backups
ls -la storage/backups/

---

Next Steps

After completing the installation, consider these additional steps:

In-Game Setup

1. Create GM Account and test module functionality
2. Configure Realmlist for public access if needed
3. Test Modules - Verify enabled modules are working properly

Server Administration

1. Set Up Monitoring with ./status.sh --watch
2. Configure Backups and test backup/restore procedures
3. Customize Modules by editing configs in storage/config/mod_*.conf
4. Add Lua Scripts in storage/lua_scripts/ for custom functionality

Performance Tuning

1. Database Optimization - Adjust MySQL settings in .env
2. Playerbot Scaling - Tune bot limits and monitor resources
3. Network Configuration - Open firewall ports and configure NAT

For detailed information about troubleshooting, architecture, and advanced configuration, see the complete documentation referenced in the main README.md file.

---

Important Notes

• First deployment takes 30-60 minutes for database setup and client data download
• Subsequent starts are much faster due to intelligent backup restoration
• Use Ctrl+P, Ctrl+Q to detach from containers (NOT Ctrl+C which stops the server)
• Module presets help quickly configure common setups
• Remote deployment keeps builds local while deploying remotely

For troubleshooting and advanced configuration options, refer to the main project documentation.