@andrian.yablonskyy/thub-coordinator 1.0.11 → 1.0.12

package/README.md

@@ -102,7 +102,7 @@ thub-admin group add ci-nightly --comment "shared CI pool"
 thub-admin group list
 thub-admin group remove <groupId>
 
-# The Coordinator is only ever updated by hand (never from the dashboard).
+# Update the Coordinator by hand (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
 ```
@@ -161,10 +161,10 @@ Server-rendered Pug templates styled with Bootstrap 5.3, with a little vanilla J
 
 The Coordinator's own version (`ver. X.Y.Z`) is shown under the TestHub logo, top left of every page.
 
-**Versions and self-update.** The Coordinator checks the npm registry for the latest Coordinator, Agent and Client every `updates.checkIntervalHours` (default 6, `0` disables; `updates.registry` for a private mirror) and on **Check for updates**. A newer Coordinator shows as a badge under the logo; 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:
+**Versions and self-update.** The Coordinator checks the npm registry for the latest Coordinator, Agent and Client every `updates.checkIntervalHours` (default 6, `0` disables; `updates.registry` for a private mirror) and on **Check for updates**. 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 is updated by hand only: `thub-admin self-update`.
+- 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.
 
 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.0.11",
+  "version": "1.0.12",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {

package/scripts/install-systemd-unit.js

@@ -24,7 +24,12 @@ const fs = require('node:fs'),
   UNIT_SRC = path.join(__dirname, '..', 'systemd', UNIT_NAME),
   SERVER_PATH = path.join(__dirname, '..', 'src', 'server.js'),
   UNIT_DEST = `/etc/systemd/system/${UNIT_NAME}`,
-  MANUAL_HINT = 'sudo npm i -g @andrian.yablonskyy/thub-coordinator';
+  MANUAL_HINT = 'sudo npm i -g @andrian.yablonskyy/thub-coordinator',
+  // Root-side self-update (README §10.2): the path unit watches the update
+  // request the dashboard writes, the service installs it.
+  UPDATE_PATH_UNIT = 'thub-coordinator-update.path',
+  UPDATE_SERVICE_UNIT = 'thub-coordinator-update.service',
+  UPDATE_HELPER = path.join(__dirname, 'self-update-helper.js');
 
 // 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
@@ -38,6 +43,19 @@ function renderUnit(user, paths){
     .replace(/^ReadWritePaths=.*$/m, `ReadWritePaths=${paths.dataDir}`);
 }
 
+function renderUpdateUnits(user, paths){
+  const nodeDir = path.dirname(process.execPath),
+    unitPath = (name) => path.join(__dirname, '..', 'systemd', name);
+  return {
+    [UPDATE_PATH_UNIT]: fs.readFileSync(unitPath(UPDATE_PATH_UNIT), 'utf8')
+      .replace(/^PathModified=.*$/m, `PathModified=${paths.updateRequestFile}`),
+    // npm is a `#!/usr/bin/env node` script, so this node goes first on PATH.
+    [UPDATE_SERVICE_UNIT]: fs.readFileSync(unitPath(UPDATE_SERVICE_UNIT), 'utf8')
+      .replace(/^Environment=PATH=.*$/m, `Environment=PATH=${nodeDir}:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`)
+      .replace(/^ExecStart=.*$/m, `ExecStart=${process.execPath} ${UPDATE_HELPER} ${paths.updateRequestFile} ${user.name}`)
+  };
+}
+
 // Best-effort, never fails the `npm install` itself. Runs after
 // install-default-config.js, so the config and data dirs the unit points
 // at already exist. `restart` (not `start`) so an upgrade picks up the
@@ -51,12 +69,18 @@ function main(){
     return;
   }
 
-  const user = resolveTargetUser();
+  const user = resolveTargetUser(),
+    paths = targetPaths(user);
   let step = 'write';
   try {
-    fs.writeFileSync(UNIT_DEST, renderUnit(user, targetPaths(user)));
+    fs.writeFileSync(UNIT_DEST, renderUnit(user, paths));
+    for (const [name, content]of Object.entries(renderUpdateUnits(user, paths))){
+      fs.writeFileSync(`/etc/systemd/system/${name}`, content);
+    }
     step = 'daemon-reload';
     execFileSync('systemctl', ['daemon-reload'], { stdio: 'ignore' });
+    step = `enable ${UPDATE_PATH_UNIT}`;
+    execFileSync('systemctl', ['enable', '--now', UPDATE_PATH_UNIT], { stdio: 'ignore' });
     step = 'enable';
     execFileSync('systemctl', ['enable', UNIT_NAME], { stdio: 'ignore' });
     step = 'restart';

package/scripts/install-target.js

@@ -66,6 +66,9 @@ function targetPaths(user){
     configPath,
     defaultDataDir,
     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'),
     dataSubdirs: ['artifacts', 'avatars', 'work'].map((d) => path.join(dataDir, d))
   };
 }

package/scripts/self-update-helper.js

