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
314
docs/CICD.md
Normal file
314
docs/CICD.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 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**:
|
||||
- Applies the **RealmMaster module profile** from `config/module-profiles/RealmMaster.json`
|
||||
- Creates `.env` with the configured modules enabled (32 modules)
|
||||
- Sets project name and configuration defaults
|
||||
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
|
||||
Reference in New Issue
Block a user