ql-lg-server/README.md

# ql-lg-server

A Quake Live server for lightning gun practice, run with Docker on Linux.

Everyone spawns with the lightning gun and 200 HP. Damage you deal heals you by the same amount, up to 200, and health above 100 drops back by 1 per second. There is no knockback and there are no items. The server never leaves warmup, so there is no match, no ready-up and no score reset: people join, pair up and duel. This is the same format the x76 LG duel servers use.

It also has an optional training bot (`lgbot`) that only uses the lightning gun and strafes on the ground instead of jumping around.

Linux only. Quake Live's dedicated server is only released for Linux, so there is no Windows version.

## Requirements

- A Linux machine: a VPS, a home server or your own desktop. The server uses about 3% of one CPU core and 50 MB of RAM when idle.
- Docker with the compose plugin ([install guide](https://docs.docker.com/engine/install/)). Your user must be in the `docker` group (`sudo usermod -aG docker $USER`, then log out and back in).
- `git`, `python3`, about 2 GB of free disk space.
- Players need Quake Live on Steam.

## Install

```sh
git clone https://git.userevolt.app/esef/ql-lg-server.git
cd ql-lg-server
./setup.sh
```

Run it as your normal user, not root. Setup asks four questions (server name, listed or not, join password, port; Enter keeps the default), then downloads the game from Steam (about 1 GB), builds minqlx and starts the server. At the end it prints the `/connect` addresses.

On a machine that runs all the time, also run `./scripts/install-cron.sh`. It adds a watchdog, a nightly backup and a daily restart (skipped while someone is playing).

## Joining

Players open the Quake Live console with `~` and type `/connect <address>:27960`.

- Same machine: `/connect 127.0.0.1:27960`
- Same network: the machine's LAN address, e.g. `/connect 192.168.1.20:27960`
- Over the internet: either forward UDP port 27960 on your router to this machine and give out your public IP, or put everyone on a VPN such as Tailscale or ZeroTier and use the VPN address.

A listed server also shows up in the in-game server browser after a few minutes. That needs the port forward too.

[docs/PLAYERS.md](docs/PLAYERS.md) is a page you can send to players.

## Everyday commands

Run these from the repo folder.

```sh
./rcon status                 # who is on
./rcon say hello
./rcon addbot hunter 5        # a normal bot to shoot at; ./rcon kick allbots removes bots
./lgbot                       # add the training bot (asks aim and movement level)
docker compose restart        # restart the server
docker compose stop           # stop it (docker compose start to start again)
./setup.sh --update           # update the game from Steam
```

`./rcon` with no arguments opens a console prompt. The RCON password is generated by setup and read from `secrets/` automatically, so you never type it.

## Settings

All per-server settings live in `.env`. After changing it, run `docker compose up -d`.

| Setting | Default | |
|---|---|---|
| `QL_HOSTNAME` | `LG Vampiric FFA` | name in the server browser (`^1`..`^7` for colors) |
| `QL_LISTED` | `yes` | `no` = not in the browser, join by address only |
| `QL_PASSWORD` | empty | join password |
| `QL_MAXCLIENTS` | `16` | |
| `QL_FACTORY` | `lgvamp` | game mode, see below |
| `QL_MAP` | `thunderstruck` | stock maps only |
| `QL_WELCOME` | short rules text | message shown to each player on join; empty = none |
| `QL_RECORD` | `0` | movement recording for the training bot, see [docs/ADMIN.md](docs/ADMIN.md) |
| `QL_PORT` / `QL_RCON_PORT` | `27960` / `28960` | game port (UDP) / RCON port (TCP, local only) |
| `QL_NAME` | `ql-lg` | Docker container name |

Game modes (`QL_FACTORY`):

| Mode | |
|---|---|
| `lgvamp` | the default: 200 HP, vampire up to 200, antilag up to 240 ms ping |
| `lgvamp_nolag` | the same without antilag: you lead your shots by your ping |
| `lgvamp100` | 100 HP and vampire up to 100, so health never drops on its own |

The modes are defined in [`home/baseq3/scripts/lgvamp.factories`](home/baseq3/scripts/lgvamp.factories).

## When something goes wrong

- **Setup says a port is in use:** another program (or another copy of this server) uses it. Set a different `QL_PORT` / `QL_RCON_PORT` in `.env` and run `./setup.sh` again.
- **`permission denied` from Docker:** your user is not in the `docker` group yet, or you haven't logged out and back in since adding it.
- **Friends can't connect but you can:** the port forward is missing or points to the wrong machine, or a firewall on the machine blocks UDP 27960 (`sudo ufw allow 27960/udp` on Ubuntu).
- **The server doesn't come up:** `docker logs --tail 50 ql-lg` shows why. Treat logs as private.
- **After a game update the server won't start:** run `./setup.sh` again. It keeps your settings and restores the minqlx files.

Admins, bans, the training bot's settings, backups and running several servers: [docs/ADMIN.md](docs/ADMIN.md). Why each setting is the way it is: [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md).

## Credits

- [minqlx](https://github.com/MinoMino/minqlx) (GPL-3.0) by MinoMino. setup.sh builds it from source; it is not included here.
- [x76.gg](https://x76.gg/) for the LG duel server format.
- [SEA LG Duels server](https://github.com/minhlong124/quake-lg-sea-server), the preset this started from.
- Quake Live is © id Software / Bethesda. The game server is downloaded from Steam (app 349090); no game files are in this repo.

License: MIT, for this repo's configs and scripts.