qlsm/index.html at main · dngrtech/qlsm · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="google-site-verification" content="NFu06dI8GzHPgkErow16hR9EHWx83jfSnoyx5r5VTtk">
<title>QLSM — Quake Live Server Management</title>
<meta name="description" content="QLSM — Quake Live Server Management. Web UI for managing Quake Live dedicated servers with self-deployment, standalone remote servers, and VULTR provisioning.">
<style>
  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 800px; margin: 40px auto; padding: 0 20px; color: #24292e; line-height: 1.6; }
  h1 { font-size: 2em; border-bottom: 1px solid #eaecef; padding-bottom: 0.3em; }
  h2 { font-size: 1.5em; margin-top: 1.5em; border-bottom: 1px solid #eaecef; padding-bottom: 0.3em; }
  pre { background: #f6f8fa; padding: 16px; border-radius: 6px; overflow-x: auto; }
  code { background: #f6f8fa; padding: 2px 5px; border-radius: 3px; font-family: monospace; }
  pre code { background: none; padding: 0; }
  a { color: #0366d6; }
  ul { padding-left: 1.5em; }
  li { margin: 0.35em 0; }
  img { max-width: 100%; height: auto; border-radius: 8px; border: 1px solid #eaecef; margin: 16px 0; }
  .github-link { display: inline-block; margin: 10px 0 20px; padding: 8px 16px; background: #24292e; color: #fff; border-radius: 6px; text-decoration: none; font-weight: bold; }
  .github-link:hover { background: #444; color: #fff; }
</style>
</head>
<body>

<h1>QLSM — Quake Live Server Management</h1>

<a class="github-link" href="https://github.com/dngrtech/qlsm">View on GitHub</a>

<h2>Features</h2>

<ul>
  <li>Three deployment modes (Debian 12 and Ubuntu 22 are tested and recommended):
    <ul>
      <li>QLSM self-deployment: run QLDS instances on the same machine as QLSM</li>
      <li>Standalone remote server</li>
      <li>VULTR cloud provisioning via Terraform</li>
    </ul>
  </li>
  <li>Optional 99k LAN rate mode. Only Debian 12 supports this feature</li>
  <li>Optional <code>QLFilter</code> deployment for supported hosts (anti-DDOS protection)</li>
  <li>Per-instance RCON console with command line and live feed of all server events</li>
  <li>Live server status with current map, gametype, mode/factory, match timer, player list, and scores</li>
  <li>Syntax-aware editors (CodeMirror) for <code>server.cfg</code>, <code>mappool.txt</code>, <code>access.txt</code>, and <code>workshop.txt</code>, featuring a Python linter for minqlx plugin's code validation. The editor includes search and replace functionality for easy editing</li>
  <li>Upload common config files, factories, custom minqlx plugins, or <code>*.so</code> binary files</li>
  <li>Preset manager to load/save/update/delete qlds presets. Each preset includes custom <code>server.cfg</code>, <code>access.cfg</code>, <code>mappool.cfg</code>, <code>workshop.txt</code>, set of minqlx-plugins and <code>*.factories</code> files
    <ul>
      <li>Minqlx plugins can be enabled in the UI by selecting checkboxes. This eliminates the need to manually edit the <code>qlx_plugins</code> cvar, as QLSM handles it automatically.</li>
      <li>UI-driven Factory Management: Enable factories directly via checkboxes</li>
    </ul>
  </li>
  <li>Chat logs (including rotated archived chat log files) and server logs retrieval with convenient search capability.</li>
  <li>Daily/weekly/monthly host auto-restart scheduling; scheduled restarts trigger workshop refresh across deployed instances</li>
  <li>Manual workshop item update by Steam Workshop ID, with optional restart of selected instances</li>
  <li>ZMQ RCON Port, ZMQ RCON Password, ZMQ Stats Port, ZMQ Stats Password - all these cvars are auto-generated and shown in the UI</li>
  <li>User management: create users, delete users, and reset passwords</li>
  <li>External API key management for service-to-service access</li>
  <li>External REST API for authenticated instance inventory lookups</li>
  <li>Per-user host/instance ordering and expanded-state preferences stored in browser local storage</li>
</ul>

<p>Everything runs over SSH via Ansible.</p>

<img width="1428" height="993" alt="servers_page" src="https://github.com/user-attachments/assets/11894a0e-19df-492e-8da7-d69b5ff01d8a">

<img width="1258" height="1218" alt="edit_config" src="https://github.com/user-attachments/assets/23cbf0dd-b291-46af-941b-74ad802c746b">

<h2>Stack</h2>

<p>Flask + React + SQLite + Redis + Ansible. Background jobs run through RQ workers. The frontend is a Vite/Tailwind SPA served behind Caddy.</p>

<h2>Requirements</h2>

<p>Ubuntu 22.04 recommended:</p>
<ul>
  <li><strong>Docker</strong> — <a href="https://docs.docker.com/engine/install/ubuntu/">install guide</a></li>
  <li><strong>Docker Compose</strong> (usually included with Docker)</li>
  <li>A user with <code>sudo</code> access</li>
</ul>

<p>Redis, Caddy, the app itself run inside Docker.</p>

<p>To install Docker on a fresh Ubuntu server:</p>
<pre><code>curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker</code></pre>

<h2>Quick start</h2>

<h3>Option 1 — one-liner</h3>
<pre><code>curl -fsSL https://raw.githubusercontent.com/dngrtech/qlsm/main/qlsm-install.sh | bash</code></pre>

<p>With a custom domain (enables HTTPS via Caddy):</p>
<pre><code>SITE_ADDRESS=qlds.example.com bash &lt;(curl -fsSL https://raw.githubusercontent.com/dngrtech/qlsm/main/qlsm-install.sh)</code></pre>

<h3>Option 2 — git clone</h3>
<pre><code>git clone https://github.com/dngrtech/qlsm.git &amp;&amp; cd qlsm
cp .env.example .env
# edit .env: set SITE_ADDRESS, REDIS_PASSWORD, and VULTR_API_KEY if using Vultr
docker compose up -d</code></pre>

<p>Default login is <code>admin</code> / <code>admin</code>. You'll be forced to change the password on first login.</p>

<h2>Updating</h2>
<pre><code>curl -fsSL https://raw.githubusercontent.com/dngrtech/qlsm/main/qlsm-install.sh | bash -s -- --update</code></pre>

<p>Downloads the latest <code>docker-compose.yml</code>, pulls the new image, and restarts. Your <code>.env</code> and data are untouched.</p>

<p>Full setup guide: <a href="https://github.com/dngrtech/qlsm/blob/main/docs/setup.md">docs/setup.md</a></p>

<h2>Development</h2>
<pre><code>cp .env.example .env
./run-dev.sh</code></pre>

<p>That starts Flask, Vite, an RQ worker, the RCON service, and a status poller together. Flask ends up on <code>:5001</code>, frontend on <code>:5173</code>.</p>

<p>Redis needs to be running locally for dev (it's included automatically in the Docker stack for production):</p>
<pre><code># Ubuntu/Debian
sudo apt install redis-server && sudo systemctl enable --now redis</code></pre>

<pre><code>pytest tests/</code></pre>

<h2>Docs</h2>
<ul>
  <li><a href="https://github.com/dngrtech/qlsm/blob/main/docs/setup.md">docs/setup.md</a> — install and configure</li>
  <li><a href="https://github.com/dngrtech/qlsm/blob/main/docs/architecture.md">docs/architecture.md</a> — how it fits together</li>
  <li><a href="https://github.com/dngrtech/qlsm/blob/main/docs/technical.md">docs/technical.md</a> — implementation details</li>
</ul>

<h2>Acknowledgements</h2>

<p>Huge thanks to <strong>Doomsday</strong> — his deep knowledge of Quake Live dedicated server administration has directly shaped a large portion of QLSM's features. Years of running servers for the NA <a href="https://www.thunderdomequake.com">Thunderdome</a> community gave him insights that no documentation could replace. He also maintains an excellent collection of <a href="https://github.com/D00MSDAYDEVICE/minqlx">minqlx plugins</a> worth checking out.</p>

<p>Kudos to <strong>mb</strong> for his help configuring and troubleshooting the 99k LAN rate feature.</p>

<h2>License</h2>
<p>GPL-3.0</p>

</body>
</html>