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

adds workflow build for RealmMaster profile

Browse Source
This commit is contained in:
uprightbass360
2026-01-09 18:18:11 -05:00
parent ce76769f79
commit ae23bc2146
6 changed files with 1381 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
docs/CICD.md Normal file
View File

@@ -0,0 +1,316 @@
# CI/CD Documentation
This document describes the continuous integration and deployment workflows configured for the AzerothCore RealmMaster project.
## Build and Publish Workflow
The `build-and-publish.yml` workflow automatically builds AzerothCore with your configured modules and publishes Docker images to Docker Hub.
### Trigger Schedule
- **Nightly builds**: Runs automatically at 2 AM UTC every day
- **Manual trigger**: Can be triggered manually via GitHub Actions UI with optional force rebuild
### What It Does
1. **Checks out the repository** - Gets the RealmMaster project code
2. **Sets up Git** - Configures git for module repository cloning
3. **Sets up Docker Buildx** - Enables optimized Docker builds
4. **Logs in to Docker Hub** - Authenticates for image publishing
5. **Prepares the build environment**:
- Runs `./setup.sh --non-interactive --module-config RealmMaster --force`
- Uses the same setup process as local builds (ensures consistency)
- Applies the **RealmMaster module profile** from `config/module-profiles/RealmMaster.json`
- Creates `.env` with proper paths and configured modules (32 modules)
- Automatically selects correct source variant (standard or playerbots)
6. **Caches build artifacts** to speed up subsequent builds:
- Go build cache (`.gocache`)
- Source repository (`local-storage/source`)
7. **Sets up Python 3.11** - Required for module management scripts
8. **Runs `./build.sh --yes`** - This is where the magic happens:
- **Step 1**: Sets up the AzerothCore source repository
- **Step 2**: Detects build requirements
- **Step 3**: Syncs module metadata
- **Step 4**: **Fetches all module repositories** - Automatically clones all 32 enabled module repos from GitHub
- **Step 5**: **Compiles AzerothCore** with all fetched modules integrated
- **Step 6**: Tags the compiled images
9. **Tags images for Docker Hub** - Prepares `latest` and date-based tags
10. **Pushes images to Docker Hub** - Publishes the built images
11. **Generates a build summary** - Shows enabled modules and published images
### Module Fetching Process
The workflow **automatically fetches all module repositories** during the build. Here's how it works:
- The `build.sh` script reads the enabled modules from `.env` (set by the RealmMaster profile)
- For each enabled module, it clones the repository from GitHub (all modules are public repos)
- Module repositories are cloned into the AzerothCore source tree under `modules/`
- Examples of fetched repositories:
- `mod-playerbots` from https://github.com/mod-playerbots/mod-playerbots.git
- `mod-transmog` from https://github.com/azerothcore/mod-transmog.git
- `mod-solo-lfg` from https://github.com/azerothcore/mod-solo-lfg.git
- ...and 29 more
**No manual module setup required!** The build process handles everything automatically.
### Published Images
The workflow publishes images with **profile-specific tags** so you know exactly which modules are included:
**Profile-Tagged Images** (recommended):
- `<dockerhub-username>/azerothcore-realmmaster:authserver-realmmaster-latest`
- `<dockerhub-username>/azerothcore-realmmaster:authserver-realmmaster-YYYYMMDD`
- `<dockerhub-username>/azerothcore-realmmaster:worldserver-realmmaster-latest`
- `<dockerhub-username>/azerothcore-realmmaster:worldserver-realmmaster-YYYYMMDD`
**Generic Tags** (backward compatibility, defaults to RealmMaster profile):
- `<dockerhub-username>/azerothcore-realmmaster:authserver-latest`
- `<dockerhub-username>/azerothcore-realmmaster:worldserver-latest`
The profile name in the tag tells you which module set is included (e.g., `realmmaster`, `suggested-modules`, `all-modules`).
## Required GitHub Secrets
To enable the build and publish workflow, you must configure the following secrets in your GitHub repository:
### Setting Up Secrets
1. Go to your GitHub repository
2. Click **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret**
4. Add the following secrets:
#### DOCKERHUB_USERNAME
Your Docker Hub username.
**Example**: `yourusername`
#### DOCKERHUB_TOKEN
A Docker Hub access token (recommended) or your Docker Hub password.
**How to create a Docker Hub access token**:
1. Log in to [Docker Hub](https://hub.docker.com/)
2. Click on your username in the top right → **Account Settings**
3. Go to **Security** → **Personal Access Tokens** → **Generate New Token**
4. Give it a description (e.g., "GitHub Actions")
5. Set permissions: **Read & Write**
6. Click **Generate**
7. Copy the token (you won't be able to see it again)
8. Add this token as the `DOCKERHUB_TOKEN` secret in GitHub
## Module Configuration
### Default Profile: RealmMaster
The workflow uses the **RealmMaster** module profile by default, which includes 32 carefully selected modules:
- MODULE_PLAYERBOTS - AI-controlled player characters
- MODULE_TRANSMOG - Transmogrification system
- MODULE_SOLO_LFG - Solo dungeon finder
- MODULE_NPC_BUFFER - Buff NPC
- MODULE_ELUNA - Lua scripting engine
- MODULE_AIO - All-in-one interface
- ...and 26 more modules
See the full list in `config/module-profiles/RealmMaster.json`.
### Customizing the Module Profile
To use a different module profile in the CI/CD workflow:
1. **Choose or create a profile** in `config/module-profiles/`:
- `RealmMaster.json` - Default (32 modules)
- `suggested-modules.json` - Alternative suggested set
- `playerbots-only.json` - Just playerbots
- `all-modules.json` - All supported modules
- Create your own JSON file
2. **Edit the workflow** at `.github/workflows/build-and-publish.yml`:
```yaml
# Change this line in the "Prepare build environment" step:
python3 scripts/python/apply_module_profile.py RealmMaster \
# To use a different profile:
python3 scripts/python/apply_module_profile.py suggested-modules \
```
3. **Update the build summary** (optional):
```yaml
# Change this line in the "Build summary" step:
echo "- **Module Profile**: RealmMaster" >> $GITHUB_STEP_SUMMARY
# To:
echo "- **Module Profile**: suggested-modules" >> $GITHUB_STEP_SUMMARY
```
### Testing Module Profiles Locally
You can test the module profile script locally before committing:
```bash
# List modules that will be enabled
python3 scripts/python/apply_module_profile.py RealmMaster --list-modules
# Apply a profile to create .env
python3 scripts/python/apply_module_profile.py RealmMaster
# Verify the result
grep '^MODULE_.*=1' .env | wc -l
```
## Cache Strategy
The workflow uses GitHub Actions cache to speed up builds:
- **Go build cache**: Cached in `.gocache` directory
- **Source repository**: Cached in `local-storage/source` directory
This significantly reduces build times for subsequent runs.
## Manual Workflow Trigger
To manually trigger the workflow:
1. Go to **Actions** tab in your GitHub repository
2. Click on **Build and Publish** workflow
3. Click **Run workflow**
4. **Choose module profile** (default: RealmMaster):
- Enter profile name (e.g., `RealmMaster`, `suggested-modules`, `all-modules`, `playerbots-only`)
- Profile must exist in `config/module-profiles/`
5. Optionally check **Force rebuild** to rebuild even if no changes detected
6. Click **Run workflow**
The workflow will build with the selected profile and tag images accordingly (e.g., `authserver-realmmaster-latest` for RealmMaster profile).
## Troubleshooting
### Build fails with "missing required command"
The workflow runs on Ubuntu and has Docker and Python 3.11 pre-installed. If you see missing command errors, ensure the build script dependencies are available.
### Authentication errors
If you see Docker Hub authentication errors:
- Verify `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` secrets are set correctly
- Ensure the Docker Hub token has **Read & Write** permissions
- Check that the token hasn't expired
### Build timeout
The workflow has a 120-minute timeout. If builds consistently exceed this:
- Consider optimizing the build process
- Check if all module sources are accessible
- Review cache effectiveness
## Using Pre-Built Images
After images are published to Docker Hub, users can deploy RealmMaster **without building locally**!
### For End Users
See the complete guide at **[docs/PREBUILT_IMAGES.md](PREBUILT_IMAGES.md)** for step-by-step instructions.
**Quick start for users**:
```bash
# Clone the repository
git clone https://github.com/uprightbass360/AzerothCore-RealmMaster.git
cd AzerothCore-RealmMaster
# Use pre-built configuration
cp .env.prebuilt .env
# Edit .env and set DOCKERHUB_USERNAME=your-dockerhub-username
# Deploy (no build required!)
./deploy.sh
```
### For Developers
To test the published images:
```bash
# Pull latest RealmMaster profile images
docker pull <dockerhub-username>/azerothcore-realmmaster:authserver-realmmaster-latest
docker pull <dockerhub-username>/azerothcore-realmmaster:worldserver-realmmaster-latest
# Or pull specific date-tagged images
docker pull <dockerhub-username>/azerothcore-realmmaster:authserver-realmmaster-20260109
docker pull <dockerhub-username>/azerothcore-realmmaster:worldserver-realmmaster-20260109
# Or use generic latest tags (defaults to RealmMaster profile)
docker pull <dockerhub-username>/azerothcore-realmmaster:authserver-latest
docker pull <dockerhub-username>/azerothcore-realmmaster:worldserver-latest
```
### Pre-Built Configuration File
The `.env.prebuilt` template provides a minimal configuration that:
- References Docker Hub images instead of local builds
- Removes all build-related variables
- Includes only runtime configuration
- Is ready to use with minimal editing (just set DOCKERHUB_USERNAME)
**Benefits of pre-built images**:
- ✅ Skip 15-45 minute build time
- ✅ No build dependencies required
- ✅ Same 32 RealmMaster modules included
- ✅ Automatic nightly updates available
- ✅ Date-tagged versions for stability
- ✅ Profile-tagged images for clear identification
## Building Multiple Profiles
You can build different module profiles by manually triggering the workflow:
### Example: Build All Modules Profile
1. Go to **Actions** → **Build and Publish**
2. Click **Run workflow**
3. Set **module_profile** to `all-modules`
4. Click **Run workflow**
This will create:
- `authserver-all-modules-latest`
- `authserver-all-modules-YYYYMMDD`
- `worldserver-all-modules-latest`
- `worldserver-all-modules-YYYYMMDD`
### Creating Custom Profile Builds
To build a custom profile:
1. **Create profile JSON** in `config/module-profiles/my-custom-profile.json`:
```json
{
"modules": [
"MODULE_PLAYERBOTS",
"MODULE_TRANSMOG",
"MODULE_SOLO_LFG"
],
"label": "My Custom Profile",
"description": "Custom module selection",
"order": 100
}
```
2. **Trigger workflow** with profile name `my-custom-profile`
3. **Images created**:
- `authserver-my-custom-profile-latest`
- `worldserver-my-custom-profile-latest`
### Scheduled Builds
The nightly scheduled build always uses the **RealmMaster** profile. To schedule builds for different profiles, you can:
1. Create additional workflow files (e.g., `.github/workflows/build-all-modules.yml`)
2. Set different cron schedules
3. Hardcode the profile name in the workflow

337
docs/PREBUILT_IMAGES.md Normal file
View File

@@ -0,0 +1,337 @@
# Deploying Pre-Built RealmMaster Images
This guide explains how to deploy AzerothCore RealmMaster using pre-built Docker images from Docker Hub. **No local building required!**
## What's Included in Pre-Built Images
The pre-built images are automatically built nightly with the **RealmMaster module profile**, which includes **32 carefully selected modules**:
- **MODULE_PLAYERBOTS** - AI-controlled player characters
- **MODULE_TRANSMOG** - Transmogrification system
- **MODULE_SOLO_LFG** - Solo dungeon finder
- **MODULE_ELUNA** - Lua scripting engine
- **MODULE_AIO** - All-in-one interface
- **MODULE_NPC_BUFFER** - Buff NPC
- **MODULE_NPC_BEASTMASTER** - Pet management
- **MODULE_SOLOCRAFT** - Solo dungeon scaling
- **MODULE_1V1_ARENA** - 1v1 arena system
- **MODULE_ACCOUNT_ACHIEVEMENTS** - Account-wide achievements
- ...and 22 more modules!
See `config/module-profiles/RealmMaster.json` for the complete list.
## Prerequisites
- Docker with Docker Compose v2
- 16GB+ RAM
- 64GB+ storage
- Linux/macOS/WSL2
## Quick Start
### 1. Clone the Repository
```bash
git clone https://github.com/uprightbass360/AzerothCore-RealmMaster.git
cd AzerothCore-RealmMaster
```
### 2. Create Configuration File
```bash
# Copy the pre-built images template
cp .env.prebuilt .env
```
### 3. Configure Docker Hub Username
Edit `.env` and set your Docker Hub username:
```bash
# Change this line:
DOCKERHUB_USERNAME=your-dockerhub-username
# To (example):
DOCKERHUB_USERNAME=uprightbass360
```
### 4. Optional: Customize Settings
Edit `.env` to customize:
- **Server address**: `SERVER_ADDRESS=your-server-ip`
- **Passwords**: `MYSQL_ROOT_PASSWORD=your-password`
- **Playerbot population**: `PLAYERBOT_MIN_BOTS` and `PLAYERBOT_MAX_BOTS`
- **Server preset**: `SERVER_CONFIG_PRESET=fast-leveling` (or blizzlike, hardcore-pvp, casual-pve)
### 5. Deploy
```bash
./deploy.sh
```
The deployment will:
- Pull pre-built images from Docker Hub
- Set up MySQL database with all module SQL
- Configure client data
- Start all services
**First deployment takes 30-60 minutes** for database setup and client data download.
## Image Tags
The CI/CD workflow publishes images with **profile-specific tags** so you know exactly which modules are included:
### Profile-Tagged Images (Recommended)
Each module profile gets its own tag:
- **`:authserver-realmmaster-latest`** - RealmMaster profile (32 modules)
- **`:worldserver-realmmaster-latest`** - RealmMaster profile (32 modules)
- **`:authserver-realmmaster-YYYYMMDD`** - Date-tagged RealmMaster builds
- **`:worldserver-realmmaster-YYYYMMDD`** - Date-tagged RealmMaster builds
Other available profiles (if built):
- **`:authserver-suggested-modules-latest`** - Suggested modules profile
- **`:authserver-all-modules-latest`** - All modules profile
- **`:authserver-playerbots-only-latest`** - Playerbots only
### Generic Tags (Backward Compatibility)
- **`:authserver-latest`** - Latest build (defaults to RealmMaster profile)
- **`:worldserver-latest`** - Latest build (defaults to RealmMaster profile)
### Choosing a Profile
In `.env.prebuilt`, set the `MODULE_PROFILE` variable:
```bash
# Choose your profile
MODULE_PROFILE=realmmaster # 32 modules (default, recommended)
# MODULE_PROFILE=suggested-modules # Alternative module set
# MODULE_PROFILE=all-modules # All supported modules
# MODULE_PROFILE=playerbots-only # Just playerbots
# Images automatically reference the selected profile
AC_AUTHSERVER_IMAGE_MODULES=${DOCKERHUB_USERNAME}/${COMPOSE_PROJECT_NAME}:authserver-${MODULE_PROFILE}-latest
AC_WORLDSERVER_IMAGE_MODULES=${DOCKERHUB_USERNAME}/${COMPOSE_PROJECT_NAME}:worldserver-${MODULE_PROFILE}-latest
```
### Using Date-Tagged Images
To pin to a specific build date, edit `.env`:
```bash
# Set your profile
MODULE_PROFILE=realmmaster
# Pin to a specific date (example: January 9, 2026)
AC_AUTHSERVER_IMAGE_MODULES=${DOCKERHUB_USERNAME}/${COMPOSE_PROJECT_NAME}:authserver-${MODULE_PROFILE}-20260109
AC_WORLDSERVER_IMAGE_MODULES=${DOCKERHUB_USERNAME}/${COMPOSE_PROJECT_NAME}:worldserver-${MODULE_PROFILE}-20260109
```
## Differences from Local Build
### What You DON'T Need
When using pre-built images, you **skip**:
- ❌ Running `./setup.sh` (module selection)
- ❌ Running `./build.sh` (compilation)
- ❌ 15-45 minute build time
- ❌ Build dependencies (Go compiler, etc.)
### What's the Same
Everything else works identically:
- ✅ Database setup and migrations
- ✅ Module SQL installation
- ✅ Configuration management
- ✅ Backup system
- ✅ All management commands
- ✅ phpMyAdmin and Keira3 tools
## Verifying Your Deployment
After deployment completes:
### 1. Check Container Status
```bash
./status.sh
```
You should see all services running:
- ✅ ac-mysql
- ✅ ac-authserver
- ✅ ac-worldserver
- ✅ ac-phpmyadmin
- ✅ ac-keira3
### 2. Verify Modules Are Loaded
Check the worldserver logs:
```bash
docker logs ac-worldserver | grep "module"
```
You should see messages about 32 modules being loaded.
### 3. Access Management Tools
- **phpMyAdmin**: http://localhost:8081
- **Keira3**: http://localhost:4201
## Post-Installation
### Create Admin Account
1. Attach to the worldserver container:
```bash
docker attach ac-worldserver
```
2. Create an account and set GM level:
```
account create admin password
account set gmlevel admin 3 -1
```
3. Detach: Press `Ctrl+P` then `Ctrl+Q`
### Configure Client
Edit your WoW 3.3.5a client's `realmlist.wtf`:
```
set realmlist 127.0.0.1
```
(Replace `127.0.0.1` with your server's IP if remote)
## Updating to Latest Images
To update to the latest nightly build:
```bash
# Pull latest images
docker compose pull
# Restart services
docker compose down
docker compose up -d
```
**Note**: Database schema updates will be applied automatically on restart.
## Switching Between Pre-Built and Local Build
### From Pre-Built to Local Build
If you want to customize modules and build locally:
```bash
# Remove pre-built .env
rm .env
# Run interactive setup
./setup.sh
# Build with your custom modules
./build.sh
# Deploy
./deploy.sh
```
### From Local Build to Pre-Built
If you want to use pre-built images instead:
```bash
# Back up your current .env
mv .env .env.custom
# Use pre-built configuration
cp .env.prebuilt .env
# Edit DOCKERHUB_USERNAME in .env
# Deploy
./deploy.sh
```
## Troubleshooting
### Image Pull Errors
**Problem**: `Error response from daemon: manifest not found`
**Solutions**:
1. Verify `DOCKERHUB_USERNAME` is set correctly in `.env`
2. Check that the images exist at: https://hub.docker.com/u/your-username
3. Ensure the CI/CD workflow has run successfully
### Module SQL Not Applied
**Problem**: Modules don't seem to be working
**Solution**: The module SQL is automatically applied during deployment. Check:
```bash
# Verify module SQL staging
ls -la storage/module-sql-updates/
# Check database for module tables
docker exec -it ac-mysql mysql -uroot -p${MYSQL_ROOT_PASSWORD} -e "SHOW TABLES" acore_world | grep -i module
```
### Performance Issues
**Problem**: Server is slow or laggy
**Solutions**:
1. Increase MySQL tmpfs size in `.env`: `MYSQL_RUNTIME_TMPFS_SIZE=16G`
2. Reduce playerbot population: `PLAYERBOT_MAX_BOTS=100`
3. Check system resources: `docker stats`
## Advanced Configuration
### Custom Module Selection
Pre-built images include all RealmMaster modules. To disable specific modules:
1. Edit server configuration files in `storage/config/`
2. Set module enable flags to 0
3. Restart worldserver: `docker compose restart ac-worldserver`
**Note**: You can only disable modules, not add new ones (requires local build).
### Server Configuration Presets
Apply configuration presets for different server types:
```bash
# In .env, set one of these presets:
SERVER_CONFIG_PRESET=blizzlike # Authentic WotLK experience (1x rates)
SERVER_CONFIG_PRESET=fast-leveling # 3x XP rates, QoL improvements
SERVER_CONFIG_PRESET=hardcore-pvp # Competitive PvP (1.5x rates)
SERVER_CONFIG_PRESET=casual-pve # Relaxed PvE (2x rates)
```
Restart after changing: `docker compose restart ac-worldserver`
## Getting Help
- **Documentation**: See other guides in `docs/`
- **GitHub Issues**: https://github.com/uprightbass360/AzerothCore-RealmMaster/issues
- **AzerothCore Discord**: https://discord.gg/gkt4y2x
## Next Steps
- [Database Management](DATABASE_MANAGEMENT.md) - Backups, restores, migrations
- [Getting Started Guide](GETTING_STARTED.md) - Detailed walkthrough
- [Troubleshooting](TROUBLESHOOTING.md) - Common issues and solutions
- [Module Catalog](MODULES.md) - Complete list of available modules