@bongos/core 1.19.101 → 1.19.102

package/scripts/gds/dev-lib.js

@@ -112,6 +112,7 @@ function resolveRunParams({
   env = process.env,
   userInfo = os.userInfo,
   argv = [],
+  mode = null,
 } = {}) {
   const facts = loadBrandingFacts({ instanceRoot, coreRoot, f });
   const modules = readJsonSafe(path.join(instanceRoot, 'config', 'modules.json'), f) || {};
@@ -119,6 +120,9 @@ function resolveRunParams({
 
   const portOverride = argFrom(argv, '--port');
   const dbOverride = argFrom(argv, '--db');
+  // 'server' = a real host (systemd-supervised, no auto-login, outward health
+  // probe); 'local' = the ADR 0149 laptop path. Same six steps either way.
+  const runMode = mode || (argv.includes('--server') ? 'server' : 'local');
 
   const port = portOverride ? parsePort(`http://x:${portOverride}`, parsePort(facts.publicOrigin)) : parsePort(facts.publicOrigin);
   const dbName = deriveDbName({ brandingDbName: facts.brandingDbName, instanceRoot, override: dbOverride });
@@ -126,16 +130,19 @@ function resolveRunParams({
   let pgUser = env.PGUSER;
   if (!pgUser) { try { pgUser = userInfo().username; } catch { pgUser = undefined; } }
 
+  const publicOrigin = facts.publicOrigin.replace(/\/+$/, '');
+
   return {
     instanceRoot,
     coreRoot,
+    mode: runMode,
     port,
-    host: HOST,
+    host: deriveBindHost({ publicOrigin, mode: runMode, override: argFrom(argv, '--bind') || env.HOST }),
     dbName,
     pgHost: env.PGHOST || 'localhost',
     pgUser,
     pgPassword: env.PGPASSWORD || undefined,
-    publicOrigin: facts.publicOrigin.replace(/\/+$/, ''),
+    publicOrigin,
     firstAdmin: facts.firstAdmin,
     envPrefix: facts.envPrefix,
     configDir: facts.configDir,
@@ -257,7 +264,7 @@ function stop(params, deps = {}) {
 // /healthz (needs no DB); authConfigured comes from /api/gds/healthz.
 async function health(params, deps = {}) {
   const fetchImpl = deps.fetchImpl || fetch;
-  const base = `http://${HOST}:${params.port}`;
+  const base = `http://${probeHost(params)}:${params.port}`;
   const timeout = deps.healthTimeoutMs || 4000;
   let up = false;
   try {
@@ -300,10 +307,209 @@ function depsInstallPlan({ instanceRoot, f = fs } = {}) {
     : { needed: true, cmd: 'install', args: ['install'] };
 }
 
+// ===================== SERVER MODE (task 1002398, ADR 0162) =====================
+// The SAME boot path — deps -> Postgres -> createdb -> migrate -> env -> server ->
+// health — retargeted at a real host. Four decisions differ from local, and every
+// one of them is a pure function here so tests/dev_lib.mjs can prove it without a
+// host: where to bind, how to start Postgres, how the DB role gets bootstrapped
+// under peer auth, and what supervises the process.
+
+// `bongos serve stop` arrives as argv ['--server','stop'] once bin/bongos.js
+// prefixes the mode flag, and `--port 3006 status` puts a VALUE where the old
+// `argv[0]` scan looked for the subcommand. Resolve the subcommand by skipping
+// flags and the values they consume, so flag order never changes the verb.
+const VALUE_FLAGS = new Set(['--port', '--db', '--bind', '--user', '--env-file']);
+
+function parseSub(argv = [], fallback = 'up') {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') break;
+    if (a.startsWith('-')) { if (VALUE_FLAGS.has(a)) i++; continue; }
+    return a;
+  }
+  return fallback;
+}
+
+// Where the server binds. Local is always loopback. On a real host the right
+// answer is derivable from the origin the instance is CONFIGURED for, so an
+// operator never has to reason about it:
+//   https://…            -> a TLS-terminating proxy fronts us  -> 127.0.0.1
+//   http://localhost:…   -> a local-shaped origin on a host     -> 127.0.0.1
+//   http://<public>:…    -> nothing in front of us yet          -> 0.0.0.0
+// An explicit --bind (or HOST in the environment) still wins over all of it.
+function deriveBindHost({ publicOrigin, mode = 'local', override } = {}) {
+  if (override) return String(override);
+  if (mode !== 'server') return HOST;
+  let u;
+  try { u = new URL(String(publicOrigin)); } catch { return HOST; }
+  if (u.protocol === 'https:') return HOST;
+  if (u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '::1') return HOST;
+  return '0.0.0.0';
+}
+
+// The address to PROBE for health. Binding 0.0.0.0 still answers on loopback;
+// binding one specific address does not, so probe whatever we actually bound.
+function probeHost(params = {}) {
+  const h = params.host || HOST;
+  return (h === '0.0.0.0' || h === '::') ? HOST : h;
+}
+
+function serviceName(params) { return `bongos-${sanitizeDbName(params.dbName) || 'instance'}`; }
+function unitPath(params, { systemdDir = '/etc/systemd/system' } = {}) {
+  return path.posix.join(systemdDir, `${serviceName(params)}.service`);
+}
+// Secrets (PGPASSWORD, GitHub OAuth creds) belong in a root-owned 0600 file the
+// unit references, NEVER in Environment= lines — `systemctl show` and the journal
+// expose those to any user on the box.
+function envFilePath(params, { etcBase = '/etc/bongos' } = {}) {
+  return path.posix.join(etcBase, `${serviceName(params)}.env`);
+}
+
+// The unit's Environment= set: ONLY the keys the boot path resolves. Deliberately
+// not buildEnv() — that spreads the caller's whole environment, which under
+// systemd would bake a builder's shell (tokens included) into a root-owned file.
+function unitEnvironment(params) {
+  const pairs = [
+    ['PORT', String(params.port)],
+    ['HOST', params.host],
+    ['PGHOST', params.pgHost],
+    ['PGDATABASE', params.dbName],
+    ['NODE_ENV', 'production'],
+  ];
+  if (params.pgUser) pairs.push(['PGUSER', params.pgUser]);
+  if (params.gdsOnly) pairs.push(['MEDUSA_GDS_ONLY', '1']);
+  pairs.push([`${params.envPrefix}_INSTANCE_ROOT`, params.instanceRoot]);
+  return pairs;
+}
+
+// systemd accepts Environment="K=v with spaces"; quote every value so a path with
+// a space (or a quote) can't split the assignment.
+function quoteUnitValue(v) { return `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`; }
+
+function renderSystemdUnit(params, { nodePath = process.execPath, user, group, envFile } = {}) {
+  const env = unitEnvironment(params).map(([k, v]) => `Environment=${quoteUnitValue(`${k}=${v}`)}`);
+  const lines = [
+    '[Unit]',
+    `Description=Cloud Bongos instance ${params.dbName} (bongos serve)`,
+    'Wants=network-online.target',
+    // postgresql.service may not exist (managed/remote DB) — After= on an absent
+    // unit is a no-op, so this is safe either way and orders us correctly when it
+    // IS local. No Requires=: a remote-DB host must still boot.
+    'After=network-online.target postgresql.service',
+    '',
+    '[Service]',
+    'Type=simple',
+    `WorkingDirectory=${params.instanceRoot}`,
+    `ExecStart=${nodePath} ${serverEntry(params)}`,
+    ...env,
+    `EnvironmentFile=-${envFile || envFilePath(params)}`,
+    // Survive a crash AND a reboot — the whole point of moving off the pid file.
+    'Restart=always',
+    'RestartSec=3',
+    'NoNewPrivileges=yes',
+    'StandardOutput=journal',
+    'StandardError=journal',
+  ];
+  if (user) lines.push(`User=${user}`);
+  if (group) lines.push(`Group=${group}`);
+  lines.push('', '[Install]', 'WantedBy=multi-user.target', '');
+  return lines.join('\n');
+}
+
+// Can this host supervise with systemd, and do we need sudo to install the unit?
+function systemdPlan({ platform = process.platform, has = () => false, isRoot = false } = {}) {
+  if (platform !== 'linux') return { available: false, reason: `systemd is linux-only (this host is ${platform})` };
+  if (!has('systemctl')) return { available: false, reason: 'systemctl is not on PATH' };
+  if (isRoot) return { available: true, sudo: false };
+  if (!has('sudo')) return { available: false, reason: 'installing a unit needs root, and sudo is not on PATH' };
+  return { available: true, sudo: true };
+}
+
+// Prefix a step with non-interactive sudo when we are not already root. `sudo -n`
+// never prompts: on a host without passwordless sudo it fails fast with a clear
+// error instead of hanging a deploy on a hidden password prompt.
+function withSudo(step, { isRoot = false, sudo = true } = {}) {
+  if (isRoot || !sudo) return step;
+  return { ...step, cmd: 'sudo', args: ['-n', step.cmd, ...step.args] };
+}
+
+// Ordered candidates for "start Postgres", best-first for the platform. dev.js
+// tries each until pg_isready passes. Homebrew keeps its own branch there (the
+// formula name has to be discovered at runtime); everything else is decided here.
+function pgStartPlan({ platform = process.platform, has = () => false, env = process.env, isRoot = false } = {}) {
+  const out = [];
+  if (platform === 'darwin' && has('brew')) out.push({ cmd: 'brew', args: ['services', 'start'], needsFormula: true, label: 'Homebrew' });
+  if (platform === 'linux') {
+    if (has('systemctl')) out.push(withSudo({ cmd: 'systemctl', args: ['start', 'postgresql'], label: 'systemd' }, { isRoot }));
+    else if (has('service')) out.push(withSudo({ cmd: 'service', args: ['postgresql', 'start'], label: 'service' }, { isRoot }));
+  }
+  if (has('pg_ctl') && env.PGDATA) out.push({ cmd: 'pg_ctl', args: ['start', '-w', '-D', env.PGDATA], label: 'pg_ctl' });
+  return out;
+}
+
+// Postgres identifiers are case-folded unless quoted, and a role name reaches the
+// server as SQL text — quote it properly and refuse anything that isn't a plain
+// identifier rather than interpolating a surprise into a CREATE ROLE.
+const SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function quoteIdent(s) { return `"${String(s).replace(/"/g, '""')}"`; }
+
+// The fresh-Debian wall: `apt-get install postgresql` creates exactly ONE role,
+// `postgres`, reachable only by peer auth as the postgres OS user. A deploy user
+// running `createdb` gets 'role "deploy" does not exist' — which reads like a
+// broken install and is really just an unbootstrapped cluster. These two steps,
+// run as the postgres superuser, are the whole fix.
+function pgBootstrapPlan({ pgUser, dbName, isRoot = false, has = () => false } = {}) {
+  if (!pgUser || !SAFE_IDENT.test(pgUser)) return { ok: false, reason: `refusing to bootstrap an unsafe role name: ${pgUser || '(none)'}` };
+  if (!dbName || !SAFE_IDENT.test(dbName)) return { ok: false, reason: `refusing to bootstrap an unsafe database name: ${dbName || '(none)'}` };
+  // Reach the postgres superuser the way this host allows: `sudo -u postgres` for
+  // a normal deploy user (and for root when sudo exists), else `su postgres -c`
+  // when we are already root on a minimal image with no sudo installed.
+  let asPostgres;
+  if (has('sudo')) asPostgres = (cmd, args, label) => ({ cmd: 'sudo', args: ['-n', '-u', 'postgres', cmd, ...args], label });
+  else if (isRoot) asPostgres = (cmd, args, label) => ({ cmd: 'su', args: ['postgres', '-c', shellJoin([cmd, ...args])], label });
+  else return { ok: false, reason: 'bootstrapping the role needs the postgres superuser (root or sudo)' };
+
+  return {
+    ok: true,
+    steps: [
+      { ...asPostgres('psql', ['-v', 'ON_ERROR_STOP=1', '-tAc',
+        `SELECT 1 FROM pg_roles WHERE rolname='${pgUser}'`], 'check role'), id: 'check-role' },
+      { ...asPostgres('psql', ['-v', 'ON_ERROR_STOP=1', '-c',
+        `CREATE ROLE ${quoteIdent(pgUser)} LOGIN CREATEDB`], 'create role'), id: 'create-role' },
+      { ...asPostgres('createdb', ['-O', pgUser, dbName], 'create database'), id: 'create-db' },
+    ],
+  };
+}
+
+// Quote an argv into a single `su -c` string. Only ever fed argv this module
+// built from validated identifiers, but quote anyway — `su -c` is a shell.
+function shellJoin(argv) {
+  return argv.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${String(a).replace(/'/g, `'\\''`)}'`)).join(' ');
+}
+
+// Health as seen from OUTSIDE — does the origin the instance advertises actually
+// answer? On a server that also exercises DNS, the proxy, and TLS, which the
+// loopback probe cannot see. Advisory: DNS may legitimately not be wired yet.
+async function publicHealth(params, deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  const timeout = deps.healthTimeoutMs || 6000;
+  try {
+    const r = await fetchImpl(`${params.publicOrigin}/healthz`, { signal: AbortSignal.timeout(timeout) });
+    return { reachable: r.status < 500, status: r.status };
+  } catch (e) {
+    return { reachable: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
 module.exports = {
   HOST, DEFAULT_PORT, CORE_ROOT,
   readJsonSafe, loadBrandingFacts, parsePort, sanitizeDbName, deriveDbName,
   resolveRunParams, buildEnv, authWillWork, depsInstallPlan,
   slug, pidPath, logPath, readPid, pidAlive, isRunning, serverEntry,
   startDetached, stop, health, argFrom,
+  // server mode (task 1002398). withSudo/quoteIdent/shellJoin stay private —
+  // they are implementation details of the plans above, not a callable surface.
+  parseSub, deriveBindHost, probeHost, serviceName, unitPath, envFilePath,
+  unitEnvironment, renderSystemdUnit, systemdPlan, pgStartPlan,
+  pgBootstrapPlan, publicHealth,
 };

package/scripts/gds/dev.js

@@ -57,22 +57,36 @@ function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 function usage() {
-  console.log(`bongos dev — run THIS instance locally, in one command.
+  console.log(`bongos dev — run THIS instance, in one command.
 
 Usage:
   bongos dev [--foreground] [--no-login] [--skip-migrate] [--port <n>] [--db <name>]
   bongos dev stop        Stop the local server this launched
   bongos dev status      Show whether it's running, its URL, and sign-in state
 
+  bongos serve           Same boot path, on a REAL HOST (= bongos dev --server)
+  bongos serve stop      Stop + disable the service
+  bongos serve status    Service state, health, and whether the public origin answers
+
 What it does (idempotent — safe to re-run):
-  1. Make sure Postgres is running (starts it via Homebrew if it isn't)
-  2. Create this instance's database if it doesn't exist
-  3. Build/refresh its tables (migrations)
-  4. Start the server on the port in config/branding.json
-  5. Sign you in to this instance (unless --no-login)
+  1. Install dependencies if this checkout has none
+  2. Make sure Postgres is running (Homebrew on a Mac, systemd/service on a host)
+  3. Create this instance's database if it doesn't exist
+  4. Build/refresh its tables (migrations)
+  5. Start the server on the port in config/branding.json
+  6. Sign you in (local only — a host prints the command instead)
+
+What --server changes:
+  • supervision — a systemd unit (enabled at boot, restarts on failure) instead of
+    a pid file, falling back to the background process where systemd is absent
+  • bind address — 127.0.0.1 behind a TLS proxy (https origin), else 0.0.0.0
+  • it bootstraps the Postgres login role on a fresh cluster (peer auth)
+  • it checks the PUBLIC origin, not just loopback, and never opens a browser
+  Extra flags: --bind <addr>, --user <unix-user> (who the service runs as).
 
 Needs Postgres + Node >= 22 installed. macOS/Linux (uses bash for migrations;
-on Windows use WSL or the Docker path in docs/recipes/self-host.md).`);
+on Windows use WSL or the Docker path in docs/recipes/self-host.md).
+Server walkthrough: docs/recipes/server-bring-up.md`);
 }
 
 // psql/createdb take -h/-U only when we have them; libpq fills the rest.
@@ -86,21 +100,31 @@ function pgReady(params) {
   return run('pg_isready', [...pgArgs(params), '-q']).status === 0;
 }
 
-// Best-effort: start a Homebrew-managed Postgres, then poll until it accepts
-// connections. Returns true if ready, false if we couldn't bring it up.
+// Am I root? (Only meaningful on POSIX; Windows has no getuid.)
+function isRoot() { return typeof process.getuid === 'function' && process.getuid() === 0; }
+
+// Best-effort: start whatever service manager owns Postgres on this platform
+// (Homebrew on a Mac, systemd/service on a Linux host, pg_ctl with PGDATA
+// anywhere), then poll until it accepts connections. The candidate list + sudo
+// prefixing are decided by dev-lib.pgStartPlan; this just executes them in order.
 function ensurePostgres(params) {
   if (pgReady(params)) { ok('Postgres is running'); return true; }
   info('Postgres is not running — trying to start it…');
-  if (has('brew')) {
-    const formulae = run('brew', ['list', '--formula']).stdout
-      .split(/\s+/).filter((x) => /^postgresql(@\d+)?$/.test(x))
-      .sort().reverse();
-    const target = formulae[0] || 'postgresql@16';
-    run('brew', ['services', 'start', target], { stdio: 'ignore' });
-  } else if (has('pg_ctl') && process.env.PGDATA) {
-    run('pg_ctl', ['start', '-w', '-D', process.env.PGDATA], { stdio: 'ignore' });
+  for (const step of dev.pgStartPlan({ has, isRoot: isRoot() })) {
+    let args = step.args;
+    if (step.needsFormula) {
+      // Homebrew's formula name has to be discovered at runtime (postgresql@16,
+      // @17, …) — the only start candidate that isn't statically known.
+      const formulae = run('brew', ['list', '--formula']).stdout
+        .split(/\s+/).filter((x) => /^postgresql(@\d+)?$/.test(x))
+        .sort().reverse();
+      args = [...step.args, formulae[0] || 'postgresql@16'];
+    }
+    run(step.cmd, args, { stdio: 'ignore' });
+    if (pgReady(params)) { ok(`Postgres started (${step.label})`); return true; }
   }
-  // Poll for readiness (~15s). pg_isready is cheap; pause between probes.
+  // Poll for readiness (~15s) — a service manager returns before the cluster is
+  // actually accepting connections. pg_isready is cheap; pause between probes.
   for (let i = 0; i < 15; i++) {
     if (pgReady(params)) { ok('Postgres started'); return true; }
     sleepSync(1000);
@@ -114,12 +138,44 @@ function dbExists(params) {
   return r.status === 0 && r.stdout.trim() === '1';
 }
 
+// A fresh `apt-get install postgresql` cluster has exactly one role — `postgres`,
+// peer-auth only — so a deploy user's createdb fails with 'role "deploy" does not
+// exist'. That reads like a broken install and is really an unbootstrapped
+// cluster. Create the login role (and the DB it owns) as the postgres superuser.
+function bootstrapRole(params) {
+  const plan = dev.pgBootstrapPlan({ pgUser: params.pgUser, dbName: params.dbName, isRoot: isRoot(), has });
+  if (!plan.ok) { warn(plan.reason); return false; }
+  info(`bootstrapping the Postgres role "${params.pgUser}" (first run on this host)…`);
+  const byId = Object.fromEntries(plan.steps.map((s) => [s.id, s]));
+
+  const check = byId['check-role'];
+  const already = run(check.cmd, check.args).stdout.trim() === '1';
+  if (!already) {
+    const mk = byId['create-role'];
+    const r = run(mk.cmd, mk.args);
+    if (r.status !== 0) { fail(`could not create the Postgres role "${params.pgUser}": ${tail(r.stderr, 2)}`); return false; }
+    ok(`created Postgres role "${params.pgUser}"`);
+  }
+  const mkdb = byId['create-db'];
+  const r = run(mkdb.cmd, mkdb.args);
+  if (r.status === 0 || /already exists/i.test(r.stderr)) { ok(`database "${params.dbName}" ready`); return true; }
+  fail(`could not create database "${params.dbName}" as the postgres superuser: ${tail(r.stderr, 2)}`);
+  return false;
+}
+
+// Does this createdb failure mean "the cluster was never bootstrapped for me"
+// (fixable, see bootstrapRole) rather than a genuine error?
+function needsRoleBootstrap(stderr) {
+  return /role .* does not exist|Peer authentication failed|password authentication failed|no password supplied/i.test(String(stderr || ''));
+}
+
 function createDb(params) {
   if (dbExists(params)) { ok(`database "${params.dbName}" exists`); return true; }
   const r = run('createdb', [...pgArgs(params), params.dbName]);
   if (r.status === 0) { ok(`created database "${params.dbName}"`); return true; }
   // A race or prior partial run may have created it; treat "already exists" as fine.
   if (/already exists/i.test(r.stderr)) { ok(`database "${params.dbName}" exists`); return true; }
+  if (needsRoleBootstrap(r.stderr) && process.platform === 'linux') return bootstrapRole(params);
   fail(`could not create database "${params.dbName}": ${tail(r.stderr, 2) || r.error}`);
   return false;
 }
@@ -152,6 +208,15 @@ function printOAuthGuidance(params) {
   console.log(`       Authorization callback URL: ${cb}`);
   console.log('       Then tick "Enable Device Flow" and Save (a separate save).');
   console.log('    2. Copy the Client ID; generate a client secret.');
+  if (params.mode === 'server') {
+    // On a host the server runs as a service user with its own (often empty) home,
+    // so the env file the unit already reads is the reliable place for creds.
+    console.log(`    3. Put both in ${dev.envFilePath(params)} (0600, root-owned):`);
+    console.log(`         ${params.envPrefix}_GITHUB_CLIENT_ID=…`);
+    console.log(`         ${params.envPrefix}_GITHUB_CLIENT_SECRET=…`);
+    console.log(`    4. systemctl restart ${dev.serviceName(params)}`);
+    return;
+  }
   console.log(`    3. Save both into ${credsPath} as:`);
   console.log('       { "client_id": "…", "client_secret": "…" }');
   console.log('    4. Re-run `bongos dev`.');
@@ -182,9 +247,124 @@ function loginNow(params) {
   return r.status === 0;
 }
 
+// ---- server mode: systemd supervision (task 1002398) ---------------------------
+// On a laptop a detached pid-file process is the right amount of machinery. On a
+// real host it is not: it dies on reboot, it has no restart policy, and its logs
+// are a file in /tmp. So server mode installs a systemd unit and lets the host's
+// own supervisor own the process — the pid-file path stays as the fallback for a
+// host without systemd (a container, a BSD, a non-root operator).
+
+function sudoWorks() { return run('sudo', ['-n', 'true']).status === 0; }
+
+// Write a root-owned file, directly when we are root and via `sudo tee` when not.
+function writeRootFile(target, contents, useSudo, mode = null) {
+  const dir = path.posix.dirname(target);
+  if (!useSudo) {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(target, contents, mode ? { mode } : undefined);
+      return { ok: true };
+    } catch (e) { return { ok: false, err: e.message }; }
+  }
+  const mk = run('sudo', ['-n', 'mkdir', '-p', dir]);
+  if (mk.status !== 0) return { ok: false, err: tail(mk.stderr, 2) };
+  const w = run('sudo', ['-n', 'tee', target], { input: contents, stdio: ['pipe', 'ignore', 'pipe'] });
+  if (w.status !== 0) return { ok: false, err: tail(w.stderr, 2) };
+  if (mode) run('sudo', ['-n', 'chmod', mode.toString(8).padStart(4, '0'), target]);
+  return { ok: true };
+}
+
+function rootFileExists(target, useSudo) {
+  if (!useSudo) return fs.existsSync(target);
+  return run('sudo', ['-n', 'test', '-f', target]).status === 0;
+}
+
+// The secrets sidecar the unit reads. Created ONCE, 0600, never overwritten — a
+// re-run must not clobber credentials an operator pasted in. Values stay out of
+// Environment= lines on purpose: `systemctl show` leaks those to every user.
+function ensureEnvFile(params, useSudo) {
+  const target = dev.envFilePath(params);
+  if (rootFileExists(target, useSudo)) return { path: target, created: false };
+  const body = [
+    `# ${dev.serviceName(params)} — secrets for this instance. Root-owned, 0600.`,
+    '# Referenced by the systemd unit as EnvironmentFile=- (optional: absent is fine).',
+    '# Fill in what applies, then: systemctl restart ' + dev.serviceName(params),
+    '',
+    '# Postgres password, if the role is not trusted/peer-authenticated:',
+    '#PGPASSWORD=',
+    '',
+    '# GitHub OAuth app for sign-in (see `bongos serve` output):',
+    `#${params.envPrefix}_GITHUB_CLIENT_ID=`,
+    `#${params.envPrefix}_GITHUB_CLIENT_SECRET=`,
+    '',
+  ].join('\n');
+  const w = writeRootFile(target, body, useSudo, 0o600);
+  return { path: target, created: w.ok, err: w.err };
+}
+
+const sc = (useSudo, args) => (useSudo ? run('sudo', ['-n', 'systemctl', ...args]) : run('systemctl', args));
+
+// Install (or refresh) the unit and bring the service up. Idempotent: rewriting
+// an identical unit is a no-op, and `restart` covers both "not yet running" and
+// "running the previous unit".
+function installUnit(params, plan) {
+  const service = dev.serviceName(params);
+  const target = dev.unitPath(params);
+  const envFile = ensureEnvFile(params, plan.sudo);
+  if (envFile.created) ok(`wrote ${envFile.path} (0600 — put secrets here)`);
+  else if (envFile.err) warn(`could not create ${envFile.path}: ${envFile.err}`);
+
+  const unit = dev.renderSystemdUnit(params, {
+    nodePath: process.execPath,
+    user: arg('--user') || (isRoot() ? null : currentUser()),
+    envFile: envFile.path,
+  });
+  const w = writeRootFile(target, unit, plan.sudo);
+  if (!w.ok) { fail(`could not write ${target}: ${w.err}`); return { ok: false }; }
+  ok(`installed ${target}`);
+
+  if (sc(plan.sudo, ['daemon-reload']).status !== 0) { fail('systemctl daemon-reload failed'); return { ok: false }; }
+  // enable = survive reboot; restart = pick up this unit whether or not it ran.
+  sc(plan.sudo, ['enable', service]);
+  const r = sc(plan.sudo, ['restart', service]);
+  if (r.status !== 0) {
+    fail(`systemctl restart ${service} failed:`);
+    console.error(tail(r.stderr, 6));
+    console.error(`  journalctl -u ${service} -n 50 --no-pager`);
+    return { ok: false };
+  }
+  return { ok: true, service, unitPath: target, envFile: envFile.path };
+}
+
+function currentUser() {
+  try { return require('node:os').userInfo().username; } catch { return null; }
+}
+
+// `systemctl is-active` exits non-zero when inactive, so read stdout, not status.
+function unitActive(params, useSudo) {
+  return sc(useSudo, ['is-active', dev.serviceName(params)]).stdout.trim() === 'active';
+}
+
 // ---- subcommands ---------------------------------------------------------------
 
 function cmdStop(params) {
+  // Server mode: if a unit owns this instance, stopping the pid-file process
+  // would be a no-op (or worse, systemd would restart it) — stop the unit, and
+  // disable it so "stopped" survives a reboot. `bongos serve` re-enables it.
+  if (params.mode === 'server') {
+    const plan = dev.systemdPlan({ has, isRoot: isRoot() });
+    if (plan.available) {
+      const useSudo = plan.sudo && sudoWorks();
+      const service = dev.serviceName(params);
+      if (rootFileExists(dev.unitPath(params), useSudo)) {
+        const r = sc(useSudo, ['stop', service]);
+        sc(useSudo, ['disable', service]);
+        if (r.status === 0) { ok(`stopped + disabled ${service}`); return 0; }
+        fail(`could not stop ${service}: ${tail(r.stderr, 2)}`);
+        return 1;
+      }
+    }
+  }
   const res = dev.stop(params);
   if (res.wasRunning) ok(`stopped the local ${params.dbName} server (pid ${res.pid})`);
   else console.log(`  (no running ${params.dbName} server to stop)`);
@@ -192,10 +372,31 @@ function cmdStop(params) {
 }
 
 async function cmdStatus(params) {
-  const running = dev.isRunning(params);
+  const server = params.mode === 'server';
   console.log(`instance:  ${path.basename(params.instanceRoot)}  (${params.publicOrigin})`);
   console.log(`database:  ${params.dbName}  on ${params.pgHost}`);
-  if (!running) { console.log('server:    not running  — start it with `bongos dev`'); return 0; }
+  console.log(`bind:      ${params.host}:${params.port}`);
+
+  if (server) {
+    const plan = dev.systemdPlan({ has, isRoot: isRoot() });
+    const useSudo = plan.available && plan.sudo && sudoWorks();
+    if (plan.available && rootFileExists(dev.unitPath(params), useSudo)) {
+      const active = unitActive(params, useSudo);
+      console.log(`service:   ${dev.serviceName(params)} — ${active ? 'active' : 'inactive'}  (${dev.unitPath(params)})`);
+      const h = await dev.health(params);
+      console.log(`health:    ${h.up ? 'OK' : 'unreachable on the bind address'}`);
+      console.log(`sign-in:   ${h.authConfigured ? 'configured' : 'NOT configured (see `bongos serve`)'}`);
+      const pub = await dev.publicHealth(params);
+      console.log(`public:    ${pub.reachable ? `reachable (${params.publicOrigin})` : `NOT reachable — ${pub.error || `HTTP ${pub.status}`}`}`);
+      console.log(`logs:      journalctl -u ${dev.serviceName(params)} -f`);
+      return 0;
+    }
+    console.log('service:   no systemd unit installed — start it with `bongos serve`');
+    // fall through: a fallback pid-managed server may still be up.
+  }
+
+  const running = dev.isRunning(params);
+  if (!running) { console.log(`server:    not running  — start it with \`bongos ${server ? 'serve' : 'dev'}\``); return 0; }
   const h = await dev.health(params);
   console.log(`server:    running (pid ${dev.readPid(params)}), health ${h.up ? 'OK' : 'starting/unreachable'}`);
   console.log(`sign-in:   ${h.authConfigured ? 'configured' : 'NOT configured (see `bongos dev`)'}`);
@@ -203,6 +404,71 @@ async function cmdStatus(params) {
   return 0;
 }
 
+// The tail of a server-mode `up`: supervise, wait for health, report the outward
+// view. Never auto-signs-in (a host has no browser) — it prints the command.
+async function cmdServeStart(params) {
+  const plan = dev.systemdPlan({ has, isRoot: isRoot() });
+  let managed = null;
+
+  if (plan.available) {
+    const useSudo = plan.sudo && sudoWorks();
+    if (plan.sudo && !useSudo) {
+      warn('sudo needs a password here, so I cannot install a systemd unit non-interactively.');
+      console.log('  Either run `sudo bongos serve`, or grant passwordless sudo, and I will supervise with systemd.');
+    } else {
+      managed = installUnit(params, { ...plan, sudo: useSudo });
+      if (!managed.ok) return 1;
+      ok(`${managed.service} started (enabled at boot, restarts on failure)`);
+    }
+  } else {
+    warn(`no systemd here (${plan.reason}) — falling back to a managed background process.`);
+    console.log('  It will NOT survive a reboot. Add it to this host’s own supervisor for production.');
+  }
+
+  if (!managed) {
+    const started = dev.startDetached(params);
+    if (started.already) ok(`server already running (pid ${started.pid})`);
+    else ok(`server running (pid ${started.pid}), logs: ${started.log}`);
+  }
+
+  const h = await waitHealthy(params);
+  if (!h.up) {
+    fail(`the server did not become healthy on ${params.host}:${params.port}. Recent log:`);
+    if (managed) console.error(run('journalctl', ['-u', managed.service, '-n', '20', '--no-pager']).stdout || `  journalctl -u ${managed.service} -n 50 --no-pager`);
+    else { try { console.error(tail(fs.readFileSync(dev.logPath(params), 'utf8'), 12)); } catch { /* no log */ } }
+    return 1;
+  }
+  ok(`healthy on ${params.host}:${params.port}`);
+
+  // The loopback probe proves the app. This proves the PATH TO IT — DNS, the
+  // proxy, TLS — which is the part that actually differs on a real host.
+  const pub = await dev.publicHealth(params);
+  blank();
+  if (pub.reachable) {
+    ok(`${params.publicOrigin} is answering`);
+  } else {
+    warn(`${params.publicOrigin} is not answering yet (${pub.error || `HTTP ${pub.status}`}).`);
+    console.log('  The app is up on this host — what is missing is in front of it:');
+    if (params.host === '127.0.0.1') console.log(`    • a reverse proxy forwarding ${params.publicOrigin} → 127.0.0.1:${params.port} (TLS terminates there)`);
+    else console.log(`    • DNS for ${new URL(params.publicOrigin).hostname} pointing at this host, and port ${params.port} open in the firewall`);
+    console.log('    • see docs/recipes/server-bring-up.md');
+  }
+
+  blank();
+  console.log(`  → ${params.publicOrigin}`);
+  if (managed) {
+    console.log(`     status:  bongos serve status      logs: journalctl -u ${managed.service} -f`);
+    console.log(`     stop:    bongos serve stop        secrets: ${managed.envFile}`);
+  } else {
+    console.log(`     status:  bongos serve status      stop: bongos serve stop`);
+  }
+  blank();
+
+  if (!dev.authWillWork()) { printOAuthGuidance(params); return 0; }
+  console.log(`  Sign in from your own machine:  bongos login ${params.publicOrigin}`);
+  return 0;
+}
+
 async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
   info(`Standing up ${path.basename(params.instanceRoot)} on ${params.publicOrigin}`);
 
@@ -270,6 +536,9 @@ async function cmdUp(params, { foreground, noLogin, skipMigrate }) {
     return r.status == null ? 1 : r.status;
   }
 
+  // Server mode: hand the process to the host's own supervisor.
+  if (params.mode === 'server') return cmdServeStart(params);
+
   // Default: managed background server.
   const started = dev.startDetached(params);
   if (started.already) ok(`server already running (pid ${started.pid})`);
@@ -302,7 +571,9 @@ async function main() {
   if (hasFlag('--help') || hasFlag('-h') || argv[0] === 'help') { usage(); return 0; }
 
   const params = dev.resolveRunParams({ instanceRoot: process.cwd(), argv });
-  const sub = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'up';
+  // Flag-order-independent: `bongos serve stop` reaches us as ['--server','stop'],
+  // and `--port 3006 status` puts a flag VALUE where a naive argv[0] scan looked.
+  const sub = dev.parseSub(argv);
 
   if (sub === 'stop') return cmdStop(params);
   if (sub === 'status') return cmdStatus(params);