Docker and Linux Services

A release carries two ways to run it on a Linux machine without GoMMO Manager:

• docker/gommoctl builds images from the unpacked release and runs it under Docker Compose.
• server/linux/install.sh copies the release into /opt/<game> and installs two systemd services, a gameserver and a webserver.

Both read the same settings.ini and keep the same folders, so you can start with one and move to the other.

Docker

What You Need

• Docker Engine with the Compose plugin, Compose 2.24 or newer (docker compose version).
• The release unpacked on the Docker host (unzip <game>-v<version>.zip). Edit its files there too: an editor that saves Windows line endings into docker.env leaves a stray character at the end of every value.

Start It

From the top of the unpacked release:

sh docker/gommoctl up

The first up builds three images (gommo-<game>-gameserver, -webserver and -tools), creates the state folders, writes docker.env from docker/docker.env.example, and waits until both servers report healthy. The gameserver's first start imports its content, which can take several minutes.

status prints the one-time control-panel password (SUPER_PASSWORD) until the first Super Administrator signs in.

Where Your Files Live

The images hold only what a release replaces: the binaries, the game data and the schema. Everything the servers write is a folder of the release, mounted into the containers.

An install upgraded from a release that still used settings.cfg keeps that file until the game server converts it to settings.ini on its first start (configuration). On RF Online, World of Kung Fu and DragonSoul gommoctl reads the old file for that one start. Gate to Heavens Classic mounts server/settings.ini as a single file, so there gommoctl stops and asks you to start the server once with GoMMO Manager or server/start-server.sh first.

The containers run as your own user, or as uid 10001 when you run gommoctl as root. Set GOMMO_UID and GOMMO_GID to choose another. GOMMO_GAME_BIND and GOMMO_WEB_BIND set the address the ports listen on (default every address), GOMMO_WEB_PORT the website port, and TZ the time zone (default the host's).

Settings From the Environment: docker.env

Any settings.ini key can be set from docker.env instead, one line per key:

GOMMO_DATABASE_HOST=mysql
GOMMO_DATABASE_PASSWORD_FILE=/srv/gommo/settings/mysql-password

• GOMMO_<KEY>=value sets <KEY>. It beats the value in settings.ini.
• GOMMO_<KEY>_FILE=<path> reads the value from a file, so a password can sit in a file of its own. /srv/gommo/ inside a container is the top of the release.
• An empty value is ignored. To blank a key through the environment, set it to EMPTY.
• SUPER_PASSWORD cannot be set this way; the server refuses to start if you try. The webserver writes and clears it itself.
• Put a value holding spaces, #, // or $ in single quotes: GOMMO_DATABASE_PASSWORD='my #1 pa$s'. Docker Compose cuts an unquoted value at # and expands $.

The same GOMMO_<KEY> lines work in server.env for the systemd services below.

The Address Players Are Sent To

A server inside a container cannot see the address players reach it on. The games that send the client a second address need it set:

• World of Kung Fu and DragonSoul: GOMMO_ADVERTISE_IP=<your public IP or hostname> in settings/docker.env, or ADVERTISE_IP in settings.ini. Without it, players get past the login and cannot reach the world.
• Gate to Heavens Classic: GTH_EXTERNAL_IP=<your public IP> in server/docker.env, or [gameserver] EXTERNAL_IP in server/settings.ini. Without it, only the Docker host can log in.

RF Online does not need one. gommoctl up warns when a game that needs it has none.

MySQL

SQLite in db/ is the default and needs nothing. For MySQL, set DATABASE_PROVIDER = mysql:

• The bundled MySQL 8.4 container: set DATABASE_HOST = mysql and gommoctl starts it with the stack. On RF Online, World of Kung Fu and DragonSoul it uses DATABASE_PASSWORD as its root password, so keep DATABASE_USERNAME = root. On Gate to Heavens Classic it loads database-mysql/ on its first start, which creates the gth user and password the shipped settings.ini already holds.
• A MySQL server on the Docker host: DATABASE_HOST = host.docker.internal, not 127.0.0.1. Inside a container 127.0.0.1 is the container. The MySQL server must listen on the Docker bridge address.

HTTPS

Set TLS_DOMAIN to a public hostname whose DNS already points at this machine, with ports 80 and 443 reachable. gommoctl then adds the TLS overlay: the webserver gets a Let's Encrypt certificate, serves the site on 443 and answers the certificate challenge on 80. Certificates are kept in certs/, so they survive restarts and upgrades.

Backups

gommoctl backup writes GoMMO Manager's backup layout (a dated folder with a backup.json), so either tool lists and restores the other's backups. SQLite is copied with VACUUM INTO while the server runs, and a database that has not changed since the previous backup is hard-linked rather than copied. MySQL is copied with mysqldump. BACKUP_KEEP in manager.ini sets how many are kept (default 10). For a nightly backup, add a cron line:

0 4 * * * cd /srv/rf2232 && sh docker/gommoctl backup scheduled

Backups covers what to keep and how to test a restore.

Upgrading

Unpack the new release into a folder of its own, then from the running install:

sh docker/gommoctl upgrade /path/to/new-release

It takes a before-update backup, stops the servers, moves the old program files into updates/<stamp>/, copies the new ones in, rebuilds the images and starts again. Your settings, databases, logs and backups stay where they are. The previous images stay tagged :previous.

On RF Online the shipped content database is replaced too; on MySQL it is dropped and imported again on the next start. On Gate to Heavens Classic client/ is replaced, because a client must match its server: point the new one at your public address again (client/data/server.cfg).

Linux Services Without Docker

From the top of the unpacked release:

sudo sh server/linux/install.sh --dry-run    # print every step and both unit files
sudo sh server/linux/install.sh              # install into /opt/<game> and start

It creates a system user named after the game, copies the release into /opt/<game>, gives the program files to root and the state folders to that user, and writes and starts two hardened systemd units, <game>-gameserver.service and <game>-webserver.service.

The working directory is set for you: the release's top folder on RF Online, World of Kung Fu and DragonSoul, and server/ on Gate to Heavens Classic. The servers find their database and content relative to it.

server.env sits beside settings.ini (settings/server.env, or server/server.env on Gate to Heavens Classic) and is the services' environment file. The GOMMO_<KEY>=value and GOMMO_<KEY>_FILE=<path> lines described for docker.env above work there too, with the file path given as a path on this machine. Restart the gameserver after changing it:

sudo systemctl restart <game>-gameserver
journalctl -u <game>-gameserver -f

To upgrade, unpack the new release and run its server/linux/install.sh with the same --prefix. It stops the services, replaces the program files, keeps your settings, databases, logs and backups, and starts them again.

Ports

Open these to players. The defaults below are what a release ships; configuration covers moving them.

The website is TCP 8080, or 80 and 443 with TLS_DOMAIN set. On RF Online the second game port is the launcher's sign-in port. Keep the stats port and MySQL's 3306 closed: the stats port carries the control panel's admin commands and listens on loopback only. Both install.sh and gommoctl status print the ports your settings actually use.

Gate to Heavens (moderngth) has no self-host release; the same Docker files build it from a folder laid out like the Classic release.

Credit

The Docker workflow builds on the one mvolotov published at github.com/mvolotov/RF-OSO-Docker, suggested on the Ideas board as IDEA-2. gommoctl started from its rfctl script.