TaystJKDocumentation GitHub

Administrator guide

Run a server

Start with a small, private server; confirm its settings and download list; then expose the game and HTTP ports to the internet.

What you need

Choose how to run it

Both run the same dedicated server and the same game module; they differ in how you install, update and restart it. Your selection is saved on this device.

Run the server with

Docker Compose

The published image contains the dedicated server for 64-bit Linux together with the bundled server configs, Compose restarts it automatically (docker-compose.yml), and your changes live in a mounted directory that survives image updates. You need Docker on the host.

The repository ships a Docker image and docker-compose.yml. Use that definition from a TaystJK source checkout when possible; it supports both pulling the published image and building the server locally.

For the published image, the relevant files are:

taystjk-server/
├── docker-compose.yml
├── base/
│   ├── assets0.pk3
│   ├── assets1.pk3
│   ├── assets2.pk3
│   └── assets3.pk3
└── homepath/

The checked-in Compose file defines the normal registry-backed service and an optional build profile. Its service definitions are:

services:
  taystjk:
    image: ghcr.io/taysta/taystjk:latest
    ports:
      - "29070:29070/udp"
      - "18200:18200/tcp"
    volumes:
      - ./base:/opt/taystjk/cdpath/base
      - ./homepath:/opt/taystjk/homepath
    environment:
      - TJK_MOD=taystjk
      - TJK_ARCH=x86_64
    restart: unless-stopped

  taystjk-build:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        TAYSTJK_REF: master
        TAYSTJK_COMMIT: unknown
    profiles: ["build"]
    ports:
      - "29070:29070/udp"
      - "18200:18200/tcp"
    volumes:
      - ./base:/opt/taystjk/cdpath/base
      - ./homepath:/opt/taystjk/homepath
    environment:
      - TJK_MOD=taystjk
      - TJK_ARCH=x86_64
    restart: unless-stopped

To run the published image:

docker compose pull taystjk
docker compose up -d taystjk
docker compose logs -f taystjk

The taystjk-build service needs the repository’s complete source checkout and Dockerfile. From that checkout, use the opt-in profile when you need an image built from the current source:

docker compose --profile build up -d --build taystjk-build
docker compose logs -f taystjk-build

Both services use the same ports, asset mount, homepath mount, architecture, and mod selection as TaystJK’s checked-in definition; do not start both at once. The image already contains TaystJK’s shipped server.cfg and the game-mode, vote and ban configs that go with it, installs them under basepath/taystjk/, and automatically launches with +exec server.cfg. They are written for TaystJK’s bundled jaPRO game module; bundled server configs describes each file. Start the container once with that configuration before changing it.

The remaining commands in this guide use the published-image service name, taystjk. Substitute taystjk-build when you are running the source-build profile.

To customize the configuration shipped by your image, copy the file you want to change into the mounted homepath:

mkdir -p homepath/taystjk
docker compose cp \
  taystjk:/opt/taystjk/basepath/taystjk/server.cfg \
  ./homepath/taystjk/server.cfg

Edit the copied file, then apply it with docker compose restart taystjk. The homepath copy takes priority over the image’s basepath copy and persists across image updates. The same works for bans.cfg, votes.cfg, default.cfg and the mode files. Custom PK3s, reflists, logs, and configuration also belong under homepath/taystjk/. Use docker compose down to stop the server.

Dedicated server

You start the dedicated server executable on the host yourself, and you manage its files, its configuration and restarting it after a crash or reboot.

Extract the server files and retain all libraries included with the release. Put the retail assets under base/ and TaystJK assets under taystjk/. Native releases do not include a server.cfg: copy the Docker image’s configs from scripts/docker/ into taystjk/, as bundled server configs explains, or write your own. Then launch:

./taystjkded.x86_64 \
  +set dedicated 2 \
  +set net_port 29070 \
  +set fs_game taystjk \
  +exec server.cfg

On Windows, use the .exe dedicated-server binary from the release. A service manager such as systemd or Docker should restart a public server after a crash or host reboot.

Run the TaystJK server engine with another mod

The dedicated executable and the server-side game rules are separate. You can use the TaystJK dedicated engine while loading another mod’s native jampgame library, such as JA+ or JA++. In this arrangement TaystJK supplies engine features, networking, and server administration, while the selected mod supplies gameplay. TaystJK game-module commands and cvars are unavailable unless the other mod implements them too.

