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.

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

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

---

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.