Installation on Linux / VPS

Prefer step-by-step instructions? Open the interactive guide to installation, updates and settings. You will choose a computer or a VPS and get instructions for your installation.

Linux has no windowed launcher – you do everything in the terminal. Ways to install:

  • the single-file installer instaluj-vps.sh – MT2009 PLUS 2.x only, the easiest way on a fresh VPS (below),
  • from the Windows launcher (the “SERWER NA VPS” button, i.e. server on VPS) – 2.x and Yohara,
  • the vps-install.sh installer from the package folder – 2.x and Yohara,
  • step by step (below, when you want to stay in full control).

The installation is the same in both versions; updates differ: 2.x updates itself from GitHub, while Yohara receives patches (Updates).

What you need

  • A VPS or mini PC with Debian or Ubuntu, an x86_64 processor (ARM will not do – the game server is 32-bit x86 code), and access as root or via sudo.
  • 8 GB RAM (4 GB works with fewer bots – the installer will create a swap file) and 60–80 GB of disk.
  • The full server package from Discord – the single-file installer (2.x) downloads it by itself.

MT2009 PLUS 2.x: single-file installer

Installation – log in to the VPS as root and enter two commands:

wget -O instaluj-vps.sh https://metin2sp.pl/wiki/pobierz/instaluj-vps.sh
sh instaluj-vps.sh

If the system has no wget, first run: apt-get update && apt-get install -y wget ca-certificates.

The script downloads the full server package by itself: MT2009-PLUS-Serwer-2.12.0.zip (about 140 MB) and immediately updates it to the latest 2.x version. You can also download the same package manually – it works on Windows (launcher) and on Linux.

What it does, step by step:

  1. Checks the machine and installs wget, unzip, curl and python3 if missing.
  2. Downloads the full package from metin2sp.pl and unpacks the server folder to /opt/mt2009plus.
  3. Reads the latest version from GitHub, downloads the update package, verifies its SHA-256 checksum and applies it to the folder.
  4. At the end it shows the server address and the commands for passwords and panels. The admin and test accounts get random passwords.

Options:

Option What it does
--paczka URL another direct link to the full package (.zip or .tar.gz) instead of the one from metin2sp.pl
--folder KATALOG where the server should live (default /opt/mt2009plus)
--address ADRES the server’s public address (by default the VPS’s detected IPv4 address)
--bots N number of bots (by default chosen to fit the memory)
--bez-aktualizacji keep the version from the full package
--force install even with low memory or disk space
--tylko-pliki steps 1–3 only – files ready in the folder, no Docker

From the Windows launcher

In the launcher (2.x or Yohara) click “SERWER NA VPS” (server on VPS): “1. POŁĄCZ (KLUCZ SSH)” (connect, SSH key), then “2. ZAINSTALUJ NA VPS” (install on VPS). The launcher uploads the server folder over SSH and runs the same commands on the VPS as below. The same window has “STAN VPS” (VPS status), “LOGI VPS” (VPS logs) and “OTWÓRZ PANEL (TUNEL SSH)” (open panel, SSH tunnel), and in 2.x also “AKTUALIZUJ VPS” (update VPS).

The vps-install.sh installer

Upload the whole server folder (the one with the VERSION file and the linux-port/ folder; in the 2.x package it is the Serwer folder) to the VPS, e.g. with scp or WinSCP, log in over SSH and run this from that folder:

sudo sh linux-port/tools/vps-install.sh install

What it does:

  1. Checks the machine (system, processor, memory, disk) and installs Docker.
  2. Creates a swap file if memory is short.
  3. Builds and starts the server. The first time it takes 15–40 minutes. The build runs in the background – a dropped SSH connection will not interrupt it.
  4. The admin and test accounts get random passwords (saved in /root/metin2-accounts.txt).

Options: --address ADRES (the server’s public address), --bots N (number of bots), --force (even with low memory or disk space); in Yohara only, also --profile NAZWA (a ready-made world configuration: mt2009, clean_easy, clean_hard, sapphire, emerald) and --language KOD (the server’s default language).

After installation – from the server folder:

sudo sh linux-port/tools/vps-install.sh status              # czy budowa jeszcze trwa, czy serwer działa
sudo sh linux-port/tools/vps-install.sh passwords           # hasła kont admin i test
sudo sh linux-port/tools/vps-install.sh add-account LOGIN   # konto dla znajomego
sudo sh linux-port/tools/vps-install.sh logs                # ostatnie logi
sudo sh linux-port/tools/vps-install.sh update              # tylko 2.x: aktualizacja do nowej wersji z GitHuba

The Yohara package also contains its own instaluj-vps.sh, which downloads the package by itself and launches this installer. It works only with a direct link to the full Yohara package (--paczka URL, --folder KATALOG, --jezyk KOD) and does not do updates. The file to download from the wiki (above) installs 2.x.

For safety, the panels are visible only on the VPS itself. You open them through an SSH tunnel – on your own computer:

ssh -L 7788:127.0.0.1:7788 -L 7790:127.0.0.1:7790 root@ADRES_VPS

and in a browser go to http://127.0.0.1:7788 (classic panel) and http://127.0.0.1:7790 (advanced panel), as long as the SSH window stays open. ItemShop (port 7791) is available to players at the server address.

In the game client add a server with the VPS address, e.g. with the file Ustaw_serwer_VPS.bat. In 2.x you can also add the server in the MT2009-Patcher (the VPS server icon at the top right). The game ports are TCP 11000 and 13000–13003 (13003 is a separate map core: in 2.x the Enchanted Forest and the level 90 maps, in Yohara the Yohara maps) – if your VPS provider has its own firewall, open them there.

