@andrian.yablonskyy/thub-coordinator 1.1.13 → 1.1.15

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
 ```
@@ -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.13",
+  "version": "1.1.15",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {
@@ -19,7 +19,7 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^1.1.3",
+    "@andrian.yablonskyy/thub-common": "^1.1.4",
     "better-sqlite3": "^12.4.1",
     "express": "^5.1.0",
     "express-session": "^1.18.2",

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/help/_agent-cli.pug

@@ -25,7 +25,7 @@
       { title: 'What to run', rows: [
         ['--command <string>', 'Required. Run with sh -c in the work directory. Exit code 0 = PASSED. It clones repositories and runs containers itself (see Using git / Using Docker).', "--command './ci/test.sh'"],
         ['--arg <value>', 'Argument for the command, as "$@" (repeatable).', '--arg --junit --arg -v'],
-        ['--suite <name>', 'Passed as THUB_SUITE (default: default).', '--suite smoke'],
+        ['--suite <name>', 'Passed as JOB_SUITE (default: default).', '--suite smoke'],
         ['--download-file <url>', 'File downloaded before the command (repeatable, http(s), no credentials). THUB_DOWNLOAD_1…', '--download-file https://…/app.bin'],
         ['--env <vars>', 'NAME=value[,NAME=value] for the command (repeatable): how data and secrets reach the job (git tokens, registry passwords). --env NAME takes the value from your shell. Masked, dropped at job end.', '--env TARGET=staging --env API_TOKEN']
       ] },
@@ -70,12 +70,12 @@
     thub run --type hw --label board:nucleo-f401re \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
       --env GH_TOKEN \
-      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
-                 st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
+      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
+                 st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
       --arg --junit --timeout 45m --wait
   +code('Reproduce a failure on the exact bench (the job carries your username)').
     thub run --type hw --label board:nucleo-f401re --client lab-hw-01 \
-      --download-file "$IMAGE_URL" --env GH_TOKEN --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" . && ./ci/test.sh'
+      --download-file "$IMAGE_URL" --env GH_TOKEN --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" src && cd src && ./ci/test.sh'
     # Ctrl-C detaches; the job keeps running. Re-attach:
     thub status M-00126
   +code('Verify a download before using it').

package/views/help/_ci.pug

@@ -34,8 +34,8 @@
                 --type hw --label board:nucleo-f401re \
                 --download-file "${{ needs.build.outputs.image_url }}" \
                 --env GH_TOKEN="${{ secrets.TESTS_READ_TOKEN }}",SHA="$GITHUB_SHA",REPO="$GITHUB_REPOSITORY" \
-                --command 'git init -q . && git fetch -q --depth 1 "https://x-access-token:$GH_TOKEN@github.com/$REPO.git" "$SHA" && git checkout -q FETCH_HEAD &&
-                           st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh' \
+                --command 'git init -q src && cd src && git fetch -q --depth 1 "https://x-access-token:$GH_TOKEN@github.com/$REPO.git" "$SHA" && git checkout -q FETCH_HEAD &&
+                           st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh' \
                 --suite smoke --timeout 30m --wait \
                 --meta runUrl="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
   ul.small.mb-0

package/views/help/_client-machines.pug

@@ -53,8 +53,8 @@
     thub run --type hw --label board:nucleo-f401re \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
       --env GH_TOKEN \
-      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
-                 st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
+      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
+                 st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
       --wait
 
   +note('warning').
@@ -74,10 +74,9 @@
   +code('A typical SW job').
     thub run --type sw \
       --env GH_TOKEN --env DOCKER_PASSWORD \
-      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
-                 export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
                  echo "$DOCKER_PASSWORD" | docker login registry.lab.local:5000 -u ci --password-stdin &&
-                 docker run --rm -v "$PWD:/work" -w /work registry.lab.local:5000/dut-emulator:2026.08 make test' --wait
+                 docker run --rm --user "$(id -u):$(id -g)" -v "$THUB_WORK_DIR/src:/work" -w /work registry.lab.local:5000/dut-emulator:2026.08 make test' --wait
 
   h3.h6 Checklist for any Client machine
   ul.small.mb-0

package/views/help/_client-setup.pug

@@ -106,8 +106,8 @@
     change it hasn't applied yet. #[strong USB devices → Import to config] fills them from the host's #[code lsusb].
     The card's #[strong Export] and #[strong Import] icons download a Client's config file (never its
     #[code joinKey]) and apply one to it. An older HW Client takes only the file's #[code hw-devices].
-    There's no ST-Link serial field: the job's #[code --command] picks the probe
-    (#[code $THUB_DUT_STLINK_<n>]), and the Client reads each serial from its udev symlink.
+    There's no ST-Link serial field: the job's #[code --command] picks the probe (#[code st-flash] alone uses the
+    only one; with several, #[code st-flash --serial] with a serial from #[code st-info --probe]).
 
   h3.h6 Several DUT slots on one machine
   +code('One instance per slot').

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/_docker.pug

@@ -13,11 +13,10 @@
     thub run --type sw \
       --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
       --env TARGET=staging \
-      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
-                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
-                 docker run --rm \
-                   -v "$THUB_WORK_DIR:/work" -w /work --user "$(id -u):$(id -g)" \
-                   -e TARGET -e THUB_SUITE -e THUB_JOB_ID \
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 docker run --rm --user "$(id -u):$(id -g)" \
+                   -v "$THUB_WORK_DIR/src:/work" -w /work \
+                   -e TARGET -e JOB_SUITE -e THUB_JOB_ID \
                    "$DOCKER_REGISTRY/team/test-runner:1.4" ./run-tests.sh --junit results/junit.xml' \
       --wait
   table.table.table-sm.small
@@ -30,8 +29,8 @@
         td: code --rm
         td Removes the container when the tests end.
       tr
-        td: code -v "$THUB_WORK_DIR:/work" -w /work
-        td The work directory, where the Client reads JUnit XML under #[code results/] and #[code artifacts/] for the test counts.
+        td: code -v "$THUB_WORK_DIR/src:/work" -w /work
+        td Only the clone (#[code src/]), not the job directory, which holds the registry login in #[code .docker/]. The Client reads JUnit XML from #[code src/results/] or #[code src/artifacts/] for the test counts.
       tr
         td: code -e NAME
         td Passes a job variable (#[code --env], #[code THUB_*], #[code JOB_*]) into the container.
@@ -40,7 +39,37 @@
         td Files written to #[code /work] stay owned by the Client user, so the workspace can be cleaned up.
       tr
         td: code --device /dev/thub/dut1-uart
-        td HW: gives the container the DUT's UART (#[code "$THUB_DUT_UART"]). Use #[code --privileged] only if you must.
+        td HW: gives the container the DUT's UART (#[code /dev/thub/dut1-uart]). Use #[code --privileged] only if you must.
+
+  h3.h6 Clone and test inside a container, with a deploy key and a registry login from the job
+  p.small.
+    Everything comes from the Agent as #[code --env]: the registry and its credentials, and the private key the
+    container clones with. Nothing is set up on the Client host beforehand.
+  +code('Reference example').
+    # In CI, from its secret store — never typed on the command line:
+    export THUB_KEY=…                              # a CI token (dashboard → CI tokens)
+    export DOCKER_PASSWORD=…                       # the registry password
+    export GIT_KEY="$(cat ~/.ssh/thub_deploy)"     # a private deploy key with read access to the repository
+    
+    thub run --type sw \
+      --env DOCKER_REGISTRY=registry.lab:5000,DOCKER_USERNAME=ci-reader \
+      --env DOCKER_PASSWORD --env GIT_KEY \
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" --username "$DOCKER_USERNAME" --password-stdin &&
+                 mkdir -p "$THUB_WORK_DIR/src" &&
+                 docker run --rm -e GIT_KEY -e HOME=/tmp --user "$(id -u):$(id -g)" \
+                   -v "$THUB_WORK_DIR/src:/work" -w /work --entrypoint sh alpine/git -c "
+                   eval \$(ssh-agent -s) > /dev/null &&
+                   printf \"%s\n\" \"\$GIT_KEY\" | ssh-add - &&
+                   GIT_SSH_COMMAND=\"ssh -o StrictHostKeyChecking=accept-new\" git clone --depth 1 git@bitbucket.org:yourorg/web-ui-tests.git . &&
+                   ./run-tests.sh"' \
+      --wait
+  ul.small
+    li Plain values go as #[code --env NAME=value]. Secrets go as #[code --env NAME] alone: the Agent takes the value from its own environment, so it never appears on the command line, in shell history or in CI logs. A multi-line value, such as the key, arrives intact.
+    li The Client sets #[code DOCKER_CONFIG=$THUB_WORK_DIR/.docker]: the registry login lands in the job's directory, deleted with the job. Only #[code src/] is mounted into the container, so the login isn't visible in it.
+    li #[code -e GIT_KEY] hands the key to the container. #[code --entrypoint sh] is needed because #[code alpine/git]'s own entrypoint is #[code git]. #[code --user "$(id -u):$(id -g)"] (with #[code HOME=/tmp]) keeps the clone owned by the Client user, so it can be deleted with the job; #[code mkdir -p] first so Docker doesn't create #[code src/] as root.
+    li In the inner script, #[code \$] is escaped, so the #[strong container] expands the variables, not the Client's shell. #[code ssh-agent] holds the key in memory: it's never written to a file. #[code accept-new] trusts the git server's host key on first use.
+    li #[code alpine/git] comes from Docker Hub. The #[code docker login] is for private images such as #[code $DOCKER_REGISTRY/team/test-runner:1.4].
+    li Never #[code echo] a secret: the command's output is the job log, which is stored and visible.
 
   h3.h6 An emulator as the DUT
   p.small.
@@ -49,8 +78,7 @@
     thub run --type sw \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.elf \
       --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
-      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
-                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
                  dut="thub-$THUB_JOB_ID" && trap "docker rm -f $dut >/dev/null" EXIT &&
                  docker run -d --name "$dut" -p 127.0.0.1:5555:5555 -v "$THUB_DOWNLOADS_DIR:/downloads:ro" \
                    "$DOCKER_REGISTRY/dut-emulator:2026.08" &&

package/views/help/_env.pug

@@ -10,14 +10,11 @@
     const thubVars = [
       ['THUB_JOB_ID', 'The job id, e.g. M-00125'],
       ['THUB_ARTIFACTS_FILE', 'Where the command may list the artifacts it published elsewhere: a JSON array of {"name", "size", "link", "timestamp"}, shown on the job page'],
-      ['THUB_WORK_DIR', 'The directory the command runs in, empty at the start (clone into it if you need a repository). JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
-      ['THUB_SUITE', '--suite (default: default)'],
+      ['THUB_WORK_DIR', 'The job\'s directory (<client workDir>/<jobId>), where the command starts. Holds downloads/, the artifacts list and .docker/ (the job\'s DOCKER_CONFIG); clone into a folder of your own, e.g. src/. JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
+      ['DOCKER_CONFIG', '$THUB_WORK_DIR/.docker — so a docker login stays with the job and is deleted with it (unless --env sets DOCKER_CONFIG)'],
       ['THUB_DOWNLOADS_DIR', 'Where the --download-file files are'],
       ['THUB_DOWNLOADS / THUB_DOWNLOAD_<n>', 'Local paths of the downloads: all, one per line / each one'],
       ['THUB_META_<KEY>', '--meta values; camelCase keys become SNAKE_CASE (ciJobId → THUB_META_CI_JOB_ID)'],
-      ['THUB_DUT_STLINK / _<n>', 'HW: ST-Link serials (device path if the serial couldn\'t be read); unsuffixed = the first'],
-      ['THUB_DUT_UART / _<n>', 'HW: UART device paths (/dev/thub/dut<N>-uart); unsuffixed = the first'],
-      ['THUB_DUT_USB / _<n>', 'HW: DUT USB device paths']
     ]
   .table-responsive
     table.table.table-sm.small
@@ -80,7 +77,7 @@
   +code('ci/test.sh (shell)').
     #!/bin/sh
     set -eu
-    echo "Job $THUB_JOB_ID on $(hostname), suite ${THUB_SUITE}"
+    echo "Job $THUB_JOB_ID on $(hostname), suite ${JOB_SUITE}"
 
     # optional parameters with defaults
     TARGET="${TARGET:-staging}"
@@ -90,21 +87,21 @@
     printf '%s\n' "$THUB_DOWNLOADS" | while read -r f; do echo "downloaded: $f"; done
 
     # HW: flash through the first ST-Link, talk to the second UART
-    st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000
-    python3 -m pytest tests/ --uart "${THUB_DUT_UART_2:-$THUB_DUT_UART}" --junitxml=results/junit.xml
+    st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000
+    python3 -m pytest tests/ --uart "/dev/thub/dut2-uart" --junitxml=results/junit.xml
 
     # CI metadata passed with --meta ciJobId=… / --meta sha=…
     echo "CI run ${THUB_META_CI_JOB_ID:-local}, sha ${THUB_META_SHA:-unknown}"
   +code('conftest.py (Python)').
-    import os
+    import glob, os
 
-    UARTS     = [v for k, v in sorted(os.environ.items()) if k.startswith("THUB_DUT_UART_")]
+    UARTS     = sorted(glob.glob("/dev/thub/dut*-uart"))                # this Client's UARTs, by udev path
     FIRMWARE  = os.environ.get("THUB_DOWNLOAD_1")
-    RESULTS   = os.path.join(os.environ.get("THUB_WORK_DIR", "."), "results")
+    RESULTS   = "results"                                            # in the clone (src/results), where the tests run
     API_TOKEN = os.environ["API_TOKEN"]                              # from --env API_TOKEN
   +code('Into a container: -e NAME copies a variable from the job').
-    docker run --rm -v "$THUB_WORK_DIR:/work" -w /work \
-      -e THUB_JOB_ID -e THUB_SUITE -e TARGET -e API_TOKEN \
+    docker run --rm --user "$(id -u):$(id -g)" -v "$THUB_WORK_DIR/src:/work" -w /work \
+      -e THUB_JOB_ID -e JOB_SUITE -e TARGET -e API_TOKEN \
       python:3.14 ./run-tests.sh
   +code('Submitting the job that feeds these').
     export API_TOKEN=…
@@ -113,7 +110,7 @@
       --env TARGET=production,BRANCH=main --env API_TOKEN --env GH_TOKEN \
       --meta ciJobId="$GITHUB_RUN_ID" --meta sha="$GITHUB_SHA" \
       --suite smoke \
-      --command 'git clone --depth 1 --branch "$BRANCH" "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+      --command 'git clone --depth 1 --branch "$BRANCH" "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
                  ./ci/test.sh' --wait
   p.small.text-body-secondary.mb-0.
     Tip: #[code thub run … --dry-run] lists every variable the command would get on the chosen Client, with #[code --env] values as #[code ***].

package/views/help/_git.pug

@@ -11,7 +11,7 @@
     export GH_TOKEN=…      # GitHub: a fine-grained PAT with read access; GitLab: oauth2 token; Bitbucket: x-token-auth
     thub run --type sw \
       --env GH_TOKEN \
-      --command 'git clone --depth 1 --branch main "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+      --command 'git clone --depth 1 --branch main "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
                  ./ci/test.sh' \
       --wait
   p.small.
@@ -23,19 +23,23 @@
     export DEPLOY_KEY_B64="$(base64 < ~/.ssh/thub_deploy | tr -d '\n')"
     thub run --type hw --label board:nucleo-f401re \
       --env DEPLOY_KEY_B64 \
-      --command 'umask 077 && echo "$DEPLOY_KEY_B64" | base64 -d > "$THUB_WORK_DIR/../key" &&
-                 GIT_SSH_COMMAND="ssh -i $THUB_WORK_DIR/../key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
-                   git clone --depth 1 git@github.com:yourorg/firmware-tests.git . &&
+      --command 'umask 077 && echo "$DEPLOY_KEY_B64" | base64 -d > "$THUB_WORK_DIR/key" &&
+                 GIT_SSH_COMMAND="ssh -i $THUB_WORK_DIR/key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
+                   git clone --depth 1 git@github.com:yourorg/firmware-tests.git src && cd src &&
                  ./ci/test.sh' \
       --wait
   p.small.
     The job directory, key included, is deleted when the job ends. Add the public key as a read-only deploy key: GitHub,
     Repository → Settings → Deploy keys; GitLab, Settings → Repository → Deploy keys; Bitbucket, Repository settings → Access keys.
 
+  p.small.
+    To clone #[em inside a container] with a key passed the same way (held by #[code ssh-agent], never written to disk), see
+    #[a(href="#docker") Using Docker → Clone and test inside a container].
+
   h3.h6 Branch, tag, commit, submodules, LFS
   +code('All in the command').
-    git clone --depth 1 --branch v1.4.0 "$REPO" .                            # a branch or tag
-    git init -q . && git remote add origin "$REPO" && git fetch -q --depth 1 origin a1b2c3d && git checkout -q FETCH_HEAD   # a commit
+    git clone --depth 1 --branch v1.4.0 "$REPO" src                            # a branch or tag
+    git init -q src && cd src && git remote add origin "$REPO" && git fetch -q --depth 1 origin a1b2c3d && git checkout -q FETCH_HEAD   # a commit
     git submodule update --init --recursive --depth 1 && git lfs pull        # submodules / LFS
   p.small.
     Pass the repository and ref as #[code --env REPO=…,REF=…] (or #[code --meta]) so the same command works for every branch.

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/mixins/client-config.pug

@@ -249,7 +249,7 @@ mixin configPanes(r, returnTo, groupsById)
         +configPane(p, 'stlinks')
           +capabilitiesStatus(r)
           +deviceTable('stlinks', 'ST-Link probes', current.stlinks || [], ['Device', 'udev devpath'])
-          .form-text Device: a udev index 1–8 (→ /dev/thub/dut<N>-stlink) or a /dev path. Which probe a job uses is up to its #[code --command] (#[code $THUB_DUT_STLINK_<n>]).
+          .form-text Device: a udev index 1–8 (→ /dev/thub/dut<N>-stlink) or a /dev path. Which probe a job uses is up to its #[code --command] (st-flash, by serial with several probes).
           +saveCapabilities(canEdit)
         +configPane(p, 'uarts')
           +capabilitiesStatus(r)