Install the mod exactly as its own documentation requires, in a directory beside base/. The library must match the dedicated executable’s operating system and architecture. For example, a 64-bit Linux server needs a compatible japlus/jampgamex86_64.so; it cannot load a 32-bit jampgamei386.so. If a mod is available only as a 32-bit library, use the matching 32-bit TaystJK dedicated build and its runtime dependencies. JA+ 2.4 is one: it ships only jampgamei386.so for Linux, so it needs taystjkded.i386.

Linux mods ship the server library loose, as JA+ 2.4’s jampgamei386.so is, but Windows mods often pack jampgamex86.dll in a PK3; JA+ 2.4 ships it only in jampgamex86.pk3. The Windows dedicated server loads it from there with +set com_unpackLibraries 1 on the command line, or you can extract it beside the PK3 as mods that package native libraries inside a PK3 describes. Linux and macOS servers never unpack a library from a PK3 (sys_unix.cpp). When the mod directory has no library the server can load, the engine falls back to TaystJK’s own jaPRO module in taystjk/ (sys_main.cpp), so check that serverinfo shows the mod’s gamename before opening the server.

Dedicated builds default fs_forcegame to an empty string so that fs_game can select the server mod. Leave it empty and launch a 64-bit JA++ server module with:

./taystjkded.x86_64 \
  +set dedicated 2 \
  +set net_port 29070 \
  +set fs_game japlus \
  +exec server.cfg

or JA+ 2.4 on the 32-bit server with:

./taystjkded.i386 \
  +set dedicated 2 \
  +set net_port 29070 \
  +set fs_game japlus \
  +exec server.cfg

The engine loads either module interface by itself. It looks for the newer GetModuleAPI entry point first and, when a library does not export one, falls back to the older dllEntry/vmMain interface that JA+ and other older modules use (sv_gameapi.cpp). A legacy start is reported as VM_CreateLegacy: jampgame... succeeded. vm_legacy is not needed for this; it only forces the older interface on a library that has both (when to use vm_legacy). Also check path to confirm that japlus/ is active and inspect the mod’s version cvar before opening the server publicly.

For Docker, put the mod and its configuration under the mounted homepath/japlus/ and set TJK_MOD=japlus. For a 32-bit module such as JA+ 2.4, also set TJK_ARCH=i386: the image contains both the x86_64 and i386 dedicated servers and runs the one TJK_ARCH names (run.sh). If you set TJK_OPTS for other launch options, keep +exec server.cfg in it: the image’s default TJK_OPTS is just that command (Dockerfile), and setting the variable replaces it. The image’s bundled configs live in taystjk/, so they do not load for another mod; supply that mod’s own server.cfg, or build one from base Jedi Academy’s settings with the server config generator. The image does not include third-party mod files; supply and maintain them yourself. Test upgrades privately because a mod may depend on engine-specific behavior outside the standard module interface.

Customize the shipped server.cfg

The supplied file starts the server on one map, mp/ffa3 in FFA, and already turns on downloads: the built-in HTTP server on TCP 18200, and the UDP downloader for clients that cannot use HTTP. Change its example identity and fill in the passwords, which ship empty:

// Identity
seta sv_hostname "My TaystJK server"
seta g_motd "Welcome! Have fun"

// Passwords. Keep rconpassword on a "set" line: docker stop reads it from here.
set rconpassword "replace-with-a-long-random-secret"
seta g_fullAdminPass "replace-with-another-secret"
seta g_juniorAdminPass "and-a-third"

To start from a full set with these already filled in, build it with the server config generator instead.

Keep server settings in this file and gameplay in default.cfg and the mode files, so that loading a mode never changes them. Bundled server configs covers the game modes and vote options, and what to do if you want the map to change by itself. jaPRO server setup covers accounts, admins, voting and bans.

Changes to sv_httpDownloads and sv_httpServerPort are latched; restart the dedicated server after changing them. Clients connect to the port number the server advertises, so keep the same number on both sides of the Compose port mapping: to use 18300, publish 18300:18300/tcp and set sv_httpServerPort 18300.

Verify before going public

  1. Join from a second machine or network, not only localhost.
  2. Confirm UDP 29070 is reachable and the server appears in the expected master list.
  3. Load every map you plan to run, and every game mode you plan to offer, and watch the server console for missing files.
  4. Run sv_referencedPakNames; make sure it contains every required client PK3 and no private or unnecessary archive.
  5. Join with a clean client and accept the download prompt. Confirm the transfer uses HTTP and the downloaded map loads.
  6. Test RCON, then keep the password out of screenshots, logs, and public configuration files.

Use the console reference to inspect server-owned cvars and their exact source registrations.

If the server does not appear in the list, or it keeps rewriting your config, both have their own entries on troubleshooting. They are the two things that go wrong most often here.

Last changed History Edit this page on GitHub