Skip to content

Docker

Jump to bottom
Ângelo Tadeucci edited this page Mar 16, 2025 · 20 revisions

About Docker

You can read more about docker here, but in short Docker provides the ability to package and run an application in a loosely isolated environment called a container.

In the case of this emulator you won't need to install MySQL and .NET in your computer, but you will NEED to enable Virtualization in your BIOS if you don't have enabled already since Docker uses Hyper-V or WSL2, you can read for about it here.

Setup

  1. Up-to-date Maple2 repository. ITS NOT RECOMMENDED TO DOWNLOAD THE REPOSITORY AS ZIP
    • You can use Github Desktop to clone the repository
    • Or you can use this command git clone --recurse-submodules https://github.com/AngeloTadeucci/Maple2
  2. MapleStory2 client
  3. Server.m2d & Xml.m2d
    1. Download our custom Server.m2d, Server.m2h, Xml.m2d, & Xml.m2h XML files from MapleStory2-XML releases repository.
    2. Place the four files inside the MapleStory 2 client folder within the Data folder. The Data folder is where you will see an existing Xml.m2d and Xml.m2h. Place all of them in this Data folder, replacing the existing Xml.m2d and Xml.m2h files.
    • The Xml.m2d is optional but you will get some fixes and translated strings.
  4. Install Docker Desktop on Windows or Docker Engine on Linux

Configure ENV

Go to where you cloned or extracted the Maple2 project.

  1. Copy and Rename .env.example to .env.
  2. Open the .env file with a text editor or code editor and leave it open for the following instructions.
  3. Rename MS2_DATA_FOLDER to MS2_DOCKER_DATA_FOLDER
    1. Go to where MapleStory2 Client is installed, copy the path of the Data folder (Example: D:\MapleStory2\MapleStory 2 Client\Data).
    2. Set the value of MS2_DOCKER_DATA_FOLDER as the path you just copied. Like MS2_DOCKER_DATA_FOLDER=D:\MapleStory2\MapleStory 2 Client\Data
  4. Add an # before DB_IP=localhost, it should look like this: #DB_IP=localhost
  5. Define a password you want for the MySQL server and change it after DB_PASSWORD=. Like DB_PASSWORD=mysupersecretandsecurepassword
    1. When the MySQL container is run the first time the password you chose will be set and can't (can but complicated) be changed

If you have MySQL already installed on your machine

When starting the database container you might get an error like Error response from daemon: Ports are not available.

To fix this go to the compose.yml file in the root of the Maple2 folder, look for the mysql service and in the ports section use a new available port like - 3307:3306. This new port is only used for outside connection of docker, for example DBeaver.

Setup Database and ingest Metadata

Open a terminal window inside the Maple2 folder and run the following command:

docker compose run --rm -it file-ingest

File Ingest requires a good amount of memory, around 8GB of RAM

If you want to check how much memory file-ingest is using and the max amount reserved for Docker, you can use this command:

docker stats

If you think file-ingest is hanging because of not enough memory, if using WSL2 go here to get more details on how to increase the memory limit and amount of CPU threads Docker will use.

Run servers

After file-ingest ends on the same terminal window, run the following commands:

docker compose build

Wait for it to finish and run:

docker compose up login world web -d

Use this command to see the logs and check if everything is fine:

docker compose logs -f

We run the Game server after since it requires the World server to be running. Doing it with a single command wont work.

docker compose up game-ch0 -d

Check again if everything is fine and you should see "Channel 1 has become active"!

Any issues go to the community discord server for help or check the FAQ!

Clone this wiki locally