A Docker setup for CMaNGOS
cmangos-deploy is a Docker-based solution for running CMaNGOS that focuses on providing a streamlined and user-friendly experience. It is largely based on vmangos-deploy and offers a range of features that simplify managing a CMaNGOS setup:
- Prebuilt Docker images for both
amd64andarm64, leveraging GitHub Actions: simply pull the provided images that have been optimized for size, performance and stability instead of having to re-compile CMaNGOS yourself every time you want to update. - Support for all three CMaNGOS expansions: Classic, TBC and WotLK are each available as separate prebuilt images.
- Built-in Playerbots support: bots can be spawned on demand, or they can populate the world automatically.
- Seamless, automated database migrations: when pulling the latest Docker images and re-creating the containers, migrations are applied automatically to keep your database up to date at all times.
- A transparent and easy-to-follow user experience: the number of different commands that need to be run to install and manage CMaNGOS is kept to a minimum. You can use the Docker CLI or any other tool that is able to manage Docker containers.
- A clean and organized structure: the CMaNGOS configuration for each
expansion can be found in
./config/<expansion>, everything else that is shared between the Docker containers and your host system lives inside./storage/<expansion>.
Note
The Docker images are built on a daily schedule, unless there have been no new commits to CMaNGOS since the last build. Additionally, every Monday, the latest images are rebuilt to ensure software and dependencies are up to date, even if there have been no updates to CMaNGOS itself.
- Docker (including Compose V2)
If you have a coding agent like Claude Code or Codex installed, you can try a prompt similar to the following one to have it assist you with the installation process:
Help me install and set up https://github.com/mserajnik/cmangos-deploy.
First, clone the repository and read the README carefully.
Then guide me through the installation process step by step, following the
README closely.
Do as much of the setup yourself as you safely can so that I only have to step
in when a manual action or personal preference is required.
Ask me about my preferences whenever a choice has to be made, explain the
relevant options clearly, and tailor your instructions to the OS I am using.
Assume that I am not familiar with CMaNGOS or Docker and that I have not read
the README myself.
For steps that I need to perform manually, give me clear instructions and exact
commands where appropriate.
Do not assume user-facing choices such as the expansion, optional services, or
networking-related preferences. Ask me whenever the README presents a
meaningful choice.
For settings that the README, the Docker Compose configuration, or the CMaNGOS
example configuration files indicate should generally be left alone, keep the
documented defaults unless I explicitly ask for something else.
Do not change settings that the README, the Docker Compose configuration, or
the CMaNGOS example configuration files indicate should not be changed.
The exact prompt that works best may vary depending on the coding agent and model you use.
Caution
You use coding agents at your own risk. You are responsible for the
permissions and access you give them. The maintainer of this project is not
liable for any damage or data loss resulting from their use. Take appropriate
precautions such as sandboxed access and limited permissions, and do not run
them with --yolo or similar options that bypass safety checks.
First, clone the repository:
git clone https://github.com/mserajnik/cmangos-deploy.git
cd cmangos-deploycmangos-deploy supports three expansions, each with its own configuration
directory under ./config:
./config/classicfor Classic./config/tbcfor TBC./config/wotlkfor WotLK
Pick the one matching the expansion you want to run and create copies of the provided CMaNGOS example configuration files in that directory. For example, for Classic:
cp ./config/classic/mangosd.conf.example ./config/classic/mangosd.conf
cp ./config/classic/realmd.conf.example ./config/classic/realmd.conf
cp ./config/classic/ahbot.conf.example ./config/classic/ahbot.conf
cp ./config/classic/aiplayerbot.conf.example ./config/classic/aiplayerbot.conf
cp ./config/classic/anticheat.conf.example ./config/classic/anticheat.conf
cp ./config/classic/mods.conf.example ./config/classic/mods.confFor TBC and WotLK, the same applies with tbc or wotlk substituted for
classic. Note that mods.conf.example only ships for Classic; it does not
exist for TBC or WotLK.
Next, adjust the configuration files you have just created for your desired
setup. The default configuration should work well as a starting point, but you
may still want to adjust certain things such as the GameType, the RealmZone
or Anticheat.* and Warden.* options. Descriptions are provided for each
option in the configuration files, so you should be able to find your way
around easily.
Note
The bundled aiplayerbot.conf.example disables auto-spawning random bots by
default (AiPlayerbot.RandomBotAutologin = 0) and the bundled
ahbot.conf.example disables AHBot by default
(AuctionHouseBot.Chance.Sell = 0 and AuctionHouseBot.Chance.Buy = 0).
Both can be re-enabled by adjusting the marked options. Players can still
spawn bots manually via the in-game command regardless.
Caution
Options relating to certain things that cmangos-deploy relies on to work
correctly (like the database connections or configured directories such as
the DataDir or the LogsDir) should not be adjusted unless you absolutely
need to change them and are aware of the implications (e.g., which other
configuration options may need to be adjusted as well to avoid discrepancies
resulting in unexpected behavior). No support will be provided for
non-default setups.
Once you are done adjusting the CMaNGOS configuration, copy the Docker Compose
example file for your chosen expansion to compose.yaml. For example, for
Classic:
cp ./compose-classic.yaml.example ./compose.yamlFor TBC and WotLK, use compose-tbc.yaml.example or
compose-wotlk.yaml.example instead. The three files share the same structure
and only differ where the expansion makes them.
The available images for each expansion are:
| Expansion | Server image | Database image |
|---|---|---|
Classic (1.12.1) |
ghcr.io/mserajnik/cmangos-server-classic |
ghcr.io/mserajnik/cmangos-database-classic |
TBC (2.4.3) |
ghcr.io/mserajnik/cmangos-server-tbc |
ghcr.io/mserajnik/cmangos-database-tbc |
WotLK (3.3.5a) |
ghcr.io/mserajnik/cmangos-server-wotlk |
ghcr.io/mserajnik/cmangos-database-wotlk |
By default, the latest available images are used. Alternatively, you can also
select specific ones via their combined revision tag. Each image is tagged with
a tag of the form
<expansion>-core.<core-revision>-db.<db-revision>-playerbots.<playerbots-revision>,
where each revision is a 7-character prefix of the matching commit hash. For
example, a Classic build might have the tag
classic-core.1aea167-db.2c980fa-playerbots.c33dfac on both the server and
database images.
Important
When you decide to select images via combined revision tag you should always
make sure to use the same one for the cmangos-server-<expansion> and the
cmangos-database-<expansion> images so there are no potential discrepancies
between code and data. It is not possible (or intended) to switch to images
based on older revisions than the previous ones you used to perform a clean
downgrade due to the database migrations.
Since the Docker images are generally built only once a day, it is unlikely that there will be a build for every single CMaNGOS commit combination. Older images are automatically deleted after 14 days; in practice, you should not rely on specific images staying available beyond the point in time when you originally pulled them. If you absolutely need images based on specific CMaNGOS commits, you can always build them yourself instead.
Tip
You can find all the currently available cmangos-server-<expansion> and
cmangos-database-<expansion> images by browsing the packages listed
here.
Aside from which Docker images you want to use you mainly have to pay attention
to the environment sections of each service configuration. In particular, you
will want to adjust the TZ (time zone) environment variable for each service.
The CMANGOS_REALMLIST_* environment variables of the database service
should also be of interest; changing the CMANGOS_REALMLIST_ADDRESS to a LAN
IP, a WAN IP or a domain name is required if you want to allow non-local
connections.
Caution
Anything in your compose.yaml that is not commented or explicitly mentioned
in this README, regardless of the section, is likely something you do not
have to (or, in some cases, must not) change. Doing so may lead to
unexpected behavior and is not supported.
CMaNGOS uses data that is generated from extracted client data to handle things
like mob movement and line of sight. If you have already acquired this data
previously, you can place it directly into
./storage/<expansion>/mangosd/extracted-data and skip the next steps.
To extract the data, first copy the contents of your client directory into
./storage/<expansion>/mangosd/client-data. Next, run the following command,
substituting the image for the expansion you want to extract for. For example,
for Classic:
docker run \
-i \
-v ./storage/classic/mangosd/client-data:/opt/cmangos/storage/client-data \
-v ./storage/classic/mangosd/extracted-data:/opt/cmangos/storage/data \
--rm \
--user 1000:1000 \
--platform linux/amd64 \
ghcr.io/mserajnik/cmangos-server-classic \
extract-client-dataThere are two things to look out for here:
- If you are using a Linux host and your user's UID and GID are not 1000,
change the
--userargument to reflect your user's UID and GID. This will cause the user in the container to use the same UID and GID and prevent permission issues on the bind mounts. If you are on Windows or macOS, you can ignore this (or even remove the--userargument altogether, if you want to) - The Docker image must reflect the expansion you want to extract the data for
Important
The extractors are only included in the amd64 images because CMaNGOS forces
BUILD_EXTRACTORS=OFF on arm64. The --platform linux/amd64 flag in the
command above ensures the right image variant is used even on arm64 hosts
(running through emulation, which can be slow).
Extracting the data can take many hours (depending on your hardware). Some notices/errors during the process are normal and usually nothing to worry about (as long as the execution continues afterwards).
Once the extraction is finished you can find the data in
./storage/<expansion>/mangosd/extracted-data. Note that you may want to
re-run the process in the future if CMaNGOS makes changes (to benefit from
potentially improved mob movement etc.). In case it becomes necessary to do so
(e.g., if the extraction process changes), the
Breaking changes section further below will be updated
accordingly.
If you re-run the extraction, it will automatically detect previously extracted
data and ask you if you want to continue (which will overwrite the old data).
You can also skip this confirmation prompt (and force the re-extraction) by
adding the --force flag to the extract-client-data command, like this:
docker run \
-i \
-v ./storage/classic/mangosd/client-data:/opt/cmangos/storage/client-data \
-v ./storage/classic/mangosd/extracted-data:/opt/cmangos/storage/data \
--rm \
--user 1000:1000 \
--platform linux/amd64 \
ghcr.io/mserajnik/cmangos-server-classic \
extract-client-data --forceIf you want to make custom changes to the world database, it is recommended to
do so using SQL files and placing them in
./storage/<expansion>/database/custom-sql (a bind mount for this directory is
configured out-of-the-box). The files in this
directory are processed on every startup, including after cmangos-deploy
re-creates the world database to apply an upstream migration edit (see the
What happens during an update section), so
your changes survive that flow without manual intervention.
By default, all SQL files (files with a .sql extension) in that directory
will be processed during each startup in alphabetical order (after the world
database has been created and updated with the latest migrations). Thus, the
SQL statements in your files have to be idempotent (i.e., they can be processed
multiple times without causing issues).
You can find further details about this feature here.
Once you are happy with the configuration and have extracted the client data, you can start CMaNGOS for the first time. To do so, run:
docker compose up -dThis pulls the Docker images first and afterwards automatically creates and starts the containers. During the first startup it might take a little longer until the server becomes available due to the initial database creation.
Caution
Make sure to not (accidentally) stop CMaNGOS before the database creation process has finished; otherwise, you will likely end up with a broken database and will have to delete and re-create it.
Especially during the first startup you might want to follow the server output to know when CMaNGOS is up and running:
docker compose logs -f mangosdOnce you see the output World initialized. you know that the initialization
process has finished and CMaNGOS is ready.
To create the first account, attach to the mangosd container (make sure
that the server is ready before attaching):
docker compose attach mangosdAfter attaching, create the account and assign an account level:
account create <account-name> <account-password>
account set gmlevel <account-name> <account-level>The available account levels are:
| Level | Type |
|---|---|
0 |
Player |
1 |
Moderator |
2 |
Game Master |
3 |
Administrator |
E.g., to create an administrator account, set the account level to 3.
Note
Setting an account level of 1 or higher means that some Game
Master-specific behavior will begin to apply to characters on that account.
Exactly which behavior applies depends on the account level; you can modify
some of this via the GM.* options in your
mangosd.conf.
For TBC and WotLK, expansion-specific content is gated by an "expansion level"
that has to be set per account. New accounts default to level 0, which
corresponds to Classic. To unlock expansion content, run:
account set addon <account-name> <expansion-level>The available expansion levels are:
| Expansion | Level | Effect |
|---|---|---|
| Classic | 0 |
Default; no action required |
| TBC | 1 |
Unlocks TBC content |
| WotLK | 2 |
Unlocks WotLK content |
When you are done, detach from the Docker container by pressing Ctrl+P and Ctrl+Q. You should now be able to log in to the game client with your newly created account.
To stop CMaNGOS, simply run:
docker compose downTo update, pull the latest images:
docker compose pullAfterwards, re-create the containers:
docker compose up -dNote
Selecting specific images via combined revision tag (as described further
above) will obviously prevent you from updating until you edit each
respective service in your compose.yaml to pull newer images. Attempting to
update without changing the configured images is not harmful, it will just
not have any effect.
cmangos-deploy detects upstream CMaNGOS commits that edit already released migration files. Such changes would otherwise leave your databases in an inconsistent state and require manual intervention to rectify.
By default, cmangos-deploy will
automatically re-create your world database
when a relevant change is detected. Anything in the world database that you may
have changed (your custom NPCs and gameobjects, npc_vendor edits, etc.) does
not survive the re-creation, so restore those from a backup if you need them
back (or use
custom SQL to
cleanly preserve the additions/changes).
For the other databases that contain user state, cmangos-deploy cannot safely re-create them and instead halts startup until you intervene; see the next section.
When a migration edit is detected that affects a database containing user state (or a world database edit with automatic corrections disabled), cmangos-deploy halts startup and prints a message naming the affected database(s) and the GitHub link(s) to the upstream commit(s).
The container stays running while paused; nothing restarts on its own. To resolve:
- Open each linked commit on GitHub and read the changes.
- Apply the equivalent SQL to the running database. From the host:
where
docker compose exec database mariadb -u root -p <database>
<database>ischaracters,realmd,logs, ormangos.mariadbwill prompt for the password; it matches yourMARIADB_ROOT_PASSWORDsetting incompose.yaml. - When you are done, confirm by running on the host:
docker compose exec database cmangos-confirm-changes
cmangos-deploy will then record the acknowledgement and continue startup. If
you instead want to abort, run docker compose down.
Caution
When you run cmangos-confirm-changes, cmangos-deploy treats the listed
commits as applied and continues. It does not check your database to verify
that the changes you made match what the commits describe. If your manual fix
is incorrect or incomplete, the database will be in an inconsistent state and
CMaNGOS may fail to start. The responsibility for matching what the commits
do is yours; cmangos-deploy provides no further support for resolving these
issues.
It is recommended to regularly check this repository (either manually or by
updating your local repository via git pull). Usually, the commits here will
just consist of maintenance and potentially new CMaNGOS configuration options
(that you may want to incorporate into your configuration).
Sometimes, there may be new features or changes that require manual intervention. Such breaking changes will be listed here (and removed again once they become irrelevant).
It is recommended to perform regular database backups, particularly before updating.
To automatically create database backups periodically, uncomment the
database-backup service configuration in your
compose.yaml and follow the comments for further information.
To make certain changes (e.g., managing accounts or changing the realm configuration) it can be necessary to access the database with a MySQL/MariaDB client.
A common web-based MySQL/MariaDB database administration tool called
phpMyAdmin is included and can be enabled by uncommenting the
phpmyadmin service configuration in your
compose.yaml. See the comments there for further information.
It is not recommended to expose your database to the public (whether through direct port access, a WAN-accessible phpMyAdmin instance, or any other means). If you decide to do so, you will have to implement appropriate security measures. Please note that no further support or guidance regarding this will be provided here.
Caution
The default database users with full access to all CMaNGOS data (root and
the user named via the MARIADB_USER environment variable) do not have any
restrictions in place in regards to which IPs/hosts can connect.
You are welcome to help out!
Open an issue or make a pull request.
AGPL-3.0-or-later(Code)CC-BY-SA-4.0(Documentation and graphic assets)CC0-1.0(Configuration files)
This project follows the REUSE specification.
cmangos-deploy is an independent, community-made Docker setup for the open-source CMaNGOS project. It is not affiliated with, endorsed by, or sponsored by Blizzard Entertainment, Inc., and it is not an official CMaNGOS project.
This project includes no game client data or other copyrighted game assets. You must supply your own legitimate game client, from which the required data is extracted locally on your own machine. It is intended for private, non-commercial use only and comes with no warranty.