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 doesn't delve into security best practices and policies...
It's just a simple practical example of a basic CMaNGOS Docker configuration; be careful to use it directly in a production environment.

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

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.

Locate the client directory

To play World of Warcraft, you'll definitely need a purchased and legally owned copy of the game. Furthermore, you'll need it to be installed on your computer.

Locate where the installation directory is located; by default -on Windows- it should be in C:\Program Files\World of Warcraft.
Once you find it, copy the path to it; we'll need it in a moment.

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.
To simplify this process, there is a .env.example file that you can copy and modify using a simple text editor (e.g. notepad.exe) to better suit your needs.

It contains 6 different key-value pairs; I will describe them in detail:

• MYSQL_SUPERPASS: it's the password of the root user that will be used to administer the MySQL database.
• MANGOS_DBUSER: it's the username of the user that will be used by the application server to connect to the MySQL database.
• MANGOS_DBPASS: it's the password of the user that will be used by the application server to connect to the MySQL database.
• WOW_CLIENT_DIR: it's the path to the WoW installation directory that you just located in the previous step.
• WOW_TIMEZONE: it's the time zone identifier that specify which time zone the server should use for the time.
• WOW_VERSION: it's the keyword that describes which version of WoW client the server have to support that you choose as the first step.

Once you've done with this, save the file and close your text editor.

Extract files 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, select your environment and follow the steps:

A Unix shell (e.g. bash)

./builder/run.sh extract

Windows Command Prompt (cmd.exe)

Recall where your WoW installation directory is and replace the <path> placeholder.
Then, also replace the <version> placeholder with the correct version of the client you want to support.

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)

Recall where your WoW installation directory is and replace the <path> placeholder.
Then, also replace the <version> placeholder with the correct version of the client you want to support.

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:

A Unix shell (e.g. bash)

./builder/run.sh init-db

Windows Command Prompt (cmd.exe)

Don't forget to replace the <version> placeholder with the correct version of the client you want to support.

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)

Don't forget to replace the <version> placeholder with the correct version of the client you want to support.

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.

Configure the realmlist table

The last step before starting the server consists into allowing the client know which Realms there are, how many and where to find them.
CMaNGOS already takes care of this step by applying a basic configuration that should match the usual scenario of a server with a single realm running on the local machine.

However, if your scenario is different or if you find yourself in a loop where the WoW client asks you to choose a realm to join and then -once selected- asks you to select the realm again, and again, and again...
You'll probably need to configure the realmlist table contained in the realmd database.

The queries you'll need to run are the following:

DELETE FROM realmlist WHERE id = 1;

INSERT INTO realmlist (id, name, address, port, icon, realmflags, timezone, allowedSecurityLevel)
    VALUES ('1', 'CMaNGOS', '127.0.0.1', '8085', '1', '0', '1', '0');

Note

You probably want to configure the name, address and port columns accordingly.

All the other fields -honestly- I'm not sure if they actually matter or not; realmflags and timezone are -actually- configurable via the mangosd.conf file.

Tip

If you have no idea how to run these queries, take a look at the Database management page.

Running the server

Once you've initialized the database, you're ready to run your very own 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.

Use 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.

Create 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>

Enable 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>

Set 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.