AzerothCore-RealmMaster/README.md

# ac-compose Deployment Guide

This guide walks through the end-to-end deployment workflow for the `ac-compose` stack. It focuses on the supported automation scripts, the order in which to run them, the default services/ports that come online, and the optional manual steps you may need when enabling additional modules.


## 1. Prerequisites

Before you begin:

- **Docker** and **Docker Compose v2** installed on the host.
- A POSIX-compatible shell (the provided scripts target Bash).
- Sufficient disk space for game assets, module clones, and source builds ( ≈ 20 GB recommended).
- Network access to GitHub (or a local mirror) for cloning AzerothCore source and modules.

> Tip: If you use a distinct user/group mapping (e.g., NFS-backed storage) the setup wizard will let you pick non-root UIDs/GIDs.


## 2. Generate `.env` via `setup.sh`

All environment configuration lives in `ac-compose/.env`. Generate or refresh it by running:

```bash
./setup.sh
```

The wizard will ask you to confirm:

1. **Deployment type** (local, LAN, or public) – sets bind address and default ports.
2. **Filesystem ownership** for container volumes.
3. **Exterior ports** for Auth (default 3784), World (8215), SOAP (7778), and MySQL (64306).
4. **Storage path** (default `./storage`) and backup retention.
5. **Module preset**. The wizard defaults to a safe set (Solo LFG, Solocraft, Autobalance, Transmog, NPC Buffer, Learn Spells, Fireworks). Manual mode lets you toggle more modules, while warning you about unsafe or incompatible ones.

### Module notes from the wizard

- **AHBot** – remains disabled until the upstream module exports `Addmod_ahbotScripts()` (linker failure otherwise).
- **Quest Count Level** – disabled: relies on deprecated ConfigMgr calls and fails to compile.
- **Eluna** – bundled with AzerothCore by default. To disable the runtime later, edit the `AC_ELUNA_ENABLED` flag under “Eluna runtime” in `.env`.
- Other disabled modules (Individual Progression, Breaking News, TimeIsTime, Pocket Portal, Random Enchants, NPC Beastmaster/Enchanter, Instance Reset, etc.) require additional SQL, DBC, or in-game configuration. Inline comments in `.env` describe these requirements.

When the wizard completes, it writes the fully populated `.env`. Re-run `./setup.sh` anytime you want to regenerate the file; make backups first if you have custom edits.


## 3. (Optional) Clone AzerothCore Source

Certain modules require recompiling the AzerothCore core. If you plan to enable any of them, clone/update the source repository first:

```bash
./scripts/setup-source.sh
```

This script:

- Reads `MODULES_REBUILD_SOURCE_PATH` (default `./source/azerothcore`).
- Clones or updates the repository (uses the Playerbot fork if `MODULE_PLAYERBOTS=1`).
- Ensures the desired branch is checked out.

You can rerun it whenever you need to pull upstream updates.


## 4. Deploy with `deploy.sh`

Use `deploy.sh` to perform a full module-aware deployment. Example:

```bash
./deploy.sh --profile modules
```

What the script does:

1. Stops any running stack (unless `--keep-running` is supplied) to avoid container-name conflicts.
2. Runs the modules manager (`docker compose --profile db --profile modules up ac-modules`) to clone missing modules, apply configuration, and execute module SQL.
3. Rebuilds AzerothCore from source if any C++ modules are enabled. The helper also tags the freshly-built images as `acore/ac-wotlk-{worldserver,authserver}:modules-latest` for subsequent compose runs.
4. Stages the runtime profile by invoking `./scripts/stage-modules.sh --yes`.
5. Tails the `ac-worldserver` logs by default (omit with `--no-watch`).

Useful flags:

- `--profile {standard|playerbots|modules}` – force a specific services profile instead of auto-detecting by module toggles.
- `--skip-rebuild` – skip the source rebuild even if modules demand it (not recommended unless you are certain rebuilt images already exist).
- `--keep-running` – do not stop existing containers before syncing modules (use sparingly; stale `ac-db-import` containers can block the rebuild stage).
- `--no-watch` – exit after staging without tailing worldserver logs.

