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 32GB+ 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 30+ available modules 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)

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

⚠️ Warning: Module preset support is still in progress. The bundled presets have not been fully tested yet—please share issues or suggestions via Discord (uprightbass360).

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

• Custom example:

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

• 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;

---

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
./scripts/bash/backup-export.sh [output_dir]                 # Export user accounts & characters
./scripts/bash/backup-import.sh [backup_dir]                 # Import user data from backup

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