Getting Started

Introduction

One of the main goals of the CMaNGOS Docker project is optimization.
To achieve this, two different types of images have been developed: the one used for maintainance (larger) and the one used for execution.

With this principle in mind, we can now begin! 🚀

Warning

This procedure doesn't describe a production-ready stack deployment and contains default password values...
It's just a simple working example of a basic configuration of CMaNGOS Docker.

If you're looking for more specific guidance, you may find the Use in Production page useful.

First time run

First of all, you have to decide up to which client version you want your server to support.
Both CMaNGOS and CMaNGOS Docker use three keywords to identify it; select the one you need and keep it in mind for the next steps:

Game name	Game version	Keyword
World of Warcraft®	v1.12.x	classic
World of Warcraft: The Burning Crusade®	v2.4.3	tbc
World of Warcraft: Wrath of the Link King®	v3.3.5a	wotlk

Download the images

Once you've selected the supported client version, you can download the related Docker images.
To do so, you need to open a shell or command prompt and type the following lines replacing the <version> placeholder with the keyword of your choice:

docker pull ghcr.io/byloth/cmangos/<version>/builder:latest  # for maintainance
docker pull ghcr.io/byloth/cmangos/<version>:latest          # for execution

e.g.

For instance, let's say you wish to support up to the tbc version of the client...
What you have to type is:

docker pull ghcr.io/byloth/cmangos/tbc/builder:latest
docker pull ghcr.io/byloth/cmangos/tbc:latest

Important

Be sure to replace the < and > characters as well!

Preliminary configuration

Create project directory

Create a new directory on your computer to store all the stuff related to your WoW server.
It's best not to use the same directory as the client: keep them separated from each other.

Download the cmangos-docker.zip¹ archive, open and extract it inside the newly created directory.

Tip

If you're proficient in using git, you can directly clone this entire repository instead of downloading it.

Note that the project is ready-to-use and -for this reason- I preferred to choose some default values rather than leaving placeholders in the code.
For example, I chose to support the tbc version of the client since it's my favourite one. 🥰

If you've decided to use another version, open the file named docker-compose.yml using a simple text editor (e.g. notepad.exe) and be sure to replace all the two occurrences of tbc with the correct version of your choice.

Create .env file

The .env file is a configuration file that allows you to customize your WoW server.

Although it's mandatory for the application to work properly, I couldn't include a ready-made one, due to its nature... This means that you've to create it yourself.
You can simply create an empty file, if you don't want to make any changes for now... Otherwise you can start customizing it, by selecting the correct time zone.

Here's an example of the .env file with a first customization:

TZ="Europe/Amsterdam"

Note

You can find other customizations here.

Files extraction from the client

Actually, due to legal reasons and copyright policies, CMaNGOS (and -of course- CMaNGOS Docker) cannot be distributed ready-to-run or -at least- not at 100% of its functionality... In fact, it needs some extra copyrighted files from Blizzard Entertainment®.

These files -fortunately- are present within the WoW client: the exact same client you need to play.
For this reason, if you've purchased and legally own a copy, you can use a CMaNGOS tool to extract these files directly from it.

To do this, we must first identify the path where the WoW client was installed; copy it.
Then type the following lines replacing both the <path> and <version> placeholders:

Windows Command Prompt (cmd.exe)

docker run -it --rm ^
           --volume "cmangos_mangosd_data:/home/mangos/data" ^
           --volume "<path>:/home/mangos/wow-client" ^
    ^
    ghcr.io/byloth/cmangos/<version>/builder:latest extract

Windows PowerShell (powershell.exe)

docker run -it --rm `
           --volume "cmangos_mangosd_data:/home/mangos/data" `
           --volume "<path>:/home/mangos/wow-client" `
    `
    ghcr.io/byloth/cmangos/<version>/builder:latest extract

A Unix shell (e.g. bash)

docker run -it --rm \
           --volume "cmangos_mangosd_data:/home/mangos/data" \
           --volume "<path>:/home/mangos/wow-client" \
    \
    ghcr.io/byloth/cmangos/<version>/builder:latest extract

Databases initialization

Since it's the first run, it's necessary to create the databases and load the initial data² required by CMaNGOS to work correctly.

Open a new shell or a command prompt inside the server project directory you've created earlier and type the following line:

docker compose up mariadb

From now on, this terminal instance is going to simply print out text indicating that it's working but won't be interactive.
As long as it prints the text, it will be up and running; once it will be possible to type a command again, it will mean that the execution of the program has stopped.

So, leave it behind and within another shell or command prompt, type the following lines (be sure to replace the <version> placeholder):

Windows Command Prompt (cmd.exe)

