Run your own Q3JS server

Create a working directory with a baseq3 folder:

mkdir -p my-q3-server/baseq3
cd my-q3-server

Copy pak0.pk3 through pak8.pk3 directly into baseq3. Do not add another nested baseq3 directory.

my-q3-server/
└── baseq3/
    ├── pak0.pk3
    ├── pak1.pk3
    ├── ...
    └── pak8.pk3

Confirm that Docker will see the expected files:

ls -1 baseq3/pak*.pk3

Run the pinned 1.0.0 image first. The named state volume preserves generated server files without changing your read-only game-data directory.

docker run --rm   --name q3js-server-test   -p 27960:27960/udp   -p 27961:27961/tcp   -v "$(pwd)/baseq3:/data/baseq3:ro"   -v q3js-server-state:/state   lukaklacar/q3js-server:1.0.0

Wait for Q3JS server ready, then open another terminal and check the gateway:

curl -fsS http://localhost:27961/healthz

A successful response means both the game server and browser gateway are ready. Stop the test with Control-C.

You need the address that internet players can use to reach this machine. Use a public IPv4 address or a DNS hostname that points to it. Do not use localhost, 0.0.0.0, or a private address such as 192.168.x.x.

Replace YOUR_PUBLIC_IP_OR_HOSTNAME, then run this from my-q3-server:

docker run -d   --name q3js-server   --restart unless-stopped   -p 27960:27960/udp   -p 27961:27961/tcp   -v "$(pwd)/baseq3:/data/baseq3:ro"   -v q3js-server-state:/state   -e Q3JS_MASTER_URL=https://master.q3js.com   -e Q3JS_PUBLISH_HOST=YOUR_PUBLIC_IP_OR_HOSTNAME   -e Q3JS_PUBLISH_PORT=27961   -e Q3JS_SECURE=false   -e 'Q3JS_SERVER_CONFIG=seta sv_hostname "My Q3JS Server"; seta sv_maxclients "16"; seta g_gametype "0"; seta fraglimit "20"; seta timelimit "15"; map q3dm17'   lukaklacar/q3js-server:1.0.0

The server sends an anonymous heartbeat to master.q3js.com and is listed as a community server. No private Q3JS credential is required.

If the Docker host is behind a router, forward both ports to its LAN address. Also allow them through the host firewall and any cloud-provider firewall.

Carrier-grade NAT can prevent inbound connections even when local forwarding is correct. If your router has no public address, request one from your ISP or run the server on a VPS.

Check that the container is running and healthy:

docker ps --filter name=q3js-server
docker inspect --format='{{.State.Health.Status}}' q3js-server
docker logs --tail 100 q3js-server

Verify the local gateway directly:

curl -fsS http://localhost:27961/healthz

Finally, open the Q3JS server browser. Registration is quick, but the master must also be able to connect back to the published host and query the server before it can display it.

Follow live logs, restart the server, or remove the container with:

docker logs -f q3js-server
docker restart q3js-server
docker rm -f q3js-server

Removing the container does not remove q3js-server-state. Re-run the public command to recreate it. Keep a versioned image tag for predictable deployments; use latest only when you intentionally want the newest release and have reviewed its migration notes.