Step by step

A guide from a clean Debian 13 to a working server. On Ubuntu it is the same (in the Docker repository, replace debian with ubuntu).

1. What you need

  • A machine with Debian 13 (a VPS or mini PC, with or without a desktop) and an account with sudo.
  • An x86 (Intel/AMD) processor – the game server does not run on ARM.
  • At least 4 GB RAM and 60–80 GB of disk (more memory for thousands of bots or a second channel).
  • Internet – Docker downloads base images during the build.
  • The full server package from Discord. From the 2.x package you only need the Serwer folder.

Do not use the installer/install.sh installers or updaters from other projects. They overwrite files with another engine version and break a working server.

2. System and Docker

System update and tools:

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl gnupg unzip

Docker from the Docker repository (the Debian repository sometimes has an older version without Compose v2):

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

Check that it works:

sudo docker run hello-world
sudo docker compose version

The first command prints Docker’s greeting, the second the Compose version number (v2.x). In this guide all Docker commands have sudo. If you add yourself to the docker group (sudo usermod -aG docker $USER, then log in again), use plain docker everywhere and do not mix it with sudo docker.

3. The server package on the machine

You upload the zip file to the server from your own computer, e.g. with scp:

scp MT2009-PLUS.zip UZYTKOWNIK@ADRES_SERWERA:~/

or with WinSCP / FileZilla. If you have a direct link, you can download it right on the server: wget -O MT2009-PLUS.zip "LINK".

Unpack the server folder to /opt/metin2/stack (check the folder name inside the zip with unzip -l; in the 2.x package it is <package folder>/Serwer):

sudo mkdir -p /opt/metin2/_new
cd /opt/metin2/_new
sudo unzip -q ~/MT2009-PLUS.zip
sudo mv "/opt/metin2/_new/<folder serwera>" /opt/metin2/stack
sudo rm -rf /opt/metin2/_new
cat /opt/metin2/stack/VERSION

/opt/metin2/stack should contain, among other things, VERSION, linux-port/, launcher/ and tools/.

4. The .env file

The whole configuration is in one file:

cd /opt/metin2/stack/linux-port/docker
sudo cp .env.example .env
sudo nano .env

Only the “1. REQUIRED” section at the top is enough:

Setting What to enter
M2_PUBLIC_ADDRESS the machine’s public IP address or a domain (curl -4 ifconfig.me). Without it the client will hang on “connecting to the server”
M2_DB_ROOT_PASSWORD, M2_DB_PASSWORD two different, long passwords, e.g. from openssl rand -hex 24 (no spaces or quotation marks)
M2_DB_PUBLISH_PORT leave 3306 unless the port is taken
M2_PANEL_PASSWORD you can leave it empty – the panel generates a password on first start
M2_DEFAULT_LANGUAGE Yohara only: the server’s default language, e.g. pl
PLAYERBOT_AUTOSPAWN_COUNT how many bots start with the game; for the first start use fewer, e.g. 50 – you can change it later in the panel

Leave M2_COMPOSE_PROJECT_NAME and M2_CONTAINER_PREFIX empty. You only need to set them for a second, separate copy of the server on the same machine.

5. First start

cd /opt/metin2/stack/linux-port/docker
sudo docker compose up -d --build

The first build compiles the server from scratch: from over ten to several dozen minutes. The console may stay silent for a long time – that is normal.

6. Is everything working

sudo docker compose ps

The services have the status Up / healthy. The *-playerbot-migrate container finishes once (Exited (0)) – that is as intended.

The panel password, if you left it empty:

sudo docker compose logs panel | grep -A4 PASSWORD

Panels: http://SERVER_ADDRESS:7788 (classic, bot map) and http://SERVER_ADDRESS:7790 (advanced panel), ItemShop: http://SERVER_ADDRESS:7791. In the game: the account admin / admin with four GM characters – change that password before anyone else sees the server.

Something did not start? Check the logs first:

sudo docker compose logs game --tail 80
sudo docker compose logs panel --tail 40

Game ports: TCP 11000 and 13000–13003 (13000–13012 with a second channel) – open them in the firewall and at your VPS provider.

7. Database from your computer (optional)

The database listens only on the server’s 127.0.0.1.

  • SSH tunnel (safer) – in Navicat / HeidiSQL set up a connection over SSH to this machine, and in it use 127.0.0.1:3306.
  • Open port (more convenient, less safe) – next to docker-compose.yml create docker-compose.override.yml:
services:
  mariadb:
    ports: !override
      - "0.0.0.0:3306:3306"

and run sudo docker compose up -d. You log in as root (password M2_DB_ROOT_PASSWORD) or metin2 (password M2_DB_PASSWORD). The database is then protected only by the strength of the password – do this knowingly.

8. Updating

MT2009 PLUS 2.x – from GitHub:

cd /opt/metin2/stack
sudo sh linux-port/tools/update.sh check   # tylko pokazuje wersje
sudo sh linux-port/tools/update.sh run     # instaluje najnowszą

9. Useful commands

sudo docker compose ps            # stan
sudo docker compose down          # zatrzymanie (baza zostaje)
sudo docker compose up -d         # start
sudo docker compose logs -f game  # logi gry

What not to do:

  • docker compose down -v – -v deletes the database.
  • Installers and updaters from other projects.
  • Manual changes in game/src/ without a rebuild – see Database and server files.

If something does not start after an update or after applying a patch: nothing has been deleted, the previous images are still on the disk. Check the logs, fix the problem and run sudo docker compose up -d --build again.

See also