@andrian.yablonskyy/thub-coordinator 1.0.4 → 1.0.6

package/README.md

@@ -7,10 +7,25 @@ See the [main TestHub repo](https://github.com/andrianyablonskyy/thub) for the f
 ## Install
 
 ```bash
-npm install -g @andrian.yablonskyy/thub-coordinator
+sudo npm i -g @andrian.yablonskyy/thub-coordinator
 ```
 
-This gives you two global commands: `thub-coordinator` (the server itself) and `thub-admin` (the local operator CLI, below). Or clone this repo directly and run it from source (see below).
+This gives you two global commands: `thub-coordinator` (the server itself) and `thub-admin` (the local operator CLI, below), and sets up everything needed to run it:
+
+- `~/.config/thub/coordinator.json` with every default option (see Configuration below), if it doesn't exist yet.
+- `~/var/lib/thub` (the `dataDir`: SQLite DB, uploaded artifacts, avatars) with its `artifacts/`, `avatars/` and `work/` subdirectories.
+- On Linux as root: `/etc/systemd/system/thub-coordinator.service`, enabled and started, so the Coordinator runs now and on every boot. A re-install/upgrade restarts it on the new code.
+
+Under `sudo`, `~` means the home of the user who ran `sudo` (`SUDO_USER`), not `/root`. That user owns the config and data and the service runs as them. Without root the config and directories are still created; the systemd step is skipped.
+
+```bash
+sudo systemctl status thub-coordinator
+journalctl -u thub-coordinator -f
+# after editing ~/.config/thub/coordinator.json:
+sudo systemctl restart thub-coordinator
+```
+
+Or clone this repo directly and run it from source (see below).
 
 ## Configuration
 
@@ -33,17 +48,19 @@ 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. Individual `THUB_LISTEN` / `THUB_PUBLIC_URL` / `THUB_DATA_DIR` / `THUB_SESSION_SECRET` / `THUB_CLIENT_JOIN_KEY` env vars override whatever the file set.
 
-`npm install -g` creates `~/.config/thub/coordinator.json` for you if it doesn't already exist, with a home-anchored `dataDir` and a freshly generated random `sessionSecret` (not the placeholder above) — a re-install never overwrites it or regenerates the secret. Set `publicUrl` and `clientJoinKey` yourself before relying on auto-registration.
+`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
 
 ```bash
 # First run: no admin_users row exists yet, so either set a bootstrap
-# password (creates user "admin") or use thub-admin afterwards.
-THUB_COORDINATOR_CONFIG=/etc/thub/coordinator.json \
+# password (creates user "admin") or use thub-admin afterwards. Reads
+# ~/.config/thub/coordinator.json; point THUB_COORDINATOR_CONFIG at another
+# file only if it exists — a missing one is an error, not a fallback.
 THUB_BOOTSTRAP_ADMIN_PASSWORD=correct-horse-battery-staple \
 thub-coordinator
 # -> Reset password for admin user "admin" from THUB_BOOTSTRAP_ADMIN_PASSWORD
+# -> Config: /home/you/.config/thub/coordinator.json; data: /home/you/var/lib/thub
 # -> TestHub Coordinator listening on http://127.0.0.1:8080
 ```
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "thub-admin": "./bin/thub-admin.js",
     "thub-coordinator": "./src/server.js"
@@ -11,7 +14,7 @@
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
     "test": "node --test test/*.test.js",
-    "postinstall": "node scripts/install-default-config.js",
+    "postinstall": "node scripts/ensure-native-deps.js && node scripts/install-default-config.js && node scripts/install-systemd-unit.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },

package/scripts/ensure-native-deps.js

@@ -0,0 +1,85 @@
+/**
+ * @file        scripts/ensure-native-deps.js
+ * @description npm postinstall: makes sure better-sqlite3's native addon loads under the Node.js
+ *              running this install, rebuilding it in place if not
+ *
+ * @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 path = require('node:path'),
+  { execFileSync, spawnSync } = require('node:child_process'),
+  { isGlobalInstall } = require('./install-target'),
+
+  PKG_DIR = path.join(__dirname, '..');
+
+// Checked in a child process: once a mismatched addon has been dlopen'ed,
+// this process keeps the old image mapped, so an in-process retry after
+// the rebuild would still see the stale one.
+function loads(){
+  const res = spawnSync(process.execPath, ['-e', 'new (require(\'better-sqlite3\'))(\':memory:\').close()'], {
+    cwd: PKG_DIR,
+    encoding: 'utf8'
+  });
+  if (res.status === 0){
+    return true;
+  }
+  if (/ERR_DLOPEN_FAILED|NODE_MODULE_VERSION/.test(res.stderr)){
+    return false;
+  }
+  throw new Error(res.stderr.trim().split('\n').find((l) => /Error/.test(l)) || `exit ${res.status}`);
+}
+
+// Runs better-sqlite3's own install script (prebuild-install, falling back
+// to node-gyp) in its own directory. Not `npm rebuild`: under `npm i -g`
+// this script inherits npm_config_global=true, which points a nested
+// `npm rebuild` at the global prefix instead of this package, where it
+// "succeeds" without touching the addon at all.
+function rebuild(){
+  const dir = path.dirname(require.resolve('better-sqlite3/package.json', { paths: [PKG_DIR] })),
+    npmCli = process.env.npm_execpath,
+    [cmd, args] = npmCli ? [process.execPath, [npmCli]] : ['npm', []];
+  execFileSync(cmd, [...args, 'run-script', 'install'], {
+    cwd: dir,
+    stdio: 'inherit',
+    env: { ...process.env, npm_config_global: 'false' }
+  });
+}
+
+// Re-running `npm i -g` for an already-installed version after a Node
+// major upgrade leaves unchanged dependencies alone — including
+// better-sqlite3's addon, still built for the old Node ABI — so the server
+// then dies with NODE_MODULE_VERSION mismatch at startup. Rebuild it here
+// with the same node/npm that's running this install. Best-effort: never
+// fails the install itself.
+function main(){
+  if (!isGlobalInstall()){
+    return;
+  }
+  try {
+    if (loads()){
+      return;
+    }
+    console.log(`thub-coordinator: rebuilding better-sqlite3 for Node.js ${process.version} (ABI ${process.versions.modules})`);
+    rebuild();
+    if (!loads()){
+      throw new Error('still fails to load after rebuild');
+    }
+    console.log('thub-coordinator: better-sqlite3 rebuilt');
+  }
+  catch (err){
+    console.warn(
+      `thub-coordinator: better-sqlite3 doesn't load under ${process.execPath} (${process.version}): ${err.message}\n` +
+        `Rebuild it manually: cd ${PKG_DIR} && sudo env "PATH=$PATH" npm rebuild better-sqlite3`
+    );
+  }
+}
+
+main();

