Docker deployment

Overview

The official image is published at ghcr.io/landsandboat/server:latest (Ubuntu-based) and ghcr.io/landsandboat/server:alpine (Alpine-based). The image contains the compiled server binaries, scripts, SQL, and tools — but not a database.

Prerequisites: mesh volumes

Navigation and line-of-sight meshes are shipped in a separate image. You must load them into named Docker volumes before starting the server:

docker run --rm \
  -v losmeshes:/losmeshes \
  -v navmeshes:/navmeshes \
  ghcr.io/landsandboat/ximeshes:latest

This is a one-time operation. The volumes (losmeshes, navmeshes) persist across container restarts.

Database configuration

A database is not included in the image. You must provide connection credentials via environment variables:

Variable	Also accepted as	Description
`XI_NETWORK_SQL_HOST`	—	Database hostname or IP
`XI_NETWORK_SQL_PORT`	—	Database port (default `3306`)
`XI_NETWORK_SQL_DATABASE`	`MARIADB_DATABASE`	Database name
`XI_NETWORK_SQL_LOGIN`	`MARIADB_USER`	Database username
`XI_NETWORK_SQL_PASSWORD`	`MARIADB_PASSWORD`	Database password

Running the server

# Start a server with no database (install MariaDB inside or connect externally)
docker run --name some-lsb-server \
  -p 54001:54001 \
  -p 54002:54002 \
  -p 54230:54230 \
  -p 54231:54231 \
  -v losmeshes:/server/losmeshes \
  -v navmeshes:/server/navmeshes \
  -it ghcr.io/landsandboat/server:latest

docker run --name some-lsb-server \
  -p 54001:54001 \
  -p 54002:54002 \
  -p 54230:54230 \
  -p 54231:54231 \
  -v losmeshes:/server/losmeshes \
  -v navmeshes:/server/navmeshes \
  --network server_default \
  -e XI_NETWORK_SQL_HOST=database \
  -e XI_NETWORK_SQL_PORT=3306 \
  -e XI_NETWORK_SQL_DATABASE=xidb \
  -e XI_NETWORK_SQL_LOGIN=xiadmin \
  -e XI_NETWORK_SQL_PASSWORD='password' \
  -it ghcr.io/landsandboat/server:latest

Docker Compose

Docker Compose is the recommended approach. It manages all services, health checks, and startup order automatically.

x-dbcreds: &dbcreds
  # MARIADB_ROOT_PASSWORD required if setting up fresh database.
  # Or generate a random root password and print it to build log:
  # MARIADB_RANDOM_ROOT_PASSWORD: true
  MARIADB_ROOT_PASSWORD: 'root'
  MARIADB_DATABASE: xidb
  MARIADB_USER: xiadmin
  MARIADB_PASSWORD: 'password'

x-common: &common
  image: ghcr.io/landsandboat/server:latest
  environment:
    <<: *dbcreds
    XI_NETWORK_HTTP_HOST: 0.0.0.0
    XI_NETWORK_ZMQ_IP: world
    XI_NETWORK_SQL_HOST: database
    # XI_{file}_{setting}: value
  volumes:
    - losmeshes:/server/losmeshes
    - navmeshes:/server/navmeshes
    # - ./config.yaml:/server/tools/config.yaml
    # - ./map.lua:/server/settings/map.lua
    # - ./modules:/server/modules

services:
  database:
    image: mariadb:lts
    restart: always
    command: ['--character-set-server=utf8mb4', '--collation-server=utf8mb4_general_ci']
    environment:
      <<: *dbcreds
    volumes:
      - database:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3

  database-update:
    <<: *common
    command: ["python", "/server/tools/dbtool.py", "update"]
    depends_on:
      database:
        condition: service_healthy

  connect:
    <<: *common
    command: ["/server/xi_connect"]
    restart: unless-stopped
    ports:
      - "54001:54001"
      - "54230:54230"
      - "54231:54231"
    depends_on:
      database:
        condition: service_healthy
        restart: true
      database-update:
        condition: service_completed_successfully

  search:
    <<: *common
    command: ["/server/xi_search"]
    restart: unless-stopped
    ports:
      - "54002:54002"
    depends_on:
      database:
        condition: service_healthy
        restart: true
      database-update:
        condition: service_completed_successfully

  world:
    <<: *common
    command: ["/server/xi_world"]
    restart: unless-stopped
    ports:
      - "8088:8088"
    depends_on:
      database:
        condition: service_healthy
        restart: true
      database-update:
        condition: service_completed_successfully

  map:
    <<: *common
    command: ["/server/xi_map"]
    restart: unless-stopped
    ports:
      - "54230:54230/udp"
    depends_on:
      database:
        condition: service_healthy
        restart: true
      database-update:
        condition: service_completed_successfully
      world:
        condition: service_started

volumes:
  database:
  losmeshes:
    external: true
  navmeshes:
    external: true

Volume mounts

Mount path	Purpose
`/server/losmeshes`	Line-of-sight mesh data (load from `ximeshes` image)
`/server/navmeshes`	Navigation mesh data (load from `ximeshes` image)
`/server/tools/config.yaml`	dbtool configuration (controls express updates, backups)
`/server/settings/map.lua`	Override individual settings files
`/server/modules`	Lua and SQL runtime modules

Customization

Settings via environment variables

Any setting in a settings/*.lua file can be overridden with an environment variable using the format:

-e XI_{file}_{setting}=value

Examples:

-e XI_NETWORK_HTTP_HOST=0.0.0.0     # sets HTTP_HOST in settings/network.lua
-e XI_NETWORK_ZMQ_IP=world          # sets ZMQ_IP in settings/network.lua
-e XI_MAIN_SERVER_NAME=MyServer     # sets SERVER_NAME in settings/main.lua

Settings files

For more extensive changes, bind-mount an entire settings file:

--mount type=bind,src="$(pwd)"/settings/map.lua,dst=/server/settings/map.lua

Modules

Bind-mount a modules directory to load Lua and SQL runtime modules:

--mount type=bind,src="$(pwd)"/modules,dst=/server/modules

C++ modules require building a custom image. See Build from source for build-arg options.

Default user

The image runs as user xiadmin (UID 1000, GID 1000). Ensure that bind-mounted files and directories are readable by UID 1000.

Port reference

Port	Protocol	Service	Purpose
54001	TCP	`xi_connect`	Login view
54002	TCP	`xi_search`	Search / auction house
54230	TCP	`xi_connect`	Login data
54230	UDP	`xi_map`	Zone data
54231	TCP	`xi_connect`	Login auth
8088	TCP	`xi_world`	HTTP API (disabled by default)

Introduction

Installation

Database Setup

Overview

Prerequisites: mesh volumes

Database configuration

Running the server

Docker Compose

Volume mounts

Customization

Settings via environment variables

Settings files

Modules

Default user

Port reference

​Overview

​Prerequisites: mesh volumes

​Database configuration

​Running the server

​Docker Compose

​Volume mounts

​Customization

​Settings via environment variables

​Settings files

​Modules

​Default user

​Port reference

Overview

Prerequisites: mesh volumes

Database configuration

Running the server

Docker Compose

Volume mounts

Customization

Settings via environment variables

Settings files

Modules

Default user

Port reference