A Docker setup for VMaNGOS
This is a Docker-based solution for running VMaNGOS that focuses on providing a streamlined and user-friendly experience. It offers a range of features that simplify managing a VMaNGOS setup:
- Prebuilt Docker images for both
x86_64andaarch64, leveraging GitHub Actions: simply pull the provided images that have been optimized for size, performance and stability instead of having to re-compile VMaNGOS yourself every time you want to update - The ability to run VMaNGOS configured for any of its supported client
versions: prebuilt images for all versions ranging from
1.6.1.4544to1.12.1.5875are provided - 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 VMaNGOS 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 VMaNGOS configuration can be found
in
./config, everything else that is shared between the Docker containers and your host system lives inside./storage
Note
The Docker images are built on a daily schedule, unless there have been no new commits to VMaNGOS 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 VMaNGOS itself.
- Docker (including Compose V2)
First, clone the repository and create copies of the provided VMaNGOS example configuration files:
git clone https://github.com/mserajnik/vmangos-deploy.git
cd vmangos-deploy
cp ./config/mangosd.conf.example ./config/mangosd.conf
cp ./config/realmd.conf.example ./config/realmd.confNext, adjust the two 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.
Caution
Options relating to certain things that vmangos-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 VMaNGOS configuration, create a copy of the Docker Compose example configuration:
cp ./compose.yaml.example ./compose.yamlNext, adjust your compose.yaml. The first thing to decide on is which Docker
images you want to use based on the client version the server should support.
You can choose from the following versions:
| Supported client version | Image |
|---|---|
1.12.1.5875 |
ghcr.io/mserajnik/vmangos-server:5875 |
1.11.2.5464 |
ghcr.io/mserajnik/vmangos-server:5464 |
1.10.2.5302 |
ghcr.io/mserajnik/vmangos-server:5302 |
1.9.4.5086 |
ghcr.io/mserajnik/vmangos-server:5086 |
1.8.4.4878 |
ghcr.io/mserajnik/vmangos-server:4878 |
1.7.1.4695 |
ghcr.io/mserajnik/vmangos-server:4695 |
1.6.1.4544 |
ghcr.io/mserajnik/vmangos-server:4544 |
Adjust the configured image for the realmd and mangosd services based on
this table. E.g., if you wanted to run a server that supports client version
1.6.1.4544, you would choose ghcr.io/mserajnik/vmangos-server:4544.
By default, the latest available images are used. Alternatively, you can also
select specific ones via the VMaNGOS commit hash they have been built from. To
allow for this, the vmangos-server image (used by the realmd and mangos
services) and the vmangos-database image (used by the database service)
have tags that include the respective commit hash. E.g., for commit
46183d287f80ab1ebf27bab12f37bc0b5b188c86:
realmd/mangos service image |
database service image |
|---|---|
ghcr.io/mserajnik/vmangos-server:5875-46183d287f80ab1ebf27bab12f37bc0b5b188c86 |
ghcr.io/mserajnik/vmangos-database:46183d287f80ab1ebf27bab12f37bc0b5b188c86 |
Important
When you decide to select images via VMaNGOS commit hash you should always
make sure to use the same one for the vmangos-server and the
vmangos-database images so there are no potential discrepancies between
code and data. It is not possible (or intended) to switch to images based
on an older commit 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 VMaNGOS commit. Older images are automatically deleted, roughly after 45 days; in practice, you should not rely on specific images staying available for any prolonged period of time. If you absolutely need images based on a specific VMaNGOS commit, you can always build them yourself instead.
Tip
You can find all the currently available vmangos-server and
vmangos-database images here and
here respectively.
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 VMANGOS_REALMLIST_* environment variables of the database service
should also be of interest; changing the VMANGOS_REALMLIST_ADDRESS to a LAN
IP, a WAN IP or a domain name is required if you want to allow non-local
connections.
Also take note of the healthcheck sections; if you are using a low end system
you may have to adjust the start_period setting so that the initial database
creation process will be able to complete in time before the healthcheck
considers the container unhealthy and causes a restart.
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.
VMaNGOS 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/mangosd/extracted-data and skip
the next steps.
To extract the data, first copy the contents of your client directory into
./storage/mangosd/client-data. Next, simply
run the following command:
docker run \
-i \
-v ./storage/mangosd/client-data:/opt/vmangos/storage/client-data \
-v ./storage/mangosd/extracted-data:/opt/vmangos/storage/extracted-data \
--rm \
--user 1000:1000 \
ghcr.io/mserajnik/vmangos-server:5875 \
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 client version you want to extract the data from; see the table further above in the Docker Compose configuration section
Important
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/mangosd/extracted-data. Note that
you may want to re-run the process in the future if VMaNGOS 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/mangosd/client-data:/opt/vmangos/storage/client-data \
-v ./storage/mangosd/extracted-data:/opt/vmangos/storage/extracted-data \
--rm \
--user 1000:1000 \
ghcr.io/mserajnik/vmangos-server:5875 \
extract-client-data --forceTo use Warden, you have to provide the Warden modules yourself. See here for details on how to do so.
Warning
Using HermesProxy (or projects derived from it) to connect
1.14.x clients to VMaNGOS will likely not be possible (in a stable manner
without getting kicked off the server) when Warden is enabled.
vmangos-deploy keeps track of certain, unusual VMaNGOS code changes (such as migration edits) that lead to a faulty (or out-of-sync) world database state when updating and would normally require manual intervention by you to rectify.
By default, vmangos-deploy can automatically correct the state of your world database in such cases by re-creating it. It is strongly suggested to keep this feature enabled.
If you do decide to disable it, you yourself are responsible for monitoring VMaNGOS for problematic code changes and taking appropriate actions (e.g., manually triggering the re-creation of the world database by mounting a database dump, as described here).
If you want to make custom changes to the world database, it is recommended to
do so using SQL files and placing them in
./storage/database/custom-sql (a bind mount
for this directory is
configured out-of-the-box). This way, you can
keep
automatic world database corrections
enabled without having to worry about your changes getting lost.
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).
An example SQL file that shows how you can populate the auctionhousebot table
with custom data
is provided. This
SQL file will not be processed by default without removing the .example
suffix from the file name. If you want to use it, it is recommended to first
make a copy of the file and then adjust the copy to your liking instead of
renaming the original file (to avoid dirtying the working tree).
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 VMaNGOS 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 VMaNGOS 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 VMaNGOS is up and running:
docker compose logs -f mangosdOnce you see the output World initialized. you know that the intialization
process has finished and VMaNGOS is ready.
To create the first account, attach to the mangosd container (make sure
that the server is ready before attaching):
docker attach vmangos-deploy-mangosd-1After attaching, create the account and assign an account level:
account create <account name> <account password>
account set gmlevel <account name> <account level> # see https://github.com/vmangos/core/blob/46183d287f80ab1ebf27bab12f37bc0b5b188c86/src/shared/Common.h#L183-L189When you are done, detach from the Docker container by pressing Ctrl+P and Ctrl+Q. You should now be able to log in with your newly created account.
To stop VMaNGOS, 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 VMaNGOS commit hash (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.
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 VMaNGOS 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), sorted by newest first:
- [2025-02-22] - Automatic world database corrections are now available and
enabled by default: vmangos-deploy now keeps track of certain, unusual
VMaNGOS code changes (such as migration edits) that lead to a faulty (or
out-of-sync) world database state when updating and would normally require
manual intervention by you to rectify. In such cases, vmangos-deploy can
automatically correct the state of your world database by re-creating it. It
is strongly suggested to keep this feature enabled. If you do decide to
disable it in your
compose.yaml, you yourself are responsible for monitoring VMaNGOS for problematic code changes and taking appropriate actions (e.g., manually triggering the re-creation of the world database by mounting a database dump, as described here). This section will no longer list such changes. - [2024-10-31] - Removal of separate images with anticheat support:
As of
vmangos/core@fbbc4aeVMaNGOS no longer supports building without anticheat support, thus anticheat is always available and there is no longer a need for separate images. If you were using one of the anticheat images (which were suffixed with-anticheat), simply switch to the regular version of that image.
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 VMaNGOS data (root and
the user named via 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 © Michael Serajnik