tortoise-deploy

---

Warning

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

---

tortoise-deploy is a Docker-based solution for running Tortoise-WoW. It offers:

• Prebuilt Docker images for both amd64 and arm64, built with GitHub Actions: simply pull the images for your architecture and get started.
• Multiple variants to choose from: the base images contain Tortoise-WoW alone, while the modules images add a curated set of modules on top. modules-bots adds TortoiseBots, a Playerbot module, to that set.
• 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 Tortoise-WoW or a bundled module 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 neither Tortoise-WoW nor a bundled module has changed.

Quick start

The steps below get a local installation running quickly, for playing on the same machine. You need Docker with Docker Compose. The steps set up the base variant. For modules or modules-bots, which the variants section describes, follow the notes in steps 1 and 2.

1. Clone the repository and copy the example configuration files:

   git clone https://github.com/mserajnik/tortoise-deploy.git
   cd tortoise-deploy
   cp config/mangosd.conf.example config/mangosd.conf
   cp config/realmd.conf.example config/realmd.conf

   For modules and modules-bots, also copy each .conf.example file in config/modules/ to a .conf file, and for modules-bots, each one in config/modules-bots/ as well. Then adjust the copies to your liking, for example the GameType or the RealmZone in your config/mangosd.conf. The files describe most of 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

   For modules or modules-bots, copy compose-modules.yaml.example or compose-modules-bots.yaml.example instead.

3. Adjust your compose.yaml: set TZ to your time zone in every service, and change the database passwords. On Linux, set TORTOISE_UID and TORTOISE_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

   Extracting can take many hours, and the extracting the client data section describes the supported client and the details.

5. Start Tortoise-WoW 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 server is up and running!.

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 this one:

Help me install and set up https://github.com/mserajnik/tortoise-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 Tortoise-WoW 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 image variant, optional services,
or networking-related preferences.
Ask me whenever the documentation presents a meaningful choice.
For settings and options that the documentation or the Tortoise-WoW 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 Tortoise-WoW
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 Tortoise-WoW, 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 server images contain Tortoise-WoW 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 Tortoise-WoW default to a value that gives objectively better results.
• It applies a fix from an open Tortoise-WoW pull request that the maintainer has reviewed and that does not conflict with Tortoise-WoW'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.

The patches are GPL-2.0-or-later, like the Tortoise-WoW code from before May 2026. Tortoise-WoW then moved to AGPL-3.0-only, which covers only the contributions after the move. A patch that changes such code is also under AGPL-3.0-only.

Similar Docker setups

• vmangos-deploy for VMaNGOS, a progressive Vanilla WoW server emulator that aims to eventually support all versions from 1.2.4.4222 to 1.12.1.5875.
• cmangos-deploy for CMaNGOS, a WoW server emulator that supports Vanilla (which CMaNGOS calls Classic), TBC, and WotLK.
• 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)
• AGPL-3.0-only (Some patches)
• GPL-2.0-only (Database entrypoint script, based on MariaDB's)
• GPL-2.0-or-later (Patches)
• CC-BY-SA-4.0 (Documentation, graphic assets, and issue templates)
• CC0-1.0 (Configuration files)

This project follows the REUSE specification.

Disclaimer

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