lklacar/q3js

Clone the repository and install the workspace dependencies:

git clone https://github.com/lklacar/q3js.git
cd q3js
pnpm install --frozen-lockfile

Build the WebAssembly client:

make client

Create the website's local configuration:

cp website/.env.example website/.env.local

Set NEXT_PUBLIC_Q3JS_STATIC_URL=http://localhost:8081 in website/.env.local. Then start the stack in separate terminals from the repository root:

# Terminal 1 — PostgreSQL
docker compose up -d database

# Terminal 2 — master API
make master-run

# Terminal 3 — game server and WebSocket gateway
export Q3JS_DATA_DIR=/absolute/path/to/quake3-data
Q3JS_BASEPATH="$Q3JS_DATA_DIR" make server-run

# Terminal 4 — PK3 and manifest server
export Q3JS_DATA_DIR=/absolute/path/to/quake3-data
docker build -f static/Dockerfile -t q3js-static .
docker run --rm -p 8081:8080 -v "$Q3JS_DATA_DIR:/data:ro" q3js-static

# Terminal 5 — website
pnpm --dir website dev

Open http://localhost:3000. The local game server publishes its gateway at ws://localhost:27961/ws and registers itself with the master automatically.

Local ports

| Port | Protocol | Service | | --- | --- | --- | | 3000 | HTTP | Website | | 5432 | TCP | PostgreSQL | | 8080 | HTTP | Master API and Swagger UI | | 8081 | HTTP | Local static asset server | | 27960 | UDP | Quake III dedicated server | | 27961 | HTTP / WebSocket | Gateway and health endpoint |