mirror of
https://github.com/uprightbass360/AzerothCore-RealmMaster.git
synced 2026-01-13 00:58:34 +00:00
adds workflow build for RealmMaster profile
This commit is contained in:
uprightbass360
321
docs/CICD.md
Normal file
321
docs/CICD.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# 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` ✅ Built nightly
|
||||
- `<dockerhub-username>/azerothcore-realmmaster:authserver-realmmaster-YYYYMMDD` ✅ Built nightly
|
||||
- `<dockerhub-username>/azerothcore-realmmaster:worldserver-realmmaster-latest` ✅ Built nightly
|
||||
- `<dockerhub-username>/azerothcore-realmmaster:worldserver-realmmaster-YYYYMMDD` ✅ Built nightly
|
||||
|
||||
**Generic Tags** (backward compatibility, defaults to RealmMaster profile):
|
||||
- `<dockerhub-username>/azerothcore-realmmaster:authserver-latest` ✅ Built nightly
|
||||
- `<dockerhub-username>/azerothcore-realmmaster:worldserver-latest` ✅ Built nightly
|
||||
|
||||
**Other Profile Tags** (built on-demand via manual workflow trigger):
|
||||
- `authserver-suggested-modules-latest` - Available when built
|
||||
- `authserver-all-modules-latest` - Available when built
|
||||
- `authserver-playerbots-only-latest` - Available when built
|
||||
|
||||
**Note**: Only the RealmMaster profile is built automatically on schedule. Other profiles can be built by manually triggering the workflow with different profile names.
|
||||
|
||||
## 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
|
||||
339
docs/PREBUILT_IMAGES.md
Normal file
339
docs/PREBUILT_IMAGES.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# 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 profiles (available when built via GitHub Actions):
|
||||
- **`:authserver-suggested-modules-latest`** - Suggested modules profile (not yet published)
|
||||
- **`:authserver-all-modules-latest`** - All modules profile (not yet published)
|
||||
- **`:authserver-playerbots-only-latest`** - Playerbots only (not yet published)
|
||||
|
||||
**Note**: Currently only the RealmMaster profile is built nightly. Other profiles can be built on-demand by manually triggering the CI/CD workflow.
|
||||
|
||||
### 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
|
||||
213
docs/RELEASES.md
Normal file
213
docs/RELEASES.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Release Strategy
|
||||
|
||||
This document explains how AzerothCore RealmMaster releases work and what they contain.
|
||||
|
||||
## Release Philosophy
|
||||
|
||||
Since **Docker images are stored on Docker Hub**, GitHub releases serve as **deployment packages** rather than source distributions. Each release contains everything users need to deploy pre-built images without building from source.
|
||||
|
||||
## What's in a Release?
|
||||
|
||||
### Release Assets (ZIP Archive)
|
||||
|
||||
Each release includes a downloadable `.zip` file containing:
|
||||
|
||||
```
|
||||
azerothcore-realmmaster-v1.0.0-realmmaster.zip
|
||||
├── .env.prebuilt # Pre-configured for Docker Hub images
|
||||
├── docker-compose.yml # Service definitions
|
||||
├── deploy.sh # Deployment script
|
||||
├── status.sh # Status monitoring
|
||||
├── cleanup.sh # Cleanup utilities
|
||||
├── scripts/ # Required Python/Bash scripts
|
||||
├── config/ # Module manifest and presets
|
||||
├── docs/ # Complete documentation
|
||||
├── QUICKSTART.md # Release-specific quick start
|
||||
└── README.md # Project overview
|
||||
```
|
||||
|
||||
### Release Notes
|
||||
|
||||
Each release includes:
|
||||
- Module profile and count
|
||||
- Docker Hub image tags (date-specific and latest)
|
||||
- Quick start instructions
|
||||
- Complete module list
|
||||
- Build information (commit, date, source variant)
|
||||
- Links to documentation
|
||||
- Known issues
|
||||
|
||||
## Release Types
|
||||
|
||||
### 1. Profile-Based Releases
|
||||
|
||||
Each module profile gets its own release variant:
|
||||
|
||||
- **v1.0.0-realmmaster** - RealmMaster profile (32 modules, recommended)
|
||||
- **v1.0.0-suggested-modules** - Alternative suggested module set
|
||||
- **v1.0.0-all-modules** - All supported modules
|
||||
- **v1.0.0-playerbots-only** - Just playerbots
|
||||
|
||||
Users choose the release that matches their desired module set.
|
||||
|
||||
### 2. Version Numbering
|
||||
|
||||
We use semantic versioning:
|
||||
- **Major** (v1.0.0 → v2.0.0): Breaking changes, major feature additions
|
||||
- **Minor** (v1.0.0 → v1.1.0): New modules, feature enhancements
|
||||
- **Patch** (v1.0.0 → v1.0.1): Bug fixes, documentation updates
|
||||
|
||||
## Docker Hub Image Tags
|
||||
|
||||
Releases reference specific Docker Hub tags:
|
||||
|
||||
### Date-Tagged Images (Recommended for Production)
|
||||
```
|
||||
uprightbass360/azerothcore-realmmaster:authserver-realmmaster-20260109
|
||||
uprightbass360/azerothcore-realmmaster:worldserver-realmmaster-20260109
|
||||
```
|
||||
- **Immutable**: Never change
|
||||
- **Stable**: Guaranteed to match the release
|
||||
- **Recommended**: For production deployments
|
||||
|
||||
### Latest Tags (Auto-Updated)
|
||||
```
|
||||
uprightbass360/azerothcore-realmmaster:authserver-realmmaster-latest
|
||||
uprightbass360/azerothcore-realmmaster:worldserver-realmmaster-latest
|
||||
```
|
||||
- **Mutable**: Updated nightly by CI/CD
|
||||
- **Convenient**: Always get the newest build
|
||||
- **Use case**: Development, testing, staying current
|
||||
|
||||
## Creating a Release
|
||||
|
||||
### Automated (Recommended)
|
||||
|
||||
Use the GitHub Actions workflow:
|
||||
|
||||
1. Go to **Actions** → **Create Release**
|
||||
2. Click **Run workflow**
|
||||
3. Fill in:
|
||||
- **Version**: `v1.0.0`
|
||||
- **Profile**: `RealmMaster` (or other profile)
|
||||
- **Pre-release**: Check if beta/RC
|
||||
4. Click **Run workflow**
|
||||
|
||||
The workflow automatically:
|
||||
- Creates deployment package with all files
|
||||
- Generates release notes with module list
|
||||
- Uploads ZIP archive as release asset
|
||||
- Creates GitHub release with proper tags
|
||||
|
||||
### Manual
|
||||
|
||||
If you need to create a release manually:
|
||||
|
||||
```bash
|
||||
# 1. Tag the release
|
||||
git tag -a v1.0.0 -m "Release v1.0.0 - RealmMaster Profile"
|
||||
git push origin v1.0.0
|
||||
|
||||
# 2. Create deployment package
|
||||
./scripts/create-release-package.sh v1.0.0 RealmMaster
|
||||
|
||||
# 3. Create GitHub release
|
||||
# Go to GitHub → Releases → Draft a new release
|
||||
# - Tag: v1.0.0
|
||||
# - Title: RealmMaster v1.0.0 - RealmMaster Profile
|
||||
# - Upload: azerothcore-realmmaster-v1.0.0-realmmaster.zip
|
||||
# - Add release notes
|
||||
```
|
||||
|
||||
## Release Checklist
|
||||
|
||||
Before creating a release:
|
||||
|
||||
- [ ] Verify CI/CD build succeeded
|
||||
- [ ] Test Docker Hub images work correctly
|
||||
- [ ] Update CHANGELOG.md
|
||||
- [ ] Update version in documentation if needed
|
||||
- [ ] Verify all module SQL migrations are included
|
||||
- [ ] Test deployment on clean system
|
||||
- [ ] Update known issues section
|
||||
|
||||
## For Users: Using a Release
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Download release
|
||||
wget https://github.com/uprightbass360/AzerothCore-RealmMaster/releases/download/v1.0.0/azerothcore-realmmaster-v1.0.0-realmmaster.zip
|
||||
|
||||
# 2. Extract
|
||||
unzip azerothcore-realmmaster-v1.0.0-realmmaster.zip
|
||||
cd azerothcore-realmmaster-v1.0.0-realmmaster
|
||||
|
||||
# 3. Configure
|
||||
nano .env.prebuilt
|
||||
# Set: DOCKERHUB_USERNAME=uprightbass360
|
||||
|
||||
# 4. Deploy
|
||||
mv .env.prebuilt .env
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
### Upgrading Between Releases
|
||||
|
||||
```bash
|
||||
# 1. Backup your data
|
||||
./scripts/bash/backup.sh
|
||||
|
||||
# 2. Download new release
|
||||
wget https://github.com/.../releases/download/v1.1.0/...
|
||||
|
||||
# 3. Extract to new directory
|
||||
unzip azerothcore-realmmaster-v1.1.0-realmmaster.zip
|
||||
|
||||
# 4. Copy your .env and data
|
||||
cp old-version/.env new-version/.env
|
||||
cp -r old-version/storage new-version/storage
|
||||
|
||||
# 5. Deploy new version
|
||||
cd new-version
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
## Release Schedule
|
||||
|
||||
- **Nightly Builds**: Images built automatically at 2 AM UTC
|
||||
- **Releases**: Created as needed when significant changes accumulate
|
||||
- **LTS Releases**: Planned quarterly for long-term support
|
||||
|
||||
## Support
|
||||
|
||||
- **Release Issues**: https://github.com/uprightbass360/AzerothCore-RealmMaster/issues
|
||||
- **Documentation**: Included in each release ZIP
|
||||
- **Discord**: https://discord.gg/gkt4y2x
|
||||
|
||||
## FAQ
|
||||
|
||||
### Why are images on Docker Hub and not in releases?
|
||||
|
||||
Docker images can be 1-2GB each. GitHub has a 2GB file limit and releases should be lightweight. Docker Hub is designed for hosting images, GitHub releases are for deployment packages.
|
||||
|
||||
### Can I use latest tags in production?
|
||||
|
||||
We recommend **date-tagged images** for production (e.g., `authserver-realmmaster-20260109`). Latest tags are updated nightly and may have untested changes.
|
||||
|
||||
### How do I know which image version a release uses?
|
||||
|
||||
Check the release notes - they include the specific Docker Hub tags (date-stamped) that were tested with that release.
|
||||
|
||||
### What if I want to build from source instead?
|
||||
|
||||
Clone the repository and use `./setup.sh` + `./build.sh` instead of using pre-built releases. See [GETTING_STARTED.md](GETTING_STARTED.md) for instructions.
|
||||
|
||||
### Are releases required?
|
||||
|
||||
No! You can:
|
||||
1. **Use releases**: Download ZIP, deploy pre-built images (easiest)
|
||||
2. **Use nightly images**: Pull latest tags directly from Docker Hub
|
||||
3. **Build from source**: Clone repo, build locally (most flexible)
|
||||
|
||||
Releases are just convenient snapshots for users who want stability.
|
||||
Reference in New Issue
Block a user