All Docker Compose commands run with the project name derived from `COMPOSE_PROJECT_NAME` in `.env` (default `ac-compose`).


### If you prefer a health check after deployment

Run:

```bash
./verify-deployment.sh --skip-deploy --quick
```

This script inspects container health states and key ports without altering the running stack.


## 5. Service Inventory & Default Ports

| Service / Container        | Role                                | Ports (host → container) | Profile(s)                 |
|----------------------------|-------------------------------------|--------------------------|----------------------------|
| `ac-mysql`                 | MySQL 8.0 database                  | `64306 → 3306`           | `db`                       |
| `ac-db-import`             | One-shot DB import/update           | –                        | `db`                       |
| `ac-db-init`               | Schema bootstrap helper             | –                        | `db`                       |
| `ac-authserver`            | Auth server (no modules)            | `3784 → 3724`            | `services-standard`        |
| `ac-worldserver`           | World server (no modules)           | `8215 → 8085`, `7778 → 7878` (SOAP) | `services-standard`        |
| `ac-authserver-modules`    | Auth server w/ custom build         | `3784 → 3724`            | `services-modules`         |
| `ac-worldserver-modules`   | World server w/ custom build        | `8215 → 8085`, `7778 → 7878` | `services-modules`       |
| `ac-authserver-playerbots` | Playerbots auth image               | `3784 → 3724`            | `services-playerbots`      |
| `ac-worldserver-playerbots`| Playerbots world image              | `8215 → 8085`, `7778 → 7878` | `services-playerbots`   |
| `ac-client-data-standard`  | Client-data fetcher                 | –                        | `client-data`              |
| `ac-modules`               | Module management / SQL executor    | –                        | `modules`                  |
| `ac-phpmyadmin`            | phpMyAdmin UI                       | `8081 → 80`              | `tools`                    |
| `ac-keira3`                | Keira3 world editor                 | `4201 → 8080`            | `tools`                    |

Additional services (e.g., backups, monitoring) can be enabled by editing `.env` and the compose file as needed.


## 6. Manual Tasks & Advanced Options

- **Disabling Eluna**: Eluna’s runtime flags live near the end of `.env`. Set `AC_ELUNA_ENABLED=0` if you do not want Lua scripting loaded.
- **Enabling experimental modules**: Edit `.env` toggles. Review the inline comments carefully—some modules require additional SQL, DBC patches, or configuration files before they work safely.
- **Custom `.env` variants**: You can create `.env.custom` files and run `docker compose --env-file` if you maintain multiple environments. The setup wizard always writes `./.env`.
- **Manual source rebuild**: If you prefer to rebuild without staging services, run `./scripts/rebuild-with-modules.sh --yes`. The script now stops and cleans up its own compose project to avoid lingering containers.
- **Health check**: `verify-deployment.sh` can also be run without `--skip-deploy` to bring up a stack and verify container states using the default profiles.


## 7. Clean-Up & Re-running

- To tear down everything: `docker compose --profile db --profile services-standard --profile services-playerbots --profile services-modules --profile client-data --profile modules --profile tools down`.
- To force the module manager to re-run (e.g., after toggling modules in `.env`): `docker compose --profile db --profile modules up --build ac-modules`.
- Storage (logs, configs, client data) lives under `./storage` by default; remove directories carefully if you need a clean slate.


## 8. Further Reading

For a full description of individual modules, sample workflows, or deeper dive into AzerothCore internals, consult the original **V1 README** and linked documentation inside the `V1/` directory. Those docs provide module-specific CMake and SQL references you can adapt if you decide to maintain custom forks.

---

You now have a repeatable, script-driven deployment process:

1. Configure once with `setup.sh`.
2. (Optional) Pull upstream source via `scripts/setup-source.sh`.
3. Deploy and stage via `deploy.sh`.
4. Verify with `verify-deployment.sh` or directly inspect `docker compose ps`.

Happy adventuring!