docker run -it --rm ^
           --env MYSQL_SUPERUSER="root" ^
           --env MYSQL_SUPERPASS="root00" ^
           --env MANGOS_DBHOST="mariadb" ^
           --env MANGOS_DBUSER="mangos" ^
           --env MANGOS_DBPASS="mangos00" ^
           --network "cmangos_default" ^
           --volume "cmangos_mangosd_data:/home/mangos/data" ^
    ^
    ghcr.io/byloth/cmangos/<version>/builder:latest init-db

Windows PowerShell (powershell.exe)

docker run -it --rm `
           --env MYSQL_SUPERUSER="root" `
           --env MYSQL_SUPERPASS="root00" `
           --env MANGOS_DBHOST="mariadb" `
           --env MANGOS_DBUSER="mangos" `
           --env MANGOS_DBPASS="mangos00" `
           --network "cmangos_default" `
           --volume "cmangos_mangosd_data:/home/mangos/data" `
    `
    ghcr.io/byloth/cmangos/<version>/builder:latest init-db

A Unix shell (e.g. bash)

docker run -it --rm \
           --env MYSQL_SUPERUSER="root" \
           --env MYSQL_SUPERPASS="root00" \
           --env MANGOS_DBHOST="mariadb" \
           --env MANGOS_DBUSER="mangos" \
           --env MANGOS_DBPASS="mangos00" \
           --network "cmangos_default" \
           --volume "cmangos_mangosd_data:/home/mangos/data" \
    \
    ghcr.io/byloth/cmangos/<version>/builder:latest init-db

Once done, go back to the previous terminal (which should still be running) and press the Ctrl & C keyboard keys at the same time.
This will cause the program to print some message about it and the execution of the program will stop within a few seconds.

After that, you will be able to type a new command again.

Running the server

Once you've initialized the database, you're ready to run your personal WoW server for the first time! 🚀

While you still in the server project directory with the terminal, type the following line:

docker compose up

As before: this instance will no longer be interactive and, as long as it prints messages, your own CMaNGOS server will be up and running.

Using the CMaNGOS console

The CMaNGOS server application provides a Command Line Interface on which you can manage users and the server itself.
You won't need this during normal use of the application server, but it might be useful in case you need to register a new user.

While your CMaNGOS server is still running, you can access it by typing within a new shell of a command prompt the following line:

docker attach cmangos-mangosd-1

Now you can type GMaNGOS commands.

Warning

Once you're done, DO NOT press Ctrl & C to exit the console.
It will cause the program to actually stop running, causing players to be unable to log into the game.

To properly exit the console, press Ctrl & P followed by Ctrl & Q.

Creating a new account

To create a new account, simply type the following line into the CMaNGOS console, replacing <username> and <password> respectively:

account create <username> <password>

Enabling expansion for an account

Regardless of the actual expansion supported by your CMaNGOS server, you can choose for each individual account which expansion it can benefit from.

Just like what happens on official WoW servers when they release a new expansion: the server does actually support that expansion but you're still not allowed to benefit from what the new expansion introduced until you physically purchase it.
This setting allows you to implement the same behaviour.

Here's a table describing the various levels of supported expansions:

Game name	Game version	Level
World of Warcraft®	v1.12.x	0
World of Warcraft: The Burning Crusade®	v2.4.3	1
World of Warcraft: Wrath of the Link King®	v3.3.5a	2

Note

Keep in mind that a higher level automatically also includes all of the above.
For example, you cannot allow a user to benefit from wotlk without benefiting from tbc.

To enable (or -of course- disable) a specific level of supported expansion for an account, all you have to do is typing the following command, replacing both <username> and <level> accordingly:

account set addon <username> <level>

Setting GM level for an account

GMs are the Game Masters and -depending on their level- they can perform different actions in the game, such as banning offensive people and teleport stranded players.

Here a table describing the various GM levels:

GM type	Level
Normal Player	0
Moderator	1
Game Master	2
Administrator	3

To change the GM level of a specific account, all you have to do is typing the following command, replacing both <username> and <level> accordingly:

account set gmlevel <username> <level>

Stopping the server

To successfully stop the server, you just need to press Ctrl & C within the terminal where the CMaNGOS server is running (the one where you previously run the server and which should still print some messages).
This should take a while but will eventually stop gracefully.

Note

If you want to make sure everything was shut down properly, you can run inside your project directory:

docker compose down

Next steps

• Server Configuration
• Database Management
• Install Updates
• Customization
• Use in Production

---

1. This file may be updated over time.
   Make sure to check it from time to time and follow the update procedure.
2. This information is about NPCs or mobs that can be found in the game, items or spells that are available or can be cast and quests or events that can be done... In addition, their related stats such as strength, speed or hit points, spawn or drop ratio, experience or gold gained and other stuff like that.
   If you find something that seems wrong or missing while playing, feel free to report it to the CMaNGOS team.