@@ -0,0 +1,67 @@
+/**
+ * @file        scripts/self-update-helper.js
+ * @description Root side of the Coordinator's self-update (README §10.2): run by thub-coordinator-update.service
+ *              when the dashboard writes an update request, installs the requested version with npm i -g
+ *
+ * @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'),
+  { PACKAGES, isValidVersion, compareVersions, npmInstallGlobal } = require('@andrian.yablonskyy/thub-common'),
+  { version: installedVersion } = require('../package.json');
+
+// argv: <request file> <user the Coordinator runs as>. The request file
+// is written by the (unprivileged) Coordinator, so only its `version` is
+// used, and only if it's a plain semver — the package is fixed.
+function main(){
+  const [requestFile, user] = process.argv.slice(2);
+  if (!requestFile || !user){
+    console.error('usage: self-update-helper.js <request file> <user>');
+    return 2;
+  }
+
+  let request;
+  try {
+    request = JSON.parse(fs.readFileSync(requestFile, 'utf8'));
+  }
+  catch (err){
+    // Deleted by a previous run (PathModified= also fires on removal).
+    if (err.code === 'ENOENT'){
+      return 0;
+    }
+    console.error(`thub-coordinator-update: unreadable request ${requestFile}: ${err.message}`);
+    fs.rmSync(requestFile, { force: true });
+    return 1;
+  }
+  fs.rmSync(requestFile, { force: true });
+
+  const target = request?.version;
+  if (!isValidVersion(target)){
+    console.error('thub-coordinator-update: ignoring request with an invalid version');
+    return 1;
+  }
+  if (compareVersions(installedVersion, target) >= 0){
+    console.log(`thub-coordinator-update: already on v${installedVersion} (requested v${target})`);
+    return 0;
+  }
+
+  console.log(`thub-coordinator-update: v${installedVersion} -> v${target} (requested by ${request.requestedBy || 'the dashboard'})`);
+  // SUDO_USER makes the postinstall scripts target the Coordinator's user,
+  // as a `sudo npm i -g` by that user would (install-target.js); the
+  // postinstall then restarts thub-coordinator on the new version.
+  const status = npmInstallGlobal(PACKAGES.coordinator, target, { env: { ...process.env, SUDO_USER: user } });
+  if (status !== 0){
+    console.error(`thub-coordinator-update: npm i -g failed (exit ${status})`);
+  }
+  return status;
+}
+
+process.exit(main());

package/src/services/updates.js

@@ -13,15 +13,21 @@
 
 'use strict';
 
-const { PACKAGES, fetchLatestVersion, defaultRegistry, isNewer } = require('@andrian.yablonskyy/thub-common'),
+const fs = require('node:fs'),
+  path = require('node:path'),
+  { PACKAGES, fetchLatestVersion, defaultRegistry, isNewer } = require('@andrian.yablonskyy/thub-common'),
   { version: coordinatorVersion } = require('../../package.json');
 
+// Installed by scripts/install-systemd-unit.js; runs the actual `npm i -g`
+// as root when the dashboard writes an update request (README §10.2).
+const UPDATE_PATH_UNIT = '/etc/systemd/system/thub-coordinator-update.path';
+
 // Latest published versions, refreshed every `updates.checkIntervalHours`
 // and on demand from the dashboard. Kept in memory only — a restart just
 // checks again.
 function createUpdatesService({ config }){
   const registry = config.updates.registry || defaultRegistry(),
-    state = { latest: {}, checkedAt: null, error: null };
+    state = { latest: {}, checkedAt: null, error: null, coordinatorPending: null };
   let inFlight = null;
 
   async function checkNow(){
@@ -55,6 +61,28 @@ function createUpdatesService({ config }){
     };
   }
 
+  // Navbar "Update app" button: hand the latest version to the root
+  // thub-coordinator-update helper, whose install restarts this process
+  // (so `coordinatorPending` only lasts until then).
+  function requestCoordinatorUpdate(requestedBy){
+    const target = status().coordinatorUpdate;
+    if (!target){
+      throw Object.assign(new Error(`Already on the latest version (v${coordinatorVersion}).`), { status: 409 });
+    }
+    if (!fs.existsSync(UPDATE_PATH_UNIT)){
+      throw Object.assign(
+        new Error(`Self-update isn't installed on this host (${UPDATE_PATH_UNIT}) — update by hand: thub-admin self-update`),
+        { status: 501 }
+      );
+    }
+    fs.writeFileSync(
+      path.join(config.dataDir, 'update-request.json'),
+      JSON.stringify({ version: target, requestedBy, requestedAt: new Date().toISOString() }) + '\n'
+    );
+    state.coordinatorPending = target;
+    return target;
+  }
+
   // The version a self-update request targets: the latest known one,
   // checking first if nothing has been fetched yet.
   async function targetVersion(app){
@@ -77,7 +105,7 @@ function createUpdatesService({ config }){
     timer.unref?.();
   }
 
-  return { checkNow, status, targetVersion, start };
+  return { checkNow, status, targetVersion, requestCoordinatorUpdate, start };
 }
 
 module.exports = { createUpdatesService };

package/src/web/routes.js

@@ -60,6 +60,7 @@ function createWebRouter({ services, config }){
     // Latest published versions (README §10.2) — navbar, Agents, Resources.
     res.locals.updates = services.updates.status();
     res.locals.isNewer = isNewer;
+    res.locals.currentPath = req.originalUrl;
     if (req.session){
       req.session.flash = [];
     }
@@ -259,6 +260,12 @@ function createWebRouter({ services, config }){
     return s.error ? `Version check: ${found || 'nothing found'} (errors: ${s.error})` : `Latest versions: ${found}.`;
   }));
 
+  router.post('/updates/coordinator', requireAdminRole, updateAction(async (req) => {
+    const version = services.updates.requestCoordinatorUpdate(req.session.user.username);
+    console.log(`Coordinator self-update to v${version} requested by ${req.session.user.username}`);
+    return `Updating the Coordinator to v${version} — the dashboard restarts in a minute or two; reload the page then.`;
+  }));
+
   router.post('/resources/update-all', requireAdminRole, updateAction(async () => {
     const version = await services.updates.targetVersion('client'),
       n = services.registry.requestUpdateAll(version);

package/systemd/thub-coordinator-update.path

@@ -0,0 +1,13 @@
+[Unit]
+Description=TestHub Coordinator self-update request watcher
+
+# PathModified= is rewritten by scripts/install-systemd-unit.js to the
+# update-request.json in the Coordinator's dataDir. The dashboard's
+# "Update app" button writes it; this starts thub-coordinator-update.service
+# (as root) to install the requested version.
+[Path]
+PathModified=/var/lib/thub/.thub/update-request.json
+Unit=thub-coordinator-update.service
+
+[Install]
+WantedBy=multi-user.target

package/systemd/thub-coordinator-update.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=TestHub Coordinator self-update
+After=network-online.target
+Wants=network-online.target
+
+# ExecStart and Environment= are rewritten by scripts/install-systemd-unit.js
+# to this install's real node and helper paths, the request file, and the
+# user the Coordinator runs as. Runs as root: `npm i -g` writes the global
+# node_modules, and its postinstall re-renders these units and restarts
+# thub-coordinator. The helper only ever installs
+# @andrian.yablonskyy/thub-coordinator, at a strictly validated version.
+[Service]
+Type=oneshot
+Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ExecStart=/usr/bin/node /usr/lib/node_modules/@andrian.yablonskyy/thub-coordinator/scripts/self-update-helper.js /var/lib/thub/.thub/update-request.json thub
+TimeoutStartSec=15min

package/views/layout.pug

@@ -14,11 +14,11 @@ html(lang="en" data-bs-theme=(user && user.theme) || "auto")
           span TestHub
           small.text-body-secondary.fw-normal.mt-1(style="font-size: .7rem;")
             | ver. #{coordinatorVersion}
-            if user && updates.coordinatorUpdate
+            if user && user.role !== 'admin' && updates.coordinatorUpdate
               span.badge.text-bg-warning.ms-1(
                 data-bs-toggle="tooltip"
                 data-bs-placement="bottom"
-                data-bs-title="Update the Coordinator by hand on its host: thub-admin self-update"
+                data-bs-title="An admin can update the Coordinator from the navbar"
               )= `v${updates.coordinatorUpdate} available`
         button.navbar-toggler(type="button" data-bs-toggle="collapse" data-bs-target="#nav")
           span.navbar-toggler-icon
@@ -37,6 +37,27 @@ html(lang="en" data-bs-theme=(user && user.theme) || "auto")
                 li.nav-item
                   a.nav-link(href="/admin/agents" class=active === 'agents' ? 'active' : '') Agents
           ul.navbar-nav
+            if user && user.role === 'admin' && updates.coordinatorUpdate
+              li.nav-item.d-flex.align-items-center.me-3
+                if updates.coordinatorPending
+                  button.btn.btn-sm.btn-warning(type="button" disabled)
+                    span.spinner-border.spinner-border-sm.me-1(aria-hidden="true")
+                    = `Updating app to ${updates.coordinatorPending}…`
+                else
+                  form(
+                    method="post"
+                    action="/updates/coordinator"
+                    onsubmit=`return confirm('Update the Coordinator to v${updates.coordinatorUpdate}? It restarts, and the dashboard and API are briefly unavailable.')`
+                  )
+                    input(type="hidden" name="returnTo" value=currentPath)
+                    button.btn.btn-sm.btn-warning(
+                      type="submit"
+                      data-bs-toggle="tooltip"
+                      data-bs-placement="bottom"
+                      data-bs-title=`Installed v${coordinatorVersion} — installs v${updates.coordinatorUpdate} and restarts the Coordinator`
+                    )
+                      i.bi.bi-cloud-download.me-1
+                      = `Update app to ${updates.coordinatorUpdate}`
             li.nav-item.d-flex.align-items-center.me-3
               button#theme-toggle.btn.btn-sm.btn-outline-secondary(
                 type="button"