vmangos-deploy

---

[!WARNING] vmangos-deploy was relaunched on 2026-10-04 with major changes that require adjusting your configuration. If you used it before this date, work through the breaking changes before you update.

---

vmangos-deploy is a Docker-based solution for running VMaNGOS. It offers:

• Prebuilt Docker images for both amd64 and arm64, built with GitHub Actions: simply pull the images for your architecture and get started.
• The ability to run VMaNGOS configured for any of its supported client versions: prebuilt images for all versions, from 1.5.1.4449 to 1.12.1.5875, are provided.
• Automated database migrations: when you pull the latest Docker images and re-create the containers, the migrations are applied automatically to keep your databases up to date at all times.

[!NOTE] The Docker images are built daily when VMaNGOS has had new commits since the last build. Additionally, every Monday, the latest images are rebuilt to keep their system packages up to date, even if VMaNGOS itself has not changed.

Quick start

The steps below get a local installation running quickly, for playing on the same machine. You need Docker with Docker Compose.

1. Clone the repository and copy the 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.conf
   

   Then adjust the copies to your liking, for example the GameType or the RealmZone in your config/mangosd.conf. The files describe their options. Some options are set by the image and cannot be configured in the files. A comment at the top of your mangosd.conf and realmd.conf lists them.

2. Copy the example Compose file:

   cp compose.yaml.example compose.yaml
   

3. Adjust your compose.yaml: set the server image of your client version for the realmd and mangosd services, as the client versions section lists. Set TZ to your time zone in every service, and change the database passwords. On Linux, set VMANGOS_UID and VMANGOS_GID to your user's UID and GID. The Docker Compose reference explains every setting.

4. Copy the contents of your client directory into storage/mangosd/client-data/, and extract the client data:

   docker compose run --rm extract-client-data
   

   Use the client that matches your chosen client version. Extracting can take many hours, and the extracting the client data section describes the details.

5. Start VMaNGOS and follow its output:

   docker compose up -d
   docker compose logs -f mangosd
   

   The first start takes longer, because it creates the databases. Do not interrupt it, or you may have to remove the database volume and start over. The server is ready when it prints World initialized..

6. Create your first account. To do that, attach to the server console:

   docker compose attach mangosd
   

   Then create the account:

   account create <account-name> <password>
   

   If you want to give the account Game Master permissions, for example, the accounts section explains the account levels. To leave the console again, press Ctrl+P and then Ctrl+Q.

7. Adjust the realmlist.wtf in the client directory to point the client at the local server:

   set realmlist 127.0.0.1
   

   Then start the client and log in with the account you created.

For the full instructions, see the usage documentation.

Using a coding agent

A coding agent such as Claude Code or Codex can walk you through the setup. Try a prompt like the following:

Help me install and set up https://github.com/mserajnik/vmangos-deploy.
First, clone the repository and read the README and every file under docs/
carefully.
Then guide me through the installation process step by step, following the
documentation 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 VMaNGOS or Docker and that I have not read
the documentation 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 client version, optional
services, or networking-related preferences.
Ask me whenever the documentation presents a meaningful choice.
For settings and options that the documentation or the VMaNGOS example
configuration files indicate should generally be left alone, keep the defaults
unless I explicitly ask for something else.
Do not change settings and options that the documentation or the VMaNGOS
example configuration files indicate should not be changed.

The prompt that works best depends on the agent and the model.

[!CAUTION] You use coding agents at your own risk, and you are responsible for the access you give them. The maintainer of this project is not liable for any damage or data loss they cause. Take precautions such as sandboxed access and limited permissions, and do not run them with --yolo or similar options that bypass their safety checks.

Documentation

• Usage: choosing images, the client data, running and updating VMaNGOS, backups, and database access.
• Docker Compose reference: every setting in your compose.yaml.
• Breaking changes: the changes you have to act on when you update.

Modifications

The images contain VMaNGOS with the patches from docker/patches/. A patch exists for one or more of these reasons:

• It corrects a problem that breaks the build or the running server.
• It adapts the code to how the images are built and run.
• It changes a VMaNGOS default to a value that gives objectively better results.
• It applies a fix from an open VMaNGOS pull request that the maintainer has reviewed and that does not conflict with VMaNGOS's goals.

Every patch adds a comment to the code it changes, which explains what the change does and why. A patch is removed once it is no longer needed, so the directory can be empty at times.

Similar Docker setups

• cmangos-deploy for CMaNGOS, a WoW server emulator that supports Vanilla (which CMaNGOS calls Classic), TBC, and WotLK.
• tortoise-deploy for Tortoise-WoW, a community-driven restoration of Turtle WoW's 1.18.1.7272 patch.
• lost-city-rs-deploy for Lost City RS, an RS2 server emulator that aims to re-create the original game accurately.

Maintainer

Michael Serajnik

Contribute

You are welcome to help out!

Open an issue or make a pull request.

Licenses

• AGPL-3.0-or-later (Code)
• GPL-2.0-only (Database entrypoint script, based on MariaDB's)
• GPL-2.0-or-later (Patches, matching VMaNGOS source)
• CC-BY-SA-4.0 (Documentation, graphic assets, and issue templates)
• CC0-1.0 (Configuration files)

This project follows the REUSE specification.

Disclaimer

vmangos-deploy is an independent, community-made Docker setup for the open-source VMaNGOS project. It is not affiliated with, endorsed by, or sponsored by Blizzard Entertainment, Inc., and it is not an official VMaNGOS 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.