2026-08-21 14:54:40 +00:00 · 2026-08-21 14:54:40 +00:00 · 67b9b2dde5
commit 67b9b2dde5
4 changed files with 1168 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,206 @@
+# 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).