@andrian.yablonskyy/thub-coordinator 1.1.14 → 1.1.16

package/README.md

@@ -50,6 +50,12 @@ The Coordinator loads a plain **JSON** config file (no YAML support). Resolution
 
 `sessionSecret` signs the dashboard's session cookie and the HMAC on artifact download links; `clientJoinKey` is the shared secret Clients self-register with — omit or leave `null` to disable auto-registration entirely. `trustProxy` is Express's [`trust proxy`](https://expressjs.com/en/guide/behind-proxies.html) setting (default `loopback`): which reverse proxies' `X-Forwarded-For` to believe for a Client's external address on the resource card — e.g. `"10.0.0.0/8"` or `1` for a proxy on another host, `false` to always use the socket address. Individual `THUB_LISTEN` / `THUB_PUBLIC_URL` / `THUB_DATA_DIR` / `THUB_SESSION_SECRET` / `THUB_CLIENT_JOIN_KEY` env vars override whatever the file set.
 
+**Kubernetes:** a Dockerfile, manifests (one replica, a volume for SQLite, ingress with SSE-friendly settings) and the upgrade, backup and HTTPS notes are in the main README, §13.3, and on the dashboard's Help page (*Running in Kubernetes*). The image starts without `--self-update`: update by deploying a new image.
+
+**Database file:** `dbPath` (or `THUB_DB_PATH`). The default is `<dataDir>/thub.db`; a relative path is taken from `dataDir`. Its directory must be writable, because SQLite keeps `-wal`/`-shm` files next to it. Details: main README §13.
+
+**HTTPS without a reverse proxy:** set `tls.certFile` / `tls.keyFile` (PEM, readable by the service user; optional `tls.caFile`, `tls.passphrase`), or `THUB_TLS_CERT` / `THUB_TLS_KEY` / `THUB_TLS_CA` / `THUB_TLS_PASSPHRASE`, and an `https://` `publicUrl`. The Coordinator then serves HTTPS itself. Bad files stop the start with the reason, and renewed files are picked up within a minute or on `SIGHUP`. For a self-signed or private CA, start Clients and Agents with `NODE_EXTRA_CA_CERTS`. Details: main README §13.
+
 `npm install -g` creates `~/.config/thub/coordinator.json` for you if it doesn't already exist, with all the options above, `dataDir` set to `~/var/lib/thub` and a freshly generated random `sessionSecret` (not the placeholder above), readable only by its owner — a re-install never overwrites it or regenerates the secret. Set `publicUrl` and `clientJoinKey` yourself before relying on auto-registration.
 
 ## Running it
@@ -79,9 +85,9 @@ Talks to the Coordinator's SQLite database directly — no running server requir
 # THUB_BOOTSTRAP_ADMIN_PASSWORD above).
 thub-admin create-admin alice s3cret --role admin
 
-# Register a CI or developer identity — the only credential still issued
-# by an admin; the token is shown once.
-thub-admin agent add ci-firmware --kind ci
+# A CI token for a pipeline (people get their key with: thub-admin user key);
+# the token is shown once.
+thub-admin agent add ci-firmware
 # -> Agent agt_... created. Token (shown once): agt_...
 
 # Mint the shared secret Clients use to self-register, and put it in both
@@ -102,7 +108,7 @@ thub-admin group add ci-nightly --comment "shared CI pool"
 thub-admin group list
 thub-admin group remove <groupId>
 
-# Update the Coordinator by hand (the dashboard's "Update app" button does the same through a root helper).
+# Update the Coordinator by hand (with --self-update, the dashboard's "Update app" button does the same through a root helper).
 thub-admin check-update                  # installed vs latest published version
 thub-admin self-update [--to <x.y.z>]    # sudo npm i -g; the postinstall restarts the service
 ```
@@ -150,7 +156,7 @@ Server-rendered Pug templates styled with Bootstrap 5.3, with a little vanilla J
 | Page | Content |
 |---|---|
 | `/` | Runner cards by status, queue length, jobs in the last 24 h. Click a card for its runner card (below). |
-| `/runners` | **Runners** (formerly Resources; `/resources` redirects): Type, Client version, labels, groups, status, busy source/reason, last heartbeat age; admin maintenance/rotate-token actions. Click a row for its resource card (below). |
+| `/runners` | **Runners** (formerly Resources; `/resources` redirects): Type, Client version, labels, groups, status (with the last heartbeat under it), busy source/reason; admin maintenance/rotate-token actions. Click a row for its resource card (below). |
 | `/groups` | Resource groups — id/name/comment, member count; admin create/rename/delete. Membership itself is set per-resource in the Client's own config. |
 | `/jobs` | Filterable job list (state, source, resource), with the job's `user` label if set; admin **Reset queue** / **Clean history**. |
 | `/jobs/:id` | Spec, timeline, live log viewer with stream filter, artifact downloads, cancel button. |
@@ -166,7 +172,7 @@ The Coordinator's own version (`ver. X.Y.Z`) is shown under the TestHub logo, to
 **Versions and self-update.** The Coordinator checks the npm registry for the latest Coordinator, Agent and Client every `updates.checkIntervalMin` (default 15 minutes, `0` disables; the older `checkIntervalHours` is ignored; `updates.registry` for a private mirror) and immediately with the navbar's **check for updates** button (admins; also on the Agents and Resources pages), which reports in a toast whether the Coordinator is current and which connected resources can update their Client. A newer Coordinator shows as an **Update app to X.Y.Z** button in the navbar for admins (a badge under the logo for viewers); Agents and Resources show each one's version with an **update available** or pending **→ vX.Y.Z** badge. Admins request self-updates per agent/resource (**Update**, which becomes **Cancel update**) or with **Update all agents** / **Update all clients**, always to the latest version:
 - Clients get a `self-update` command on their next heartbeat and install it through their root `thub-client-update` helper, once none of the host's instances is busy.
 - Agents install it at the start of their next run (`GET /api/v1/agents/me/update`), then re-run the command on the new version.
-- The Coordinator itself: the **Update app** button writes `<dataDir>/update-request.json`; the root `thub-coordinator-update.path` unit (installed by `sudo npm i -g`) runs `npm i -g` for it, and the postinstall restarts the service (the dashboard and API are briefly down). Logs: `journalctl -u thub-coordinator-update`. Without that unit, use `thub-admin self-update` on the host.
+- The Coordinator itself, only when started with `--self-update` (off by default; under systemd add it to the unit's `ExecStart`, a re-install keeps it): the **Update app** button writes `<dataDir>/update-request.json`; the root `thub-coordinator-update.path` unit (installed by `sudo npm i -g`) runs `npm i -g` for it, and the postinstall restarts the service (the dashboard and API are briefly down). Logs: `journalctl -u thub-coordinator-update`. Without that unit, use `thub-admin self-update` on the host.
 
 A request is cleared when the Agent/Client reports the new version.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {

package/public/css/thub.css

@@ -457,3 +457,20 @@ fieldset:disabled .thub-tags-box {
     white-space: nowrap;
   }
 }
+
+/* A second, smaller line in a table cell: the version under a name (Runners,
+   CI tokens), the last heartbeat under a status (Runners). */
+.thub-subline {
+  font-size: 0.7rem;
+  margin-top: 0.125rem;
+}
+
+.thub-subline .badge {
+  font-size: 0.65rem;
+}
+
+.thub-subline .btn {
+  --bs-btn-padding-y: 0;
+  --bs-btn-padding-x: 0.3rem;
+  --bs-btn-font-size: 0.7rem;
+}

package/scripts/install-default-config.js

@@ -81,7 +81,9 @@ function main(){
     paths = targetPaths(user);
   try {
     mkdirOwned(paths.configDir, user);
-    for (const dir of [paths.dataDir, ...paths.dataSubdirs]){
+    // The database's own directory too, when dbPath puts it elsewhere: the
+    // systemd unit's ReadWritePaths needs it to exist.
+    for (const dir of [paths.dataDir, ...paths.dataSubdirs, ...(paths.dbDir ? [paths.dbDir] : [])]){
       mkdirOwned(dir, user);
     }
     if (!fs.existsSync(paths.configPath)){

package/scripts/install-systemd-unit.js

@@ -34,13 +34,24 @@ const fs = require('node:fs'),
 // The checked-in unit only has placeholders — fill in the target user and
 // wherever *this* install's node and server.js actually are, so it works
 // regardless of npm prefix or an nvm-managed Node.
+// `--self-update` (README §10.2) is off by default; once added to the
+// installed unit's ExecStart, a re-install keeps it there.
+function selfUpdateFlag(existingUnit = UNIT_DEST){
+  try {
+    return /^ExecStart=.*\s--self-update(\s|$)/m.test(fs.readFileSync(existingUnit, 'utf8')) ? ' --self-update' : '';
+  }
+  catch {
+    return '';
+  }
+}
+
 function renderUnit(user, paths){
   return fs.readFileSync(UNIT_SRC, 'utf8')
     .replace(/^User=.*$/m, `User=${user.name}`)
     .replace(/^Group=.*$/m, `Group=${user.gid}`)
     .replace(/^Environment=THUB_COORDINATOR_CONFIG=.*$/m, `Environment=THUB_COORDINATOR_CONFIG=${paths.configPath}`)
-    .replace(/^ExecStart=.*$/m, `ExecStart=${process.execPath} ${SERVER_PATH}`)
-    .replace(/^ReadWritePaths=.*$/m, `ReadWritePaths=${paths.dataDir}`);
+    .replace(/^ExecStart=.*$/m, `ExecStart=${process.execPath} ${SERVER_PATH}${selfUpdateFlag()}`)
+    .replace(/^ReadWritePaths=.*$/m, `ReadWritePaths=${[paths.dataDir, paths.dbDir].filter(Boolean).join(' ')}`);
 }
 
 function renderUpdateUnits(user, paths){

package/scripts/install-target.js

@@ -66,6 +66,9 @@ function targetPaths(user){
     configPath,
     defaultDataDir,
     dataDir,
+    // The database's directory, when the config's dbPath puts it outside
+    // dataDir: the systemd unit must allow writes there too.
+    dbDir: configuredDbDir(configPath, dataDir),
     // Written by the dashboard's "Update app" button, watched by
     // thub-coordinator-update.path (README §10.2).
     updateRequestFile: path.join(dataDir, 'update-request.json'),
@@ -73,6 +76,21 @@ function targetPaths(user){
   };
 }
 
+function configuredDbDir(configPath, dataDir){
+  try {
+    const dbPath = JSON.parse(fs.readFileSync(configPath, 'utf8'))?.dbPath;
+    if (typeof dbPath !== 'string' || !dbPath.trim()){
+      return null;
+    }
+    const dir = path.dirname(path.resolve(dataDir, dbPath)),
+      inside = path.relative(dataDir, dir);
+    return inside === '' || (!inside.startsWith('..') && !path.isAbsolute(inside)) ? null : dir;
+  }
+  catch {
+    return null;
+  }
+}
+
 function configuredDataDir(configPath){
   try {
     const dataDir = JSON.parse(fs.readFileSync(configPath, 'utf8'))?.dataDir;

package/src/config.js

@@ -27,6 +27,10 @@ const DEFAULTS = {
   // default setup — listening on 127.0.0.1 behind a local reverse proxy.
   trustProxy: 'loopback',
   dataDir: path.join(process.cwd(), '.data'),
+  // The SQLite database file. null = <dataDir>/thub.db; a relative path is
+  // taken from dataDir. Its directory must be writable: SQLite keeps its
+  // -wal/-shm files next to it.
+  dbPath: null,
   sessionSecret: 'dev-only-change-me',
   session: {
     // The dashboard session cookie's Secure flag (server.js cookieSecure):
@@ -34,6 +38,16 @@ const DEFAULTS = {
     // Secure only on a connection that is itself HTTPS); true / false force it.
     secureCookie: 'auto'
   },
+  // HTTPS served by the Coordinator itself (tls.js): PEM files, readable by
+  // its user. No certFile/keyFile = plain HTTP, e.g. behind a reverse proxy
+  // that terminates TLS. caFile: intermediate certificates, if not already
+  // in certFile; passphrase: for an encrypted key.
+  tls: {
+    certFile: null,
+    keyFile: null,
+    caFile: null,
+    passphrase: null
+  },
   // Shared secret Clients present to self-register (see api/resource.js).
   // null disables auto-registration entirely — set it explicitly to turn it on.
   clientJoinKey: null,
@@ -127,12 +141,20 @@ function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
   if (process.env.THUB_DATA_DIR){
     config.dataDir = process.env.THUB_DATA_DIR;
   }
+  if (process.env.THUB_DB_PATH){
+    config.dbPath = process.env.THUB_DB_PATH;
+  }
   if (process.env.THUB_SESSION_SECRET){
     config.sessionSecret = process.env.THUB_SESSION_SECRET;
   }
   if (process.env.THUB_CLIENT_JOIN_KEY){
     config.clientJoinKey = process.env.THUB_CLIENT_JOIN_KEY;
   }
+  for (const [env, key]of [['THUB_TLS_CERT', 'certFile'], ['THUB_TLS_KEY', 'keyFile'], ['THUB_TLS_CA', 'caFile'], ['THUB_TLS_PASSPHRASE', 'passphrase']]){
+    if (process.env[env]){
+      config.tls[key] = process.env[env];
+    }
+  }
 
   for (const key of ['requestsPerMinute', 'loginPerMinute']){
     const v = config.rateLimit[key];
@@ -160,20 +182,24 @@ function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
   const [host, port] = config.listen.split(':');
   config.host = host;
   config.port = Number(port);
-  config.dbPath = path.join(config.dataDir, 'thub.db');
+  if (config.dbPath !== null && (typeof config.dbPath !== 'string' || !config.dbPath.trim())){
+    throw new Error(`dbPath must be a file path, or null for <dataDir>/thub.db (got ${JSON.stringify(config.dbPath)}) in ${candidate || 'the config'}`);
+  }
+  config.dbPath = config.dbPath ? path.resolve(config.dataDir, config.dbPath) : path.join(config.dataDir, 'thub.db');
   config.workDir = path.join(config.dataDir, 'work');
   config.avatarsDir = path.join(config.dataDir, 'avatars');
 
   ensureWritableDir(config.dataDir, config.configPath);
   ensureWritableDir(config.avatarsDir, config.configPath);
+  ensureWritableDir(path.dirname(config.dbPath), config.configPath, 'dbPath / THUB_DB_PATH');
 
   return config;
 }
 
-// SQLite opens thub.db (plus its -wal/-shm files) inside dataDir, so an
+// SQLite opens thub.db (plus its -wal/-shm files) in its directory, so an
 // existing but unwritable dataDir — typically one created by an earlier
 // run under sudo — would otherwise fail later as a bare SQLITE_CANTOPEN.
-function ensureWritableDir(dir, configPath){
+function ensureWritableDir(dir, configPath, setting = 'dataDir / THUB_DATA_DIR'){
   try {
     fs.mkdirSync(dir, { recursive: true });
     fs.accessSync(dir, fs.constants.W_OK);
@@ -181,7 +207,7 @@ function ensureWritableDir(dir, configPath){
   catch (err){
     throw new Error(
       `Coordinator data directory ${dir} is not writable by this user (${err.code || err.message}). ` +
-        `Fix its ownership, or set dataDir in ${configPath || 'the config'} / THUB_DATA_DIR to a writable path.`
+        `Fix its ownership, or set ${setting} (in ${configPath || 'the config'}) to a writable path.`
     );
   }
 }

package/src/server.js

@@ -21,6 +21,7 @@ const fs = require('node:fs'),
   session = require('express-session'),
 
   { loadConfig } = require('./config'),
+  { createServer, readTlsOptions } = require('./tls'),
   { openDb } = require('./db'),
   { bus } = require('./services/bus'),
   { createEventsService } = require('./services/events'),
@@ -209,9 +210,16 @@ function createApp(config, services){
   return app;
 }
 
-function start(configPath){
-  const config = loadConfig(configPath),
-    services = buildServices(config),
+// `node server.js [--self-update]`. --self-update turns on the dashboard's
+// "Update app" (an admin installs a newer Coordinator through the root
+// thub-coordinator-update helper, README §10.2). Off by default — e.g. in a
+// container, where a new image is the update.
+function start(configPath, argv = process.argv.slice(2)){
+  const config = loadConfig(configPath);
+  config.selfUpdate = argv.includes('--self-update');
+  // Certificate problems stop the Coordinator before anything else starts.
+  readTlsOptions(config.tls, config.configPath || 'the config');
+  const services = buildServices(config),
     app = createApp(config, services);
 
   ensureBootstrapAdmin(services);
@@ -219,10 +227,15 @@ function start(configPath){
   // Clients and jobs to work on the dashboard with (src/dev/virtual.js).
   services.dev = startDevMode(services, config);
 
-  const server = app.listen(config.port, config.host, () => {
-    console.log(`Config: ${config.configPath || '(built-in defaults)'}; data: ${config.dataDir}`);
-    console.log(`TestHub Coordinator listening on http://${config.host}:${config.port}`);
+  const { server, scheme } = createServer(app, config);
+  server.listen(config.port, config.host, () => {
+    console.log(`Config: ${config.configPath || '(built-in defaults)'}; data: ${config.dataDir}; database: ${config.dbPath}`);
+    console.log(`TestHub Coordinator listening on ${scheme}://${config.host}:${config.port}`);
+    if (scheme === 'https' && !/^https:/.test(config.publicUrl)){
+      console.warn(`tls: serving HTTPS, but publicUrl is ${config.publicUrl} — set it to the https:// address Clients and Agents use`);
+    }
     console.log(`Coordinator v${require('../package.json').version}, thub-common v${commonVersion()} (${commonPath()})`);
+    console.log(config.selfUpdate ? 'Self-update: on (--self-update)' : 'Self-update: off (start with --self-update to update from the dashboard)');
   });
 
   return { app, server, services, config };

package/src/services/updates.js

@@ -120,6 +120,8 @@ function createUpdatesService({ config, pathUnit = UPDATE_PATH_UNIT, fetchLatest
     return {
       ...state,
       coordinatorVersion,
+      // The dashboard's "Update app": only with `--self-update` (server.js).
+      selfUpdate: Boolean(config.selfUpdate),
       coordinatorUpdate: isNewer(state.latest.coordinator, coordinatorVersion) ? state.latest.coordinator : null
     };
   }
@@ -128,6 +130,10 @@ function createUpdatesService({ config, pathUnit = UPDATE_PATH_UNIT, fetchLatest
   // thub-coordinator-update helper, whose install restarts this process
   // (so `coordinatorPending` only lasts until then).
   function requestCoordinatorUpdate(requestedBy){
+    if (!config.selfUpdate){
+      throw Object.assign(new Error('Self-update is off: start the Coordinator with --self-update to update it from the dashboard ' +
+        '(README §10.2), or update it by hand — thub-admin self-update, or a new container image'), { status: 403 });
+    }
     const target = status().coordinatorUpdate;
     if (!target){
       throw Object.assign(new Error(`Already on the latest version (v${coordinatorVersion}).`), { status: 409 });

package/src/tls.js

@@ -0,0 +1,96 @@
+/**
+ * @file        packages/coordinator/src/tls.js
+ * @description HTTPS for the Coordinator itself: certificate files from the config, checked at start, reloaded when renewed (README §13)
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const fs = require('node:fs'),
+  http = require('node:http'),
+  https = require('node:https'),
+  tls = require('node:tls');
+
+// How often renewed certificate files are looked for (Let's Encrypt,
+// cert-manager rotate them in place). SIGHUP reloads at once.
+const WATCH_INTERVAL_MS = 60_000;
+
+// The `tls` config section as Node TLS options — or null for plain HTTP
+// (no certFile/keyFile). Throws with a readable reason if the files can't be
+// read or don't make a usable certificate/key pair, so a mistake stops the
+// Coordinator at start instead of failing every connection later.
+function readTlsOptions(cfg, where = 'the config'){
+  if (!cfg || (!cfg.certFile && !cfg.keyFile)){
+    return null;
+  }
+  if (!cfg.certFile || !cfg.keyFile){
+    throw new Error(`tls: set both certFile and keyFile (or neither, for plain HTTP) in ${where}`);
+  }
+  const read = (key) => {
+      try {
+        return fs.readFileSync(cfg[key]);
+      }
+      catch (err){
+        throw new Error(`tls.${key} ${cfg[key]} can't be read by this user (${err.code || err.message}) — check the path and its permissions`);
+      }
+    },
+    options = {
+      cert: read('certFile'),
+      key: read('keyFile'),
+      ...(cfg.caFile ? { ca: read('caFile') } : {}),
+      ...(cfg.passphrase ? { passphrase: cfg.passphrase } : {})
+    };
+  try {
+    tls.createSecureContext(options); // a cert that doesn't match its key, a wrong passphrase…
+  }
+  catch (err){
+    throw new Error(`tls: ${cfg.certFile} / ${cfg.keyFile} aren't a usable certificate and key: ${err.message}`);
+  }
+  return options;
+}
+
+// The Coordinator's server: HTTPS with the configured certificate, else
+// plain HTTP (behind a TLS-terminating proxy, as before). With HTTPS, a
+// renewed certificate is picked up without a restart: its files are checked
+// every minute, and on SIGHUP.
+function createServer(app, config, { log = console } = {}){
+  const options = readTlsOptions(config.tls);
+  if (!options){
+    return { server: http.createServer(app), scheme: 'http' };
+  }
+  const server = https.createServer(options, app),
+    files = [config.tls.certFile, config.tls.keyFile, config.tls.caFile].filter(Boolean),
+    reload = (why) => {
+      try {
+        server.setSecureContext(readTlsOptions(config.tls));
+        log.log(`tls: certificate reloaded (${why})`);
+      }
+      catch (err){
+        log.error(`tls: keeping the current certificate — ${err.message}`);
+      }
+    },
+    onChange = (cur, prev) => {
+      if (cur.mtimeMs !== prev.mtimeMs){
+        reload('file changed');
+      }
+    },
+    onHup = () => reload('SIGHUP');
+  for (const f of files){
+    fs.watchFile(f, { interval: WATCH_INTERVAL_MS, persistent: false }, onChange);
+  }
+  process.on('SIGHUP', onHup);
+  server.on('close', () => {
+    files.forEach((f) => fs.unwatchFile(f, onChange));
+    process.off('SIGHUP', onHup);
+  });
+  return { server, scheme: 'https' };
+}
+
+module.exports = { readTlsOptions, createServer };

package/systemd/thub-coordinator.service

@@ -3,6 +3,8 @@ Description=TestHub Coordinator
 After=network-online.target
 Wants=network-online.target
 
+# Add --self-update to ExecStart to let admins update the Coordinator from
+# the dashboard ("Update app", README §10.2); a re-install keeps it.
 # User, Group, THUB_COORDINATOR_CONFIG, ReadWritePaths and ExecStart are
 # rewritten by scripts/install-systemd-unit.js at install time to the user
 # who ran `sudo npm i -g` and this install's real node/server.js paths.

package/test/config.test.js

@@ -0,0 +1,76 @@
+/**
+ * @file        packages/coordinator/test/config.test.js
+ * @description Tests: the Coordinator config — database file location
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const test = require('node:test'),
+  assert = require('node:assert/strict'),
+  fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path'),
+  { loadConfig } = require('../src/config'),
+  { buildServices } = require('../src/server');
+
+function withConfig(content){
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-cfg-')),
+    file = path.join(dir, 'coordinator.json');
+  fs.writeFileSync(file, JSON.stringify({ dataDir: path.join(dir, 'data'), updates: { checkIntervalMin: 0 }, ...content }));
+  return { dir, file };
+}
+
+test('dbPath: <dataDir>/thub.db by default; absolute, relative to dataDir, or THUB_DB_PATH; the database is opened there', () => {
+  const plain = withConfig({});
+  assert.equal(loadConfig(plain.file).dbPath, path.join(plain.dir, 'data', 'thub.db'));
+
+  const rel = withConfig({ dbPath: 'db/testhub.sqlite' });
+  assert.equal(loadConfig(rel.file).dbPath, path.join(rel.dir, 'data', 'db', 'testhub.sqlite'));
+
+  const abs = withConfig({}),
+    elsewhere = path.join(abs.dir, 'fast-disk', 'thub.db');
+  fs.writeFileSync(abs.file, JSON.stringify({ dataDir: path.join(abs.dir, 'data'), dbPath: elsewhere, updates: { checkIntervalMin: 0 } }));
+  const config = loadConfig(abs.file);
+  assert.equal(config.dbPath, elsewhere);
+  buildServices(config).db.close();
+  assert.ok(fs.existsSync(elsewhere), 'the database file is created at dbPath');
+  assert.ok(!fs.existsSync(path.join(abs.dir, 'data', 'thub.db')));
+
+  const env = withConfig({ dbPath: 'from-file.db' }),
+    saved = process.env.THUB_DB_PATH;
+  process.env.THUB_DB_PATH = path.join(env.dir, 'from-env.db');
+  try {
+    assert.equal(loadConfig(env.file).dbPath, path.join(env.dir, 'from-env.db'));
+  }
+  finally {
+    if (saved === undefined){
+      delete process.env.THUB_DB_PATH;
+    }
+    else {
+      process.env.THUB_DB_PATH = saved;
+    }
+  }
+
+  assert.throws(() => loadConfig(withConfig({ dbPath: 42 }).file), /dbPath must be a file path, or null/);
+});
+
+test('dbPath in a directory this user can\'t write: stops the start, naming the setting', { skip: process.getuid?.() === 0 }, () => {
+  const { dir, file } = withConfig({}),
+    locked = path.join(dir, 'locked');
+  fs.mkdirSync(locked, { mode: 0o500 });
+  fs.writeFileSync(file, JSON.stringify({ dataDir: path.join(dir, 'data'), dbPath: path.join(locked, 'thub.db') }));
+  try {
+    assert.throws(() => loadConfig(file), /locked is not writable by this user .*set dbPath \/ THUB_DB_PATH/);
+  }
+  finally {
+    fs.chmodSync(locked, 0o700);
+  }
+});

package/test/tls.test.js

@@ -0,0 +1,141 @@
+/**
+ * @file        packages/coordinator/test/tls.test.js
+ * @description Tests: HTTPS served by the Coordinator itself — certificate checks, serving, renewal
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const test = require('node:test'),
+  assert = require('node:assert/strict'),
+  fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path'),
+  https = require('node:https'),
+  { spawnSync } = require('node:child_process'),
+  { loadConfig } = require('../src/config'),
+  { buildServices, createApp } = require('../src/server'),
+  { readTlsOptions, createServer } = require('../src/tls');
+
+const hasOpenssl = spawnSync('openssl', ['version']).status === 0;
+
+// A self-signed certificate for 127.0.0.1 into `dir`, as <name>.crt / <name>.key.
+function makeCert(dir, name){
+  const crt = path.join(dir, `${name}.crt`),
+    key = path.join(dir, `${name}.key`),
+    r = spawnSync('openssl', ['req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-days', '2', '-subj', `/CN=${name}`,
+      '-keyout', key, '-out', crt], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  return { crt, key };
+}
+
+// GET over HTTPS, trusting only `ca`; resolves { status, headers, subject }.
+function get(port, urlPath, ca, headers = {}){
+  return new Promise((resolve, reject) => {
+    const req = https.request({ host: '127.0.0.1', port, path: urlPath, ca, headers, checkServerIdentity: () => undefined }, (res) => {
+      const subject = res.socket.getPeerCertificate().subject.CN;
+      res.resume();
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, subject }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+test('tls config: none = plain HTTP; half a pair, an unreadable file or a mismatched key stop the start, saying why', { skip: !hasOpenssl }, () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-tls-')),
+    a = makeCert(dir, 'a'),
+    b = makeCert(dir, 'b');
+  assert.equal(readTlsOptions({}), null);
+  assert.equal(readTlsOptions({ certFile: null, keyFile: null }), null);
+  assert.throws(() => readTlsOptions({ certFile: a.crt }), /set both certFile and keyFile/);
+  assert.throws(() => readTlsOptions({ certFile: a.crt, keyFile: path.join(dir, 'missing.key') }),
+    /tls.keyFile .*missing.key can't be read by this user \(ENOENT\)/);
+  assert.throws(() => readTlsOptions({ certFile: a.crt, keyFile: b.key }), /aren't a usable certificate and key/);
+  assert.ok(readTlsOptions({ certFile: a.crt, keyFile: a.key }).cert);
+});
+
+test('HTTPS: the dashboard and API over TLS, a Secure session cookie, a renewed certificate picked up on SIGHUP', { skip: !hasOpenssl }, async (t) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-tls-')),
+    first = makeCert(dir, 'first'),
+    renewed = makeCert(dir, 'renewed'),
+    live = { crt: path.join(dir, 'live.crt'), key: path.join(dir, 'live.key') },
+    file = path.join(dir, 'coordinator.json');
+  fs.copyFileSync(first.crt, live.crt);
+  fs.copyFileSync(first.key, live.key);
+  fs.writeFileSync(file, JSON.stringify({
+    dataDir: path.join(dir, 'data'), updates: { checkIntervalMin: 0 }, publicUrl: 'https://thub.example.com',
+    tls: { certFile: live.crt, keyFile: live.key }
+  }));
+  const config = loadConfig(file),
+    services = buildServices(config),
+    logs = [],
+    { server, scheme } = createServer(createApp(config, services), config, { log: { log: (m) => logs.push(m), error: (m) => logs.push(m) } });
+  assert.equal(scheme, 'https');
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  t.after(() => new Promise((r) => {
+    server.closeAllConnections?.();
+    server.close(r);
+  }));
+  const port = server.address().port,
+    login = await get(port, '/login', fs.readFileSync(first.crt));
+  assert.equal(login.status, 200);
+  assert.equal(login.subject, 'first');
+
+  services.adminUsers.create({ username: 'root', email: 'r@example.com', role: 'admin', password: 'pw' }, { by: 't' });
+  const signIn = await new Promise((resolve, reject) => {
+    const req = https.request({
+      host: '127.0.0.1', port, path: '/login', method: 'POST', ca: fs.readFileSync(first.crt), checkServerIdentity: () => undefined,
+      headers: { 'content-type': 'application/x-www-form-urlencoded' }
+    }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res));
+    });
+    req.on('error', reject);
+    req.end('username=root&password=pw');
+  });
+  assert.equal(signIn.statusCode, 302);
+  assert.match(String(signIn.headers['set-cookie']), /;\s*Secure/i); // the cookie only travels over HTTPS
+
+  // Renewed in place (cert-manager, certbot): picked up without a restart.
+  fs.copyFileSync(renewed.crt, live.crt);
+  fs.copyFileSync(renewed.key, live.key);
+  process.emit('SIGHUP');
+  const after = await get(port, '/login', fs.readFileSync(renewed.crt));
+  assert.equal(after.subject, 'renewed');
+  assert.ok(logs.some((l) => /certificate reloaded \(SIGHUP\)/.test(l)), logs.join('\n'));
+
+  // A broken renewal keeps the working certificate.
+  fs.writeFileSync(live.key, 'not a key');
+  process.emit('SIGHUP');
+  assert.equal((await get(port, '/login', fs.readFileSync(renewed.crt))).subject, 'renewed');
+  assert.ok(logs.some((l) => /keeping the current certificate/.test(l)));
+});
+
+test('tls settings from the environment (THUB_TLS_*) win over the file', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-tls-')),
+    file = path.join(dir, 'coordinator.json'),
+    saved = { ...process.env };
+  fs.writeFileSync(file, JSON.stringify({ dataDir: path.join(dir, 'data'), tls: { certFile: '/file.crt', keyFile: '/file.key' } }));
+  Object.assign(process.env, { THUB_TLS_CERT: '/env.crt', THUB_TLS_KEY: '/env.key', THUB_TLS_CA: '/env-ca.crt', THUB_TLS_PASSPHRASE: 'pp' });
+  try {
+    assert.deepEqual(loadConfig(file).tls, { certFile: '/env.crt', keyFile: '/env.key', caFile: '/env-ca.crt', passphrase: 'pp' });
+  }
+  finally {
+    for (const k of ['THUB_TLS_CERT', 'THUB_TLS_KEY', 'THUB_TLS_CA', 'THUB_TLS_PASSPHRASE']){
+      if (saved[k] === undefined){
+        delete process.env[k];
+      }
+      else {
+        process.env[k] = saved[k];
+      }
+    }
+  }
+});

package/test/updates.test.js

@@ -29,7 +29,7 @@ async function setup(){
     clock = { t: Date.parse('2026-09-28T12:00:00Z') };
   fs.writeFileSync(pathUnit, '');
   const updates = createUpdatesService({
-    config: { dataDir, updates: {} },
+    config: { dataDir, updates: {}, selfUpdate: true }, // started with --self-update
     pathUnit,
     fetchLatest: async () => NEWER,
     now: () => clock.t
@@ -104,3 +104,40 @@ test('on startup, a finished update\'s status is cleared; a failure is kept for
   make().start();
   assert.equal(fs.existsSync(statusFile), true);
 });
+
+test('self-update is off unless the Coordinator was started with --self-update: no request, no button', async (t) => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-updates-')),
+    updates = createUpdatesService({ config: { dataDir, updates: {} }, pathUnit: path.join(dataDir, 'fake.path'), fetchLatest: async () => '99.0.0' });
+  fs.writeFileSync(path.join(dataDir, 'fake.path'), '');
+  await updates.checkNow();
+  assert.equal(updates.status().selfUpdate, false);
+  assert.ok(updates.status().coordinatorUpdate); // the notice still shows a newer version
+  assert.throws(() => updates.requestCoordinatorUpdate('admin'), /Self-update is off: start the Coordinator with --self-update/);
+  assert.ok(!fs.existsSync(path.join(dataDir, 'update-request.json')));
+
+  // The dashboard: a notice, no "Update app" button.
+  const { loadConfig } = require('../src/config'),
+    { buildServices, createApp } = require('../src/server'),
+    file = path.join(dataDir, 'coordinator.json');
+  fs.writeFileSync(file, JSON.stringify({ dataDir: path.join(dataDir, 'data'), updates: { checkIntervalMin: 0 } }));
+  for (const selfUpdate of [false, true]){
+    const config = { ...loadConfig(file), selfUpdate },
+      services = buildServices(config);
+    services.updates.checkNow = async () => {};
+    Object.assign(services.updates, { status: () => ({ latest: {}, coordinatorVersion: '1.0.0', coordinatorUpdate: '99.0.0', selfUpdate }) });
+    services.adminUsers.create({ username: `root${selfUpdate}`, email: `r${selfUpdate}@example.com`, role: 'admin', password: 'pw' }, { by: 't' });
+    const server = createApp(config, services).listen(0, '127.0.0.1');
+    await new Promise((r) => server.on('listening', r));
+    t.after(() => new Promise((r) => {
+      server.closeAllConnections?.();
+      server.close(r);
+    }));
+    const base = `http://127.0.0.1:${server.address().port}`,
+      cookie = (await fetch(`${base}/login`, {
+        method: 'POST', body: new URLSearchParams({ username: `root${selfUpdate}`, password: 'pw' }), redirect: 'manual'
+      })).headers.get('set-cookie').split(';')[0],
+      html = await (await fetch(`${base}/runners`, { headers: { cookie } })).text();
+    assert.equal(/action="\/updates\/coordinator"/.test(html), selfUpdate, `Update app button with selfUpdate=${selfUpdate}`);
+    assert.match(html, /v99\.0\.0 available|Update app to 99\.0\.0/);
+  }
+});

package/views/admin/agents.pug

@@ -31,7 +31,6 @@ block content
       tr
         +sortHeader(list, 'name', 'Name')
         +sortHeader(list, 'group', 'Group')
-        +sortHeader(list, 'version', 'Version', 'desc')
         +sortHeader(list, 'created', 'Created', 'desc')
         +sortHeader(list, 'used', 'Last used', 'desc')
         +sortHeader(list, 'status', 'Status')
@@ -42,13 +41,14 @@ block content
           //- The name opens Edit (name and group).
           td
             a.fw-medium(href=`#editAgentModal-${a.id}` data-bs-toggle="modal" role="button")= a.name
+            //- Its Agent's last reported version and update controls (none for a revoked token).
+            .thub-subline.text-body-secondary
+              +versionWithUpdate(a.version, updates.latest.agent, a.update_to, `/admin/agents/${a.id}/update`, list.pageUrl(), !a.revoked_at)
           td
             if a.group_id && groupsById[a.group_id]
               span.badge.text-bg-info= groupsById[a.group_id].name
             else
               span.text-body-secondary any
-          //- A revoked token can't pick an update up: no button.
-          td: +versionWithUpdate(a.version, updates.latest.agent, a.update_to, `/admin/agents/${a.id}/update`, list.pageUrl(), !a.revoked_at)
           td= fmtDate(a.created_at)
           td= fmtDate(a.last_used_at, 'never')
           td= a.revoked_at ? 'revoked' : 'active'
@@ -89,7 +89,7 @@ block content
 
       else
         tr
-          td.text-body-secondary(colspan="7")
+          td.text-body-secondary(colspan="6")
             if q
               | No agent matches “#{q}”. 
               a(href=list.urlFor({ q: '' })) Show all agents

package/views/help/_coordinator.pug

@@ -12,7 +12,8 @@
     #[code sudo npm i -g] does the whole setup for the user who ran #[code sudo]. It creates
     #[code ~/.config/thub/coordinator.json] (with a random #[code sessionSecret]) and
     #[code ~/var/lib/thub] (database, avatars). It installs, enables and starts
-    #[code thub-coordinator.service], plus the root helper behind the navbar's #[strong Update app] button.
+    #[code thub-coordinator.service], plus the root helper behind the navbar's #[strong Update app] button
+    (off unless the Coordinator runs with #[code --self-update]; see Updates below).
     The unit uses #[code ProtectSystem=strict] with #[code PrivateTmp=yes], so the data directory and a
     private #[code /tmp] (SQLite's temp files) are the only places the service can write.
 
@@ -58,6 +59,12 @@
         tr
           td: code session.secureCookie
           td #[code "auto"] (default): the session cookie is Secure (HTTPS-only) whenever #[code publicUrl] is https://. #[code true]/#[code false] force it. Sessions are stored in the database and survive restarts.
+        tr
+          td: code dbPath
+          td The SQLite database file. Default: #[code <dataDir>/thub.db]; a relative path is taken from #[code dataDir]. Its directory must be writable (SQLite's #[code -wal]/#[code -shm] files sit next to it). To move a database, stop the Coordinator and move #[code thub.db] with its #[code -wal]/#[code -shm] files.
+        tr
+          td: code tls.*
+          td #[code certFile] / #[code keyFile] (PEM): HTTPS served by the Coordinator itself, without a reverse proxy. #[code caFile]: intermediates, if not in the cert file; #[code passphrase]: for an encrypted key. Unset (default): plain HTTP. See #[strong HTTPS without a proxy] below.
         tr
           td: code clientJoinKey
           td The shared secret Clients self-register with. Unset or #[code null] turns registration off (#[code 503]).
@@ -86,7 +93,8 @@
   p.small.
     Resolution order: #[code THUB_COORDINATOR_CONFIG] (a path) → #[code ~/.config/thub/coordinator.json] → the bundled
     default. These environment variables override the file: #[code THUB_LISTEN], #[code THUB_PUBLIC_URL],
-    #[code THUB_DATA_DIR], #[code THUB_SESSION_SECRET] and #[code THUB_CLIENT_JOIN_KEY].
+    #[code THUB_DATA_DIR], #[code THUB_DB_PATH], #[code THUB_SESSION_SECRET], #[code THUB_CLIENT_JOIN_KEY] and #[code THUB_TLS_CERT] /
+    #[code THUB_TLS_KEY] / #[code THUB_TLS_CA] / #[code THUB_TLS_PASSPHRASE].
 
   h3.h6 3. HTTPS reverse proxy
   p.small.
@@ -112,6 +120,23 @@
           client_max_body_size 10m;     # log batches, avatars
         }
 
+  h3.h6 Or: HTTPS without a proxy
+  p.small.
+    The Coordinator can serve HTTPS itself, e.g. in Kubernetes or on a single host. Give it the certificate files
+    (readable by its user) and an #[code https://] #[code publicUrl]:
+  +code('coordinator.json').
+    {
+      "listen": "0.0.0.0:8443",
+      "publicUrl": "https://thub.example.com:8443",
+      "tls": { "certFile": "/etc/thub/tls/tls.crt", "keyFile": "/etc/thub/tls/tls.key" }
+    }
+  ul.small
+    li A bad path, half a pair or a key that doesn't match the certificate stops the start with the reason.
+    li Renewed files are picked up within a minute, or at once on #[code sudo systemctl kill -s HUP thub-coordinator]; a broken renewal keeps the working certificate.
+    li Port 443 under systemd needs #[code AmbientCapabilities=CAP_NET_BIND_SERVICE] (a drop-in), or use 8443. certbot's private key is root-only: copy it for the service user in a #[code --deploy-hook].
+    li Self-signed or private CA: start Clients and Agents with #[code NODE_EXTRA_CA_CERTS=/path/to/ca.pem] (a Client: #[code sudo systemctl edit thub-client@<instance>] → #[code Environment=NODE_EXTRA_CA_CERTS=…]).
+    li Kubernetes: mount the TLS secret and set #[code THUB_TLS_CERT] / #[code THUB_TLS_KEY] to its #[code tls.crt] / #[code tls.key].
+
   h3.h6 4. Users, agents and the join key
   p.small.
     #[code thub-admin] works directly on the database. Run it on the Coordinator host as the service user.
@@ -150,7 +175,12 @@
 
   h3.h6 Updates
   p.small.mb-0.
-    The Coordinator checks npm for new Coordinator, Agent and Client versions. Admins update the Coordinator
-    with #[strong Update app] in the navbar, and Agents and Clients from the #[a(href="/admin/agents") Agents]
-    and #[a(href="/runners") Runners] pages. Clients install an update only between jobs.
-    Manual alternatives: #[code thub-admin self-update], #[code thub self-update] and #[code thub-client self-update].
+    The Coordinator checks npm for new Coordinator, Agent and Client versions. Admins update Agents and Clients
+    from the #[a(href="/admin/agents") Agents] and #[a(href="/runners") Runners] pages; Clients install an update
+    only between jobs. Updating the #[strong Coordinator] from the dashboard (#[strong Update app] in the navbar)
+    is #[strong off by default]: start it with #[code --self-update] to turn it on. Under systemd:
+    #[code sudo sed -i 's|server.js$|server.js --self-update|' /etc/systemd/system/thub-coordinator.service],
+    then #[code sudo systemctl daemon-reload && sudo systemctl restart thub-coordinator] (a re-install keeps it).
+    Without it, a #[strong vX.Y.Z available] badge shows; update by hand — #[code thub-admin self-update],
+    #[code sudo npm i -g …], or a new container image. Manual alternatives for the others:
+    #[code thub self-update] and #[code thub-client self-update].

package/views/help/_kubernetes.pug

@@ -0,0 +1,169 @@
++section('kubernetes', 'Running in Kubernetes', 'boxes')
+  p.
+    The Coordinator runs as one container: the published package in a Node.js image, its SQLite database on a
+    persistent volume, TLS at the ingress. Clients and Agents connect from outside at #[code publicUrl].
+    Self-update stays off: the image starts the Coordinator without #[code --self-update], and you update it by
+    deploying a new image tag.
+
+  h3.h6 1. Build the image
+  +code('Dockerfile').
+    # syntax=docker/dockerfile:1
+    # docker build --build-arg THUB_VERSION=<version> -t registry.example.com/thub-coordinator:<version> .
+    ARG NODE_VERSION=22
+
+    FROM node:${NODE_VERSION}-bookworm-slim AS build
+    ARG THUB_VERSION
+    # Only needed if better-sqlite3 has no prebuilt binary for the platform.
+    RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ ca-certificates \
+     && rm -rf /var/lib/apt/lists/*
+    WORKDIR /app
+    # A local (not global) install: the package's systemd and ~/.config setup is skipped.
+    RUN npm pack "@andrian.yablonskyy/thub-coordinator@${THUB_VERSION}" \
+     && tar xzf andrian.yablonskyy-thub-coordinator-*.tgz --strip-components=1 && rm -f *.tgz \
+     && npm install --omit=dev --no-audit --no-fund && npm cache clean --force \
+     && rm -rf test systemd
+
+    FROM node:${NODE_VERSION}-bookworm-slim
+    # tini as PID 1: forwards SIGTERM and reaps zombies.
+    RUN apt-get update && apt-get install -y --no-install-recommends tini && rm -rf /var/lib/apt/lists/*
+    COPY --from=build /app /app
+    RUN ln -s /app/bin/thub-admin.js /usr/local/bin/thub-admin \
+     && mkdir -p /var/lib/thub && chown node:node /var/lib/thub
+    ENV NODE_ENV=production THUB_LISTEN=0.0.0.0:8080 THUB_DATA_DIR=/var/lib/thub
+    USER 1000:1000
+    WORKDIR /var/lib/thub
+    EXPOSE 8080
+    ENTRYPOINT ["/usr/bin/tini", "--"]
+    # No --self-update: a new image is how this Coordinator is updated.
+    CMD ["node", "/app/src/server.js"]
+  +code('Build and push').
+    docker build --build-arg THUB_VERSION=1.1.15 -t registry.example.com/thub-coordinator:1.1.15 .
+    docker push registry.example.com/thub-coordinator:1.1.15
+
+  h3.h6 2. Create the Secret
+  +code('Secrets as environment variables (they win over the config file and Settings)').
+    kubectl create namespace thub
+    kubectl -n thub create secret generic thub-coordinator-secrets \
+      --from-literal=THUB_SESSION_SECRET="$(openssl rand -hex 32)" \
+      --from-literal=THUB_CLIENT_JOIN_KEY="$(openssl rand -hex 24)" \
+      --from-literal=THUB_BOOTSTRAP_ADMIN_PASSWORD='choose-a-strong-password'
+
+  h3.h6 3. Apply the manifests
+  p.small.
+    Replace #[code thub.example.com], which must match #[code publicUrl], and the image.
+  +code('thub.yaml').
+    apiVersion: v1
+    kind: Namespace
+    metadata: { name: thub }
+    ---
+    # Non-secret settings, mounted as the config file. Settings changed on the
+    # dashboard are stored in the database, so this mount can be read-only.
+    apiVersion: v1
+    kind: ConfigMap
+    metadata: { name: thub-coordinator-config, namespace: thub }
+    data:
+      coordinator.json: |
+        {
+          "publicUrl": "https://thub.example.com",
+          "trustProxy": "loopback, uniquelocal",
+          "updates": { "checkIntervalMin": 15 }
+        }
+    ---
+    # SQLite needs block storage (ReadWriteOnce); avoid NFS-backed classes.
+    apiVersion: v1
+    kind: PersistentVolumeClaim
+    metadata: { name: thub-coordinator-data, namespace: thub }
+    spec:
+      accessModes: ["ReadWriteOnce"]
+      resources: { requests: { storage: 10Gi } }
+    ---
+    # One replica only: one SQLite file, scheduler in-process. Recreate frees
+    # the volume before the new pod opens the database.
+    apiVersion: apps/v1
+    kind: Deployment
+    metadata: { name: thub-coordinator, namespace: thub }
+    spec:
+      replicas: 1
+      strategy: { type: Recreate }
+      selector: { matchLabels: { app: thub-coordinator } }
+      template:
+        metadata: { labels: { app: thub-coordinator } }
+        spec:
+          securityContext: { runAsNonRoot: true, runAsUser: 1000, runAsGroup: 1000, fsGroup: 1000 }
+          containers:
+            - name: coordinator
+              image: registry.example.com/thub-coordinator:<version>
+              ports: [{ name: http, containerPort: 8080 }]
+              env:
+                - { name: THUB_COORDINATOR_CONFIG, value: /etc/thub/coordinator.json }
+              envFrom:
+                - secretRef: { name: thub-coordinator-secrets }   # THUB_SESSION_SECRET, THUB_CLIENT_JOIN_KEY, …
+              volumeMounts:
+                - { name: data, mountPath: /var/lib/thub }
+                - { name: config, mountPath: /etc/thub, readOnly: true }
+                - { name: tmp, mountPath: /tmp }                  # SQLite temp files (read-only root FS)
+              startupProbe: { httpGet: { path: /login, port: http }, periodSeconds: 5, failureThreshold: 24 }
+              readinessProbe: { httpGet: { path: /login, port: http }, periodSeconds: 10 }
+              livenessProbe: { tcpSocket: { port: http }, periodSeconds: 20 }
+              resources: { requests: { cpu: 100m, memory: 192Mi }, limits: { memory: 512Mi } }
+              securityContext: { allowPrivilegeEscalation: false, readOnlyRootFilesystem: true, capabilities: { drop: ["ALL"] } }
+          volumes:
+            - { name: data, persistentVolumeClaim: { claimName: thub-coordinator-data } }
+            - { name: config, configMap: { name: thub-coordinator-config } }
+            - { name: tmp, emptyDir: { sizeLimit: 256Mi } }
+    ---
+    apiVersion: v1
+    kind: Service
+    metadata: { name: thub-coordinator, namespace: thub }
+    spec:
+      selector: { app: thub-coordinator }
+      ports: [{ name: http, port: 80, targetPort: http }]
+    ---
+    # TLS at the ingress. Long polls and log streams (SSE) need long timeouts and
+    # no buffering; log batches and avatars stay under 10 MB.
+    apiVersion: networking.k8s.io/v1
+    kind: Ingress
+    metadata:
+      name: thub-coordinator
+      namespace: thub
+      annotations:
+        nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+        nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
+        nginx.ingress.kubernetes.io/proxy-buffering: "off"
+        nginx.ingress.kubernetes.io/proxy-body-size: "10m"
+        # cert-manager.io/cluster-issuer: letsencrypt
+    spec:
+      ingressClassName: nginx
+      tls: [{ hosts: ["thub.example.com"], secretName: thub-coordinator-tls }]
+      rules:
+        - host: thub.example.com
+          http:
+            paths:
+              - path: /
+                pathType: Prefix
+                backend: { service: { name: thub-coordinator, port: { name: http } } }
+  +code('Deploy').
+    kubectl apply -f thub.yaml
+    kubectl -n thub rollout status deploy/thub-coordinator
+    kubectl -n thub logs deploy/thub-coordinator      # listening on http://0.0.0.0:8080 · Self-update: off
+
+  h3.h6 4. First sign-in, then remove the bootstrap password
+  +code('It resets the admin password on every start while it\'s set').
+    kubectl -n thub patch secret thub-coordinator-secrets --type=json \
+      -p='[{"op":"remove","path":"/data/THUB_BOOTSTRAP_ADMIN_PASSWORD"}]'
+    kubectl -n thub rollout restart deploy/thub-coordinator
+  +code('thub-admin works inside the pod, on the same database').
+    kubectl -n thub exec deploy/thub-coordinator -- thub-admin user add alice --email alice@example.com --role admin --password '…'
+    kubectl -n thub exec deploy/thub-coordinator -- thub-admin agent add ci-firmware
+    kubectl -n thub exec deploy/thub-coordinator -- thub-admin join-key generate
+
+  h3.h6 Things to know
+  ul.small
+    li #[strong One replica.] One SQLite file and an in-process scheduler: no scale-out, no HPA. #[code Recreate] means a few seconds of downtime per upgrade; Clients and Agents reconnect by themselves.
+    li #[strong Updating:] deploy a new image tag. Migrations run on the new pod's first start. #[strong Update app] stays off (no #[code --self-update]); admins see a #[strong vX.Y.Z available] badge. Agents and Clients still update from the dashboard.
+    li #[strong Storage:] block storage (ReadWriteOnce), not NFS. A separate database volume: mount it and set #[code THUB_DB_PATH].
+    li #[strong /tmp] is an #[code emptyDir]: SQLite needs a writable temp directory and the root filesystem is read-only.
+    li #[strong Backups:] #[code kubectl -n thub exec deploy/thub-coordinator -- node -e "new (require('/app/node_modules/better-sqlite3'))('/var/lib/thub/thub.db').backup('/var/lib/thub/backup.db')"], then #[code kubectl cp].
+    li #[strong trustProxy] #[code "loopback, uniquelocal"] trusts the ingress from private ranges; set your pod CIDR if it's elsewhere.
+    li #[strong Other ingress controllers:] a read timeout well above 30 s, no response buffering, bodies up to 10 MB.
+    li #[strong HTTPS in the pod:] mount the TLS secret, set #[code THUB_TLS_CERT] / #[code THUB_TLS_KEY], listen on 8443, #[code scheme: HTTPS] in the probes, and an HTTPS backend (#[code nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"]) or a #[code LoadBalancer] on 443.

package/views/help/index.pug

@@ -8,6 +8,7 @@ block content
       { id: 'use-cases', label: 'Use cases' },
       { id: 'quick-start', label: 'Quick start' },
       { id: 'coordinator', label: 'Coordinator setup' },
+      { id: 'kubernetes', label: 'Running in Kubernetes' },
       { id: 'agent-setup', label: 'Agent setup' },
       { id: 'client-setup', label: 'Client setup' },
       { id: 'client-machines', label: 'Client machines (HW / SW)' },
@@ -53,6 +54,7 @@ block content
       include _overview
       include _quick-start
       include _coordinator
+      include _kubernetes
       include _agent-setup
       include _client-setup
       include _client-machines

package/views/layout.pug

@@ -29,11 +29,12 @@ html(lang="en" data-bs-theme=(user && user.theme) || "auto")
             data-bs-title=`Coordinator v${coordinatorVersion} · thub-common v${commonVersion} (validates job specs)`
           )
             | ver. #{coordinatorVersion}
-            if user && !can.admin && updates.coordinatorUpdate
+            //- Without --self-update (or for non-admins): just the notice.
+            if user && updates.coordinatorUpdate && !(can.admin && updates.selfUpdate)
               span.badge.text-bg-warning.ms-1(
                 data-bs-toggle="tooltip"
                 data-bs-placement="bottom"
-                data-bs-title="An admin can update the Coordinator from the navbar"
+                data-bs-title=updates.selfUpdate ? 'An admin can update the Coordinator from the navbar' : 'Update the Coordinator by hand (thub-admin self-update, npm i -g, or a new container image); self-update from the dashboard is off'
               )= `v${updates.coordinatorUpdate} available`
         button.navbar-toggler(type="button" data-bs-toggle="collapse" data-bs-target="#nav")
           span.navbar-toggler-icon
@@ -91,7 +92,7 @@ html(lang="en" data-bs-theme=(user && user.theme) || "auto")
                     data-bs-title=updates.checkedAt ? `Check for updates now — the Coordinator and connected runners (last checked ${fmtDate(updates.checkedAt)})` : 'Check for updates now — the Coordinator and connected runners'
                   )
                     i.bi.bi-arrow-repeat
-            if user && can.admin && updates.coordinatorUpdate
+            if user && can.admin && updates.selfUpdate && updates.coordinatorUpdate
               li.nav-item.d-flex.align-items-center.me-3
                 if updates.coordinatorPending
                   //- public/js/update-watch.js polls /updates/status and

package/views/resources/list.pug

@@ -24,21 +24,25 @@ block content
       tr
         +sortHeader(list, 'name', 'Name')
         +sortHeader(list, 'type', 'Type')
-        +sortHeader(list, 'version', 'Version', 'desc')
         +sortHeader(list, 'status', 'Status')
         th Labels
         th Groups
         th Busy source / reason
-        +sortHeader(list, 'heartbeat', 'Last heartbeat', 'desc')
         if can.operate
           th Actions
     tbody(data-live="rows")
       each r in resources
         tr(role="button" tabindex="0" data-resource-card=`resource-card-${r.id}`)
-          td= r.name
+          //- Name, and under it the Client's version (with its update controls).
+          td
+            div= r.name
+            .thub-subline.text-body-secondary
+              +versionWithUpdate(r.client_version, updates.latest.client, r.update_to, `/runners/${r.id}/update`, list.pageUrl(), true, r.activity && r.activity.state === 'update-hold')
           td.text-uppercase= r.type
-          td: +versionWithUpdate(r.client_version, updates.latest.client, r.update_to, `/runners/${r.id}/update`, list.pageUrl(), true, r.activity && r.activity.state === 'update-hold')
-          td: +resourceBadge(r.status, r.remove_requested_at)
+          //- Status, and under it when the Client last heartbeated.
+          td
+            +resourceBadge(r.status, r.remove_requested_at)
+            .thub-subline.text-body-secondary.text-nowrap(title="Last heartbeat")= fmtDate(r.last_heartbeat_at, 'never')
           //- One label per line.
           td
             if r.labels.length
@@ -52,7 +56,6 @@ block content
             else
               span.text-body-secondary —
           td= r.busy_source ? `${r.busy_source}${r.busy_reason ? ' — ' + r.busy_reason : ''}` : '—'
-          td= fmtDate(r.last_heartbeat_at, 'never')
           if can.operate
             td
               +resourceActions(r, list.pageUrl())