A Docker setup for VMaNGOS
This is a simplified Docker setup for VMaNGOS based on my previous project. It aims to improve upon its foundation while providing a much nicer experience for the user and features a number of big improvements:
- Prebuilt Docker images for both
x86_64andaarch64, leveraging GitHub Actions: you no longer need to spend a lot of time re-compiling VMaNGOS every time you want to update. In addition, the Docker images have been completely rewritten and optimized for size and previously redundant images have been merged into a single one - 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: by pulling the latest Docker images and recreating the containers, migrations are applied automatically to keep your database up-to-date
- A more transparent and easier to follow user experience: due to the prebuilt images the number of different commands that need to be run to manage the server has been greatly reduced and thus it is no longer necessary to use various scripts to install, update and manage VMaNGOS. Instead, you can simply use the Docker CLI (or any other tool that is able to manage Docker containers)
- A much tidier repository structure: the VMaNGOS configuration can be
found in
./config, everything else that is shared between the containers and your host system lives inside./storage
The Docker images are built daily, unless there have been no new commits to VMaNGOS. Additionally, every Monday, the latest images are rebuilt to ensure that all included 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 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, you have to adjust the two configuration files you have just created for
your desired setup. Configuration options relating to the database connection
or directories (such as DataDir or LogsDir) should not be adjusted unless
you know what you are doing and want/need to change the default setup.
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 the Docker
image version you want to use based on the client version the server should
support. You can choose from the following versions:
| Supported client version | Image tag |
|---|---|
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 want to run a server that supports client version
1.6.1.4544 you would use ghcr.io/mserajnik/vmangos-server:4544.
Instead of using the latest build you can also use a specific VMaNGOS commit.
To allow for this, the vmangos-database image is tagged with the commit hash
(e.g., vmangos-database:e87d583a5e50ad49f12a716fb408b393d3c21103) and the
vmangos-server image tag is suffixed with the commit hash (e.g.,
vmangos-server:5875-e87d583a5e50ad49f12a716fb408b393d3c21103) so you can
still select the supported client version.
When you decide to use a specific commit 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. Note that it is not
possible (or intended) to use this feature to perform a clean downgrade due to
the database migrations.
Since the Docker images are built only once a day it is unlikely that there
will be a build for every single VMaNGOS commit; you can find all the available
versions for the vmangos-server and the vmangos-database images
here and
here respectively. Older images are
automatically deleted; only the images from the last 45 builds are kept (which
generally means the builds from the last 45 days, unless there have been builds
outside of the normal daily schedule or there have been no VMaNGOS commits on
some days).
Aside from the Docker image version 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 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 on 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.
Anything else that is not commented is likely something you do not not have to (or, in some cases, must not) adjust; this applies to everything including port mappings, volumes and environment variables.
VMaNGOS uses data that is generated from extracted client data to handle things
like 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 generate the data, first copy the contents of your client directory into
./storage/mangosd/client-data. Next, simply
run the following command:
docker run \
-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 (and even remove the--userargument altogether, if you want to) - The Docker image version must reflect the client version you want to extract the data from; see the table further above in the Docker Compose configuration section
Generating the data can take many hours (depending on your hardware). Some notices/errors during the extraction process are normal and nothing to worry about.
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 pathing etc.).
Optionally, if want to use Warden you have to provide the
Warden modules. See the volumes section of the mangosd
service in your compose.yaml on how to do that.
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. Note that during the first startup it might take a little longer until the server becomes available due to the initial database creation. 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/bd9cca7b9d16d3e88c15ed378a893faebaf353f1/src/shared/Common.h#L183-L190When 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, recreate the containers:
docker compose up -dNote that using a specific VMaNGOS commit will obviously prevent you from updating (but attempting to do so is not harmful, it just will 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:
- [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. - [2024-10-29] - Migration edits in
vmangos/core@e3f0547andvmangos/core@ebf9cd8: if you have already run the affected migrations before they have been edited in these commits, you will have to either manually edit your database to reflect these changes or alternatively re-create the world database and run migrations again. To do the latter, you can simply mount the initial database dump as described here. Make sure your Docker images are newer than the commits mentioned above before re-creating the database via this method. - [2024-09-25] - Migration edits in
vmangos/core@4bad448andvmangos/core@8ab4fbf: if you have already run the affected migrations before they have been edited in these commits, you will have to either manually edit your database to reflect these changes or alternatively re-create the world database and run migrations again. To do the latter, you can simply mount the initial database dump as described here. Make sure your Docker images are newer than the commits mentioned above before re-creating the database via this method.
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 there 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.
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. Therefore, you
should never 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.
You are welcome to help out!
Open an issue or make a pull request.
AGPL-3.0-or-later © Michael Serajnik