CSJS

Field manual / Local stack

Run CSJS

CSJS has three independent application services: the Next.js website, the Java/Quarkus master, and the Xash3D game server with its browser gateway. Start only the parts you are working on, or use Compose for the complete stack.

01

Install the toolchain

You need Docker with Compose, Node.js 24 with pnpm 11, Java 17, and zip. Then install the workspace dependencies:

pnpm install --frozen-lockfile
02

Run services separately

Use separate terminals when developing. Starting the game server does not start the master, database, or website.

docker compose up -d database
make master-run
make server-run
pnpm --dir website dev

The website is at http://localhost:3000, the master at http://localhost:8080, the browser gateway at http://localhost:27016, and native game traffic uses UDP 27015.

03

Run the complete stack

For an integrated local deployment, let Compose build and start all four containers:

make server-up

Open the CSJS server browser. Follow logs with make logs and stop everything with make server-down.

04

Publish a game server

Expose UDP 27015 for native game traffic and TCP 27016 for HTTP/WebSocket traffic. Configure the public gateway address before registering with the master:

CSJS_PUBLISH_HOST=cs.example.com
CSJS_PUBLISH_PORT=443
CSJS_SECURE=true
CSJS_MASTER_URL=https://master.example.com
CSJS_EVENT_CLIENT_SECRET=csjs_your-approved-per-server-secret

CSJS_HOSTNAME, CSJS_MAP, and CSJS_MAXPLAYERS control the initial server. Request approval on the custom server page, then set the issued secret. It authenticates the listing and telemetry and binds to the first published host and port that uses it.

05

Verify each boundary

curl -fsS http://localhost:27016/healthz
curl -fsS http://localhost:8080/q/health
docker compose ps

If the game is healthy but absent from the website, verify the master URL, approved secret, and published host. A secret already bound to another host or port is rejected. If it is listed but cannot launch, verify that the browser can connect to /ws on the selected gateway.