package/scripts/install-default-config.js

@@ -1,9 +1,9 @@
 /**
  * @file        scripts/install-default-config.js
- * @description npm postinstall: creates ~/.config/thub/coordinator.json on a real global install,
- *              if it doesn't already exist, with a freshly generated sessionSecret rather than a
- *              shared placeholder — so every real installation isn't using the same known secret
- *              for its session cookies and artifact-download HMACs (README §12, §13)
+ * @description npm postinstall: on a real global install, creates the Coordinator's directory layout
+ *              (~/.config/thub, ~/var/lib/thub and its artifacts/avatars/work subdirs) and, if it
+ *              doesn't already exist, ~/.config/thub/coordinator.json with every default option and
+ *              a freshly generated sessionSecret (README §12, §13)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -17,57 +17,82 @@
 'use strict';
 
 const fs = require('node:fs'),
-  os = require('node:os'),
   path = require('node:path'),
   crypto = require('node:crypto'),
+  { DEFAULTS } = require('../src/config'),
+  { isGlobalInstall, isRoot, resolveTargetUser, targetPaths } = require('./install-target');
 
-  CONFIG_PATH = path.join(os.homedir(), '.config', 'thub', 'coordinator.json');
-
-// npm only sets this for an actual `npm install -g` — absent for a plain
-// local/workspace install (e.g. this monorepo's own `npm install`).
-function isGlobalInstall(){
-  return process.env.npm_config_global === 'true';
-}
-
-// Deliberately minimal, not a copy of the bundled config.json (which uses
-// a relative dataDir and a fixed sessionSecret for zero-setup `npm run
-// coordinator` in the monorepo — fine there since it's never a real
-// deployment). loadConfig()'s own DEFAULTS already cover everything else
-// (listen, publicUrl, heartbeat/scheduler/jobs/retention/artifacts), so
-// only what genuinely needs to differ for a real standalone install goes
-// here:
-//   - dataDir: home-anchored, not cwd-relative — a real install shouldn't
-//     silently get a different data directory depending on which
-//     directory you happened to launch thub-coordinator from.
-//   - sessionSecret: freshly random per install. The code's own default
-//     ("dev-only-change-me") is fine for local dev but would otherwise
-//     mean every real installation nobody got around to changing shares
-//     the exact same session-signing key.
-//   - clientJoinKey stays unset (null, the code's own default) — auto-
-//     registration is opt-in, and there's nothing sensible to
-//     auto-generate here since it also has to be copied to every Client.
-function defaultContent(){
+// Every option loadConfig() knows, written out so the file documents what
+// can be changed — not a copy of the bundled config.json (which uses a
+// relative dataDir and a fixed sessionSecret for zero-setup `npm run
+// coordinator` in the monorepo). What differs from DEFAULTS:
+//   - dataDir: home-anchored (~/var/lib/thub), not cwd-relative — a real
+//     install shouldn't get a different data directory depending on which
+//     directory thub-coordinator happened to be launched from.
+//   - sessionSecret: freshly random per install, never the shared
+//     "dev-only-change-me" default.
+//   - clientJoinKey stays null (auto-registration is opt-in, and it also
+//     has to be copied to every Client, so there's nothing to generate).
+function defaultContent(paths){
   return {
-    dataDir: path.join(os.homedir(), '.local', 'share', 'thub'),
+    ...DEFAULTS,
+    dataDir: paths.defaultDataDir,
     sessionSecret: crypto.randomBytes(32).toString('hex')
   };
 }
 
+// Under `sudo npm i -g` everything is created by root in another user's
+// home — hand it over, or the Coordinator (running as that user, see
+// install-systemd-unit.js) couldn't read its config or write its data.
+function chownToUser(p, user){
+  if (isRoot() && user.uid !== 0){
+    fs.chownSync(p, user.uid, user.gid);
+  }
+}
+
+// Creates `dir` and chowns every directory this call created along the
+// way (e.g. ~/.config, ~/var, ~/var/lib when they didn't exist yet),
+// plus `dir` itself.
+function mkdirOwned(dir, user){
+  const firstCreated = fs.mkdirSync(dir, { recursive: true });
+  if (firstCreated){
+    const rel = path.relative(firstCreated, dir).split(path.sep).filter(Boolean);
+    let current = firstCreated;
+    chownToUser(current, user);
+    for (const part of rel){
+      current = path.join(current, part);
+      chownToUser(current, user);
+    }
+  }
+  else {
+    chownToUser(dir, user);
+  }
+}
+
 // Best-effort and never fails the `npm install` itself. Never overwrites
-// an existing file — a re-install/upgrade must not clobber whatever the
-// user already configured, and must never regenerate sessionSecret out
+// an existing config file — a re-install/upgrade must not clobber whatever
+// the user already configured, and must never regenerate sessionSecret out
 // from under a running deployment (that would invalidate every session).
 function main(){
-  if (!isGlobalInstall() || fs.existsSync(CONFIG_PATH)){
+  if (!isGlobalInstall()){
     return;
   }
+  const user = resolveTargetUser(),
+    paths = targetPaths(user);
   try {
-    fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-    fs.writeFileSync(CONFIG_PATH, JSON.stringify(defaultContent(), null, 2) + '\n', { mode: 0o600 });
-    console.log(`thub-coordinator: created ${CONFIG_PATH} with a freshly generated sessionSecret`);
+    mkdirOwned(paths.configDir, user);
+    for (const dir of [paths.dataDir, ...paths.dataSubdirs]){
+      mkdirOwned(dir, user);
+    }
+    if (!fs.existsSync(paths.configPath)){
+      fs.writeFileSync(paths.configPath, JSON.stringify(defaultContent(paths), null, 2) + '\n', { mode: 0o600 });
+      chownToUser(paths.configPath, user);
+      console.log(`thub-coordinator: created ${paths.configPath} with a freshly generated sessionSecret`);
+    }
+    console.log(`thub-coordinator: data directory is ${paths.dataDir}`);
   }
   catch (err){
-    console.warn(`thub-coordinator: could not create ${CONFIG_PATH} automatically (${err.message}).`);
+    console.warn(`thub-coordinator: could not create ${paths.configPath} / ${paths.dataDir} automatically (${err.message}).`);
   }
 }
 

package/scripts/install-systemd-unit.js

@@ -0,0 +1,79 @@
+/**
+ * @file        scripts/install-systemd-unit.js
+ * @description npm postinstall: installs systemd/thub-coordinator.service to /etc/systemd/system on
+ *              Linux when root, rendered for the user who ran `sudo npm i -g` and this install's real
+ *              node/server.js paths, then enables and (re)starts it (README §13.1)
+ *
+ * @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'),
+  path = require('node:path'),
+  { execFileSync } = require('node:child_process'),
+  { isGlobalInstall, isRoot, resolveTargetUser, targetPaths } = require('./install-target'),
+
+  UNIT_NAME = 'thub-coordinator.service',
+  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';
+
+// 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.
+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}`);
+}
+
+// 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
+// new code immediately.
+function main(){
+  if (process.platform !== 'linux' || !isGlobalInstall()){
+    return;
+  }
+  if (!isRoot()){
+    console.log(`\nthub-coordinator: skipping systemd service install (not root). To install it, run:\n  ${MANUAL_HINT}\n`);
+    return;
+  }
+
+  const user = resolveTargetUser();
+  let step = 'write';
+  try {
+    fs.writeFileSync(UNIT_DEST, renderUnit(user, targetPaths(user)));
+    step = 'daemon-reload';
+    execFileSync('systemctl', ['daemon-reload'], { stdio: 'ignore' });
+    step = 'enable';
+    execFileSync('systemctl', ['enable', UNIT_NAME], { stdio: 'ignore' });
+    step = 'restart';
+    execFileSync('systemctl', ['restart', UNIT_NAME], { stdio: 'ignore' });
+    console.log(`thub-coordinator: installed and started ${UNIT_DEST} (runs as ${user.name}; logs: journalctl -u ${UNIT_NAME})`);
+  }
+  catch (err){
+    if (step === 'write'){
+      console.warn(`thub-coordinator: could not install ${UNIT_DEST} (${err.message}).`);
+    }
+    else {
+      console.warn(
+        `thub-coordinator: installed ${UNIT_DEST} but 'systemctl ${step}' failed (${err.message}).\n` +
+          `Finish it yourself: sudo systemctl daemon-reload && sudo systemctl enable --now ${UNIT_NAME}`
+      );
+    }
+  }
+}
+
+main();

package/scripts/install-target.js

@@ -0,0 +1,83 @@
+/**
+ * @file        scripts/install-target.js
+ * @description Shared by the npm postinstall scripts: resolves which user a global install is for
+ *              (the one who ran `sudo npm i -g`, not root) and the paths it gets (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'),
+  os = require('node:os'),
+  path = require('node:path'),
+  { execFileSync } = require('node:child_process');
+
+// npm only sets this for an actual `npm install -g` — absent for a plain
+// local/workspace install (e.g. this monorepo's own `npm install`).
+function isGlobalInstall(){
+  return process.env.npm_config_global === 'true';
+}
+
+function isRoot(){
+  return typeof process.getuid === 'function' && process.getuid() === 0;
+}
+
+// Under `sudo npm i -g`, npm runs postinstall as root with HOME=/root, but
+// "~" in README §13 means the person who ran sudo — SUDO_USER. Their home
+// comes from the passwd database, since HOME has already been reset.
+function lookupUser(name){
+  const entry = execFileSync('getent', ['passwd', name], { encoding: 'utf8' }).trim().split(':');
+  return { name: entry[0], uid: Number(entry[2]), gid: Number(entry[3]), home: entry[5] };
+}
+
+function resolveTargetUser(){
+  const sudoUser = process.env.SUDO_USER;
+  if (isRoot() && sudoUser && sudoUser !== 'root' && process.platform === 'linux'){
+    try {
+      return lookupUser(sudoUser);
+    }
+    catch {
+      // fall through to the current user
+    }
+  }
+  const info = os.userInfo();
+  return { name: info.username, uid: info.uid, gid: info.gid, home: os.homedir() };
+}
+
+// Default layout (README §13): config under ~/.config/thub, runtime data
+// (SQLite DB, uploaded artifacts, avatars, work files) under ~/var/lib/thub.
+// An existing coordinator.json's own dataDir wins over the default, so a
+// re-install prepares (and the systemd unit allows writes to) the
+// directory the Coordinator will really use.
+function targetPaths(user){
+  const configDir = path.join(user.home, '.config', 'thub'),
+    configPath = path.join(configDir, 'coordinator.json'),
+    defaultDataDir = path.join(user.home, 'var', 'lib', 'thub'),
+    dataDir = configuredDataDir(configPath) || defaultDataDir;
+  return {
+    configDir,
+    configPath,
+    defaultDataDir,
+    dataDir,
+    dataSubdirs: ['artifacts', 'avatars', 'work'].map((d) => path.join(dataDir, d))
+  };
+}
+
+function configuredDataDir(configPath){
+  try {
+    const dataDir = JSON.parse(fs.readFileSync(configPath, 'utf8'))?.dataDir;
+    return typeof dataDir === 'string' && path.isAbsolute(dataDir) ? dataDir : null;
+  }
+  catch {
+    return null;
+  }
+}
+
+module.exports = { isGlobalInstall, isRoot, resolveTargetUser, targetPaths };

package/src/config.js

@@ -72,6 +72,13 @@ const USER_CONFIG_PATH = path.join(os.homedir(), '.config', 'thub', 'coordinator
   PACKAGE_DEFAULT_CONFIG_PATH = path.join(__dirname, '..', 'config.json');
 
 function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
+  // An explicitly named config that doesn't exist is an error, not a cue to
+  // fall back: silently running on the bundled dev config instead (relative
+  // dataDir, placeholder secrets) only surfaces later as a confusing
+  // failure far from the real cause, e.g. SQLITE_CANTOPEN.
+  if (configPath && !fs.existsSync(configPath)){
+    throw new Error(`Coordinator config not found: ${configPath} (from THUB_COORDINATOR_CONFIG)`);
+  }
   const candidate = [configPath, USER_CONFIG_PATH, PACKAGE_DEFAULT_CONFIG_PATH].find(
       (p) => p && fs.existsSync(p)
     ),
@@ -95,6 +102,9 @@ function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
     config.clientJoinKey = process.env.THUB_CLIENT_JOIN_KEY;
   }
 
+  config.configPath = candidate || null;
+  config.dataDir = path.resolve(config.dataDir);
+
   const [host, port] = config.listen.split(':');
   config.host = host;
   config.port = Number(port);
@@ -103,11 +113,27 @@ function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
   config.workDir = path.join(config.dataDir, 'work');
   config.avatarsDir = path.join(config.dataDir, 'avatars');
 
-  fs.mkdirSync(config.dataDir, { recursive: true });
-  fs.mkdirSync(config.artifactsDir, { recursive: true });
-  fs.mkdirSync(config.avatarsDir, { recursive: true });
+  ensureWritableDir(config.dataDir, config.configPath);
+  ensureWritableDir(config.artifactsDir, config.configPath);
+  ensureWritableDir(config.avatarsDir, config.configPath);
 
   return config;
 }
 
+// SQLite opens thub.db (plus its -wal/-shm files) inside dataDir, 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){
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.accessSync(dir, fs.constants.W_OK);
+  }
+  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.`
+    );
+  }
+}
+
 module.exports = { loadConfig, DEFAULTS };

package/src/db/index.js

@@ -18,7 +18,7 @@ const fs = require('node:fs'),
   Database = require('better-sqlite3');
 
 function openDb(dbPath){
-  const db = new Database(dbPath);
+  const db = openDatabase(dbPath);
   db.pragma('journal_mode = WAL');
   db.pragma('synchronous = NORMAL');
   db.pragma('foreign_keys = ON');
@@ -26,6 +26,32 @@ function openDb(dbPath){
   return db;
 }
 
+// better-sqlite3 is a native addon built for one Node.js ABI at install
+// time; after a Node major upgrade it must be rebuilt. Without this, the
+// only hint is a raw NODE_MODULE_VERSION mismatch from deep in bindings.js.
+// The rebuild command keeps the caller's PATH under sudo, since sudo's own
+// secure_path often finds a different (older) node than the user's shell
+// does — rebuilding with that one just reproduces the same mismatch.
+function openDatabase(dbPath){
+  try {
+    return new Database(dbPath);
+  }
+  catch (err){
+    if (err.code === 'ERR_DLOPEN_FAILED'){
+      const builtFor = err.message.match(/NODE_MODULE_VERSION (\d+)/)?.[1],
+        pkgDir = path.join(__dirname, '..', '..');
+      throw new Error(
+        `better-sqlite3 was built for a different Node.js ABI (${builtFor || 'unknown'}) than this one: ` +
+          `${process.version}, ABI ${process.versions.modules}, at ${process.execPath}.\n` +
+          `Rebuild it with this same node: cd ${pkgDir} && sudo env "PATH=$PATH" npm rebuild better-sqlite3\n` +
+          'If `sudo node -v` and `node -v` differ, sudo was using another Node.js for earlier installs.',
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+}
+
 function migrate(db){
   db.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (

package/src/server.js

@@ -145,6 +145,7 @@ function start(configPath){
   ensureBootstrapAdmin(services);
 
   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}`);
   });
 

package/systemd/thub-coordinator.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=TestHub Coordinator
+After=network-online.target
+Wants=network-online.target
+
+# 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.
+[Service]
+Type=simple
+User=thub
+Group=thub
+Environment=THUB_COORDINATOR_CONFIG=/var/lib/thub/.config/thub/coordinator.json
+ExecStart=/usr/bin/node /usr/lib/node_modules/@andrian.yablonskyy/thub-coordinator/src/server.js
+Restart=always
+RestartSec=2
+NoNewPrivileges=yes
+ProtectSystem=strict
+ReadWritePaths=/var/lib/thub/var/lib/thub
+
+[Install]
+WantedBy=multi-user.target