azerothcore-playerbots-installer/README.md

# AzerothCore + Playerbots Installer

A single script that takes a clean Ubuntu Server VM to a running AzerothCore
3.3.5a (Wrath of the Lich King) private server with the [Playerbots][playerbots]
fork, plus a handful of optional community modules — fully unattended after
you answer a short set of setup questions.

[playerbots]: https://github.com/mod-playerbots/azerothcore-wotlk

## What it installs

- **AzerothCore**, built from the [`mod-playerbots/azerothcore-wotlk`][pb-core]
  fork (`Playerbot` branch) — required for Playerbots support; the standard
  AzerothCore repo will not compile the module.
- **mod-playerbots** — populates the world with AI-controlled bot characters
  you can group with, fight alongside, or just watch go about their business.
- **mod-ah-bot** *(optional)* — keeps the auction house stocked and active.
- **mod-ollama-chat** *(optional)* — gives bots LLM-generated chat via an
  [Ollama](https://ollama.com) server, either installed locally by this
  script or pointed at one you already run elsewhere on your network.
- **mod-quest-loot-party** *(optional)* — lets every eligible party member
  receive a quest item drop, not just whoever loots first.
- **mod-breaking-news-override** *(optional)* — an announcement panel on the
  character-select screen, driven by a small HTML file you can edit later.

It also sets up:

- `authserver` / `worldserver` as **systemd services** (auto-start on boot,
  auto-restart on crash)
- Basic **MySQL tuning** sized to the VM's RAM
- **ufw firewall rules** for the game ports (optional, on by default)
- **Client data** (maps/vmaps/mmaps/dbc), downloaded pre-extracted via
  AzerothCore's own `bin/acore client-data` command — no WoW client needed
  for this step
- A **GM (admin) account**, created automatically
- Helper scripts: `restart-servers.sh` and (if you want it later) `soap-cmd.sh`
  for remote console commands
- A **summary file** in your home directory with every credential, path,
  and next step you'll need

[pb-core]: https://github.com/mod-playerbots/azerothcore-wotlk

## Requirements

- **Ubuntu Server 24.04** (other Ubuntu versions will likely work; nothing
  else is tested)
- A regular user with **sudo** access (not root)
- Recommended VM spec: **8 vCPU / 16GB RAM / 60GB+ disk** — see
  [Hardware sizing](#hardware-sizing) below for smaller/larger setups
- Outbound internet access (cloning repos, `apt`, downloading client data)

## Usage

```bash
git clone <this-repo-url>
cd azerothcore-playerbots-installer
chmod +x install.sh
```

**Run it inside `screen` or `tmux`.** The compile step alone can take
30–90+ minutes; if your SSH session drops, a bare foreground script dies
with it.

```bash
screen -S install
./install.sh
```

You'll be asked for:

- A MySQL password for the database user the server will use
- Build/thread counts (sensible defaults are suggested based on your CPU)
- Which optional modules to install
- Playerbots population size (min/max bots)
- Ollama connection details, if you want bot chat
- A GM account username/password
- Whether to open the game ports in `ufw`

Then it runs unattended. Detach from `screen` any time with `Ctrl+A`, `D`,
and reattach later with `screen -r install`.

When it finishes, everything you need is in:

```
~/azerothcore-server-info.txt
```

This file is `chmod 600`'d automatically since it contains real passwords.
**Treat it like a password file** — don't copy it somewhere world-readable.

## Resuming after a failure

Every step records its own completion in `~/.azerothcore-installer-state/`.
If the script dies partway through (compiler error, disconnected SSH,
out of disk, etc.), fix the underlying problem and just run it again:

```bash
./install.sh
```

Completed steps are skipped; the run picks up wherever it left off. You'll
be asked the setup questions again each time (they're cheap to answer), but
slow steps like the build or client-data download won't redo unnecessarily.

To force a specific step to redo, delete its marker:

```bash
rm ~/.azerothcore-installer-state/build
./install.sh
```

## Hardware sizing

| Bot count / use case | vCPU | RAM | Disk |
|---|---|---|---|
| Solo / small friends group, ~50-100 bots | 4 | 8GB | 40GB |
| Medium, ~200-300 bots | 6-8 | 16GB | 60GB |
| Large bot population / real player traffic | 8+ | 16-24GB | 80GB+ |

`worldserver`'s main loop is heavily single-core-performance dependent —
a modern CPU with fewer, faster cores tends to outperform more, slower
cores. `MapUpdate.Threads` (set automatically from your detected core
count, adjustable) generally shouldn't exceed cores minus 2.

## After install: things worth doing

**Confirm the realm address is right for how people will connect.** The
summary file fills in your best-guess public IP, but if you're behind a
home router (NAT), players outside your LAN need port forwarding for
3724/8085 on the router itself, and the `realmlist` table's `address`
needs to be the address actually reachable from where they're connecting
from:

```bash
mysql -u acore -p acore_auth -e "UPDATE realmlist SET address = 'YOUR_IP' WHERE id = 1;"
```

**AH Bot needs one manual step.** Because its buyer/seller acts through a
real character, and character creation requires an actual client login,
this can't be scripted headlessly. The summary file has the exact steps —
short version: create an account for it, log into the client once to make
a throwaway character, then point `mod_ahbot.conf` at that account's ID
and give the character some starting gold.

**SOAP remote admin is installed but disabled by default.** The
`soap-cmd.sh` helper script is generated either way, but `SOAP.Enabled`
is left at `0` in `worldserver.conf` — enabling a remote admin interface
by default felt like the wrong call for an unattended script to make on
your behalf. Flip it on in `worldserver.conf` when you actually want it,
and restrict the port at your firewall to trusted IPs rather than opening
it broadly (SOAP auth sends credentials unencrypted over plain HTTP).

**Consider restricting SSH, and MySQL/SOAP if you enable them, to known
IPs** rather than "Anywhere" in `ufw`, especially if this VM has a public
IP. The installer only opens the two game ports by default for this
reason.

## Why some things work the way they do

A few non-obvious lessons are baked into this script, worth knowing if
you're debugging or extending it:

- **`-DTOOLS_BUILD=db-only`, never `none`.** AzerothCore's `dbimport` tool
  is bundled under the same cmake flag as the map/vmap/mmap extractors.
  Setting it to `none` to skip the (slow, client-required) extractors also
  silently skips building `dbimport` itself — which then makes the
  database-import step fail with a confusing missing-file error several
  steps later, with no obvious link back to the build flag. `db-only`
  builds just the database tool; client data comes from `bin/acore
  client-data` instead (pre-extracted, no client needed).
- **Module SQL is never imported by hand.** Every module here relies on
  AzerothCore's own auto-updater to apply its SQL on first `worldserver`
  start, using a `updates` tracking table it manages itself. Manually
  running a module's `.sql` files against MySQL — even when a module's own
  README suggests it — desyncs that tracking table from actual database
  state, which shows up later as baffling "table already exists" or
  "table doesn't exist" crashes. Let the updater own its own bookkeeping.
- **Module config filenames are not consistent.** Some use hyphens
  (`mod-quest-loot-party.conf`), some underscores (`mod_ahbot.conf`,
  `mod_ollama_chat.conf`), one is just lowercase with neither
  (`breakingnews.conf`) — and none of these necessarily match the module's
  repository name. The filenames in this script were confirmed against
  real installs; if a module updates and renames its config, the relevant
  step will need updating too.
- **GM account creation needs the console, not raw SQL.** Account
  passwords are stored as an SRP6 salt+verifier pair, not a simple hash,
  so there's no safe direct-SQL way to create one. This script briefly
  stops the systemd-managed `worldserver`, drives an interactive console
  session via `expect`, and hands control back to systemd afterward.

## What this script won't do for you

- **Won't source a WoW client.** Not needed anyway — client data comes
  pre-extracted via `bin/acore client-data`.
- **Won't create the AH Bot's character** — see above, needs a real
  client login.
- **Won't harden the VM beyond basic firewall rules** — no fail2ban,
  no automatic security updates, no TLS in front of SOAP. Reasonable
  next steps for anything facing the open internet.
- **Won't set up backups.** Worth adding a periodic `mysqldump` of all
  databases once the server's running — bot activity and real player
  progress both live only in MySQL.

## License

MIT — see [LICENSE](LICENSE).