@openmeet/snowglobe 0.3.0-rc.0 → 0.3.0

package/.env.example

@@ -1,7 +1,7 @@
 # Database credentials — single source of truth for PLC and test postgres.
 # Consumer overrides these to use their own postgres instance.
 SG_DB_USER=postgres
-SG_DB_PASSWORD=postgres
+# SG_DB_PASSWORD=   (unset: snowglobe up makes a random one, in secrets.env in the snowglobe's state folder)
 SG_DB_HOST=postgres
 SG_DB_PORT=5432
 SG_DB_NAME=plc

package/README.md

@@ -80,14 +80,19 @@ keeps the https names, and they are what make an app run unchanged.
 ## Quick start
 
 ```bash
-git clone https://github.com/OpenMeet-Team/snowglobe.git
-cd snowglobe
-npm install
-npm link                                 # puts the snowglobe command on your PATH
-cp snowglobe.default.yml snowglobe.yml   # the file says what your snowglobe runs; edit it freely
-snowglobe up                     # the first run pulls and builds images, which takes a while
+npm install -g @openmeet/snowglobe       # puts the snowglobe command on your PATH
+snowglobe up --default                   # the first run pulls and builds images, which takes a while
 ```
 
+To change what it runs, copy the default file into your folder, give it a name of its own on the
+`globe:` line (`snowglobe` is the default file's, and a snowglobe belongs to the file that first
+brought it up), edit it, and run `snowglobe up`:
+`cp "$(npm root -g)/@openmeet/snowglobe/snowglobe.default.yml" snowglobe.yml`.
+To keep the command with one project instead, run `npm install --save-dev @openmeet/snowglobe`, then
+`npx snowglobe up --default` for the default, or `npx snowglobe up` once the folder has a
+`snowglobe.yml` (copy it from `node_modules/@openmeet/snowglobe/snowglobe.default.yml`). Either
+command also fits in a `package.json` script.
+
 Now try it. `snowglobe run` runs a command that can reach the snowglobe by name, and `--cacert`
 gives curl the snowglobe's certificate authority (CA), so it trusts the snowglobe's https:
 

package/bin/snowglobe.mjs

@@ -2,6 +2,7 @@
 // snowglobe: run the globe a snowglobe.yml describes.
 //
 //   check     checks a snowglobe.yml
+//   ls        lists the snowglobes on this machine
 //   render    writes the https globe it describes into its state folder
 //   certs     makes your CA, once, and the leaf nginx serves
 //   trust     puts your CA in the system and browser trust stores (--remove takes it out)
@@ -10,8 +11,8 @@
 //   invite    mints an invite code on one of its PDSes
 //   lexicons  publishes lexicons into its lexicon authority
 //   app       routes https://<name>.app.<domain> to a port on this machine
-//   up        brings the globe up, as the compose project named for its file
-//   down      stops it
+//   up        brings the globe up, as the compose project named for its file (or <name>, -f <file>)
+//   down      stops it (the same ways)
 //   run       runs a command with the app's settings, and plc.directory pointed at the snowglobe
 //
 // A snowglobe is the snowglobe.yml in the folder you are in or the nearest one above (else
@@ -30,6 +31,7 @@ import { Refused, UsageError, adoptOldNames } from '../lib/env.mjs';
 // Loaded when it runs, so check and render do without the certificate library.
 const COMMANDS = {
   check: () => import('../lib/commands/check.mjs'),
+  ls: () => import('../lib/commands/ls.mjs'),
   render: () => import('../lib/commands/render.mjs'),
   certs: () => import('../lib/commands/certs.mjs'),
   trust: () => import('../lib/commands/trust.mjs'),

package/lib/apps.mjs

@@ -15,7 +15,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
 import { join } from 'node:path';
 import { ROOT, globeFacts, paths } from './env.mjs';
 
-const HEADER = '# Written by bin/snowglobe.mjs app from https/apps; rerun it instead of editing.\n';
+const HEADER = '# Written by snowglobe app from https/apps; rerun it instead of editing.\n';
 
 /**
  * The first saved route whose ending is `app`, or null. app.<domain> is where the apps are, so an
@@ -25,7 +25,7 @@ export const appEnding = (apps) => apps.find((a) => a.ending === 'app') ?? null;
 
 export const appEndingMessage = (file, a) =>
   `${file}: the line "${formatApps([a]).trim()}" claims the ending app, which is where the apps are (${a.name}.app.<domain>); ` +
-  `remove the route (bin/snowglobe.mjs app --remove ${a.name}) or give it another ending`;
+  `remove the route (snowglobe app --remove ${a.name}) or give it another ending`;
 
 /** The routes in an apps file's text: [{ name, port, ending }], ending null when none. */
 export function parseApps(text) {
@@ -85,7 +85,7 @@ export const writeApps = (p, apps) => put(p.apps, formatApps(apps));
 export function renderRoutes({ root = ROOT, state, env = process.env } = {}) {
   const p = paths(root, state);
   const pageJson = join(p.globe, 'page.json');
-  if (!existsSync(pageJson)) throw new Error(`No ${pageJson}: run bin/snowglobe.mjs up, which renders it`);
+  if (!existsSync(pageJson)) throw new Error(`No ${pageJson}: run snowglobe up, which renders it`);
   const { domain } = globeFacts({ root, state, env });
   const apps = readApps(p);
   const bad = appEnding(apps);

package/lib/commands/down.mjs

@@ -1,37 +1,40 @@
-// bin/snowglobe.mjs down [-v]
+// bin/snowglobe.mjs down [<file> | <name>] [-f <file>] [-v]
 //
 // down stops the compose project of the snowglobe in this folder (or above, see lib/state.mjs;
-// SG_PROJECT if set), on the globe up last rendered (globe/ in its state folder), and a service an
+// SG_PROJECT if set), or of the one it is pointed at: a file (<file> or -f <file>), or a name
+// from snowglobe ls, which works even when the file that owned it is gone, on the globe up last rendered (globe/ in its state folder), and a service an
 // earlier render ran and this one does not with it.
 //   -v  also drop the project's volumes: every account, DID and record is gone. The PLC's
 //       database is a named volume, so without -v the DIDs survive with the PDSes.
 //
 // The state folder is never deleted. After -v, the next up starts over: the base init reseeds
 // alice and bob and rewrites accounts.env from scratch, dropping the logins the tools wrote there
-// (their accounts are gone too), and the lexicon authority is made again. The CA, the leaf and
+// (their accounts are gone too), and the lexicon authority is made again. The fixed secrets an
+// older snowglobe kept for its data (secrets.env) are dropped with it, so up makes random ones. The CA, the leaf and
 // the app routes stay either way. The project is guarded as up guards it.
 
-import { ROOT, dc, guardProject } from '../env.mjs';
-import { session } from '../state.mjs';
+import { ROOT, dc, dropLegacySecrets, guardProject } from '../env.mjs';
+import { byName, pointedAt, session } from '../state.mjs';
 
 export const command = {
   name: 'down',
-  usage: 'down [-v]',
-  options: { volumes: { type: 'boolean', short: 'v' } },
-  positionals: [0, 0],
-  accepts: ({ tokens }) => tokens.length <= 1,
+  usage: 'down [<file> | <name>] [-f <file>] [-v]',
+  options: { volumes: { type: 'boolean', short: 'v' }, file: { type: 'string', short: 'f' } },
+  positionals: [0, 1],
 };
 
-export function run({ values }) {
-  return down({ volumes: values.volumes });
+export function run({ values, positionals: [word] }) {
+  return down({ volumes: values.volumes, ...pointedAt({ file: values.file, word }) });
 }
 
-export function down({ volumes = false, file, root = ROOT, env = process.env } = {}) {
+export function down({ volumes = false, file, name, root = ROOT, env = process.env } = {}) {
   // The shared devnet is refused before anything is looked up, even by a file that is not there.
   if (env.SG_PROJECT) guardProject(env);
-  const found = session({ file, env });
+  const found = name ? byName(name, { env }) : session({ file, env });
   const project = guardProject(env, found.name);
   const res = dc(project, ['down', '--remove-orphans', ...(volumes ? ['-v'] : [])], { root, state: found.state, env });
   if (res.error) throw res.error;
+  // The data the fixed secrets were kept for is gone only once compose says it removed it.
+  if (volumes && res.status === 0) dropLegacySecrets({ root, state: found.state });
   return res.status ?? 1;
 }

package/lib/commands/env.mjs

@@ -12,7 +12,7 @@
 // lib/settings.mjs has the names.
 
 import { existsSync } from 'node:fs';
-import { ROOT, UsageError, envGet, paths, resolveDomain, setting } from '../env.mjs';
+import { ROOT, UsageError, envGet, paths, resolveBind, resolveDomain, setting } from '../env.mjs';
 import { session } from '../state.mjs';
 import { isSecret, lookup, parseValue } from '../settings.mjs';
 import { accountPrefixes } from '../up.mjs';
@@ -51,7 +51,8 @@ function load({ file, root = ROOT, env = process.env } = {}) {
     if (name === 'ca.file') return existsSync(p.ca) ? p.ca : undefined;
     if (name === 'accounts.file') return existsSync(p.accounts) ? p.accounts : undefined;
     // The mail page's port is a setting, not recorded in the state; the rendered globe says up has run.
-    if (name === 'services.mail.url') return !existsSync(p.compose) ? undefined : `http://127.0.0.1:${setting('SG_MAILDEV_WEB_PORT', { root, env }) || '1081'}`;
+    if (name === 'services.mail.url') return !existsSync(p.compose) ? undefined : `http://${resolveBind({ root, state: found.state, env })}:${setting('SG_MAILDEV_WEB_PORT', { root, env }) || '1081'}`;
+    if (name === 'services.tap.url') return !existsSync(p.compose) ? undefined : `http://${resolveBind({ root, state: found.state, env })}:${setting('SG_TAP_PORT', { root, env }) || '2480'}`;
     if (name === 'lexicons.authority.did') return kept('LEX_AUTHORITY_DID');
     if (head === 'accounts') return kept(`${prefixes.get(rest[0])}_${rest[1].toUpperCase()}`);
     return undefined;

package/lib/commands/ls.mjs

@@ -0,0 +1,72 @@
+// bin/snowglobe.mjs ls
+//
+// ls lists the snowglobes on this machine: every folder in the state root (lib/env.mjs stateRoot;
+// ca/, the one CA, is not one) with its name, the domain it was rendered for, whether its compose
+// project is running, and the file that owns it. Take the name to `up`, `down`, or a file to -f.
+// "up" is a project with a container running (the one-shot init and relay-init have exited by
+// then), "down" is none, or no project yet; "unknown" is what it says when Docker did not answer.
+// Reads only; nothing is started.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT, envGet, paths, stateRoot } from '../env.mjs';
+import { ownerOf } from '../state.mjs';
+
+export const command = {
+  name: 'ls',
+  usage: 'ls',
+  options: {},
+  positionals: [0, 0],
+};
+
+/** Compose's own status for each project, "running(5)" or "exited(2)" or "exited(1), running(10)", by name; null when Docker did not answer. */
+export function projectStatuses() {
+  const res = spawnSync('docker', ['compose', 'ls', '-a', '--format', 'json'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) return null;
+  try {
+    return new Map(JSON.parse(res.stdout || '[]').map((p) => [p.Name, p.Status ?? '']));
+  } catch {
+    return null;
+  }
+}
+
+// What a compose status means for the table.
+export function stateWord(status) {
+  return /running\(\d+\)/.test(status ?? '') ? 'up' : 'down';
+}
+
+/**
+ * The snowglobes in the state root: [{ name, domain, state, file }], by name. `statuses` is
+ * projectStatuses()'s answer, null for "unknown". A file that is gone is shown as "(gone)".
+ */
+export function list({ root = ROOT, env = process.env, statuses = projectStatuses() } = {}) {
+  const base = stateRoot(env);
+  if (!existsSync(base)) return [];
+  return readdirSync(base, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== 'ca')
+    .map((e) => {
+      const state = join(base, e.name);
+      const owner = ownerOf(state);
+      return {
+        name: e.name,
+        domain: envGet('SG_DOMAIN', paths(root, state).globeEnv) || '-',
+        state: statuses === null ? 'unknown' : stateWord(statuses.get(env.SG_PROJECT || e.name)),
+        file: owner ? (existsSync(owner) ? owner : `${owner} (gone)`) : '-',
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function run() {
+  const rows = list();
+  if (!rows.length) {
+    console.log(`No snowglobes in ${stateRoot()}. snowglobe up in a folder with a snowglobe.yml makes one.`);
+    return 0;
+  }
+  const head = { name: 'NAME', domain: 'DOMAIN', state: 'STATE', file: 'FILE' };
+  const cols = Object.keys(head);
+  const width = Object.fromEntries(cols.map((c) => [c, Math.max(head[c].length, ...rows.map((r) => r[c].length))]));
+  for (const r of [head, ...rows]) console.log(cols.map((c, i) => (i === cols.length - 1 ? r[c] : r[c].padEnd(width[c]))).join('  '));
+  return 0;
+}

package/lib/commands/run.mjs

@@ -76,7 +76,7 @@ export function runUnder(cmd, { root = ROOT, env = process.env, state = session(
   if (!bwrap) throw new Error('bwrap (bubblewrap) is not installed, or not on PATH');
   // Refuses a SG_DOMAIN the render is not for, and a SG_BIND that is not loopback.
   const { domain } = resolveDomain({ root, state, env });
-  const bind = resolveBind({ root, env });
+  const bind = resolveBind({ root, state, env });
 
   const read = (f) => (existsSync(f) ? readFileSync(f, 'utf8') : '');
   const names = runNames({ leafNames: read(p.leafNames), handles: read(p.names), apps: readApps(p), domain, extra: env.HTTPS_RUN_EXTRA_NAMES });

package/lib/commands/up.mjs

@@ -1,4 +1,4 @@
-// bin/snowglobe.mjs up [<file>]
+// bin/snowglobe.mjs up [<file> | <name>] [-f <file>] [--default]
 //
 // up brings up the globe a snowglobe.yml describes, as the compose project named for the file's
 // `globe:` (or SG_PROJECT). Safe to rerun: each step keeps what an earlier run made, and a rerun
@@ -10,7 +10,8 @@
 // means that folder. A checkout that still holds a globe in its own data/ is refused (nothing
 // started, nothing moved) with the command that moves it.
 //
-//   1. render: data/globe/ from <file>, else SG_FILE, else the nearest snowglobe.yml here or above
+//   1. render: data/globe/ from <file> (or -f <file>), or the file that owns the snowglobe called
+//      <name> (snowglobe ls lists them), else SG_FILE, else the nearest snowglobe.yml here or above
 //      (none: up refuses; `up --default` runs the default globe, snowglobe.default.yml: one PDS,
 //      a PLC directory and Jetstream).
 //      SG_DOMAIN, from the environment or .env, replaces the file's domain.
@@ -34,10 +35,10 @@
 //
 // A rerun finds the accounts and leaves unchanged lexicons alone. Anything else an app makes
 // (more accounts, invite codes) is its own, with account, invite and lexicons. Nothing secret is
-// printed. The tool ports come from the usual variables
-// (SG_PLC_PORT, SG_JETSTREAM_PORT, SG_JETSTREAM_METRICS_PORT,
-// SG_MAILDEV_WEB_PORT, SG_MAILDEV_SMTP_PORT, SG_PROXY_PORT), in the environment or
-// .env; pass the same ones on every run. devnet-spaces, the shared devnet, is refused (exit 3) as
+// printed. The tool ports (SG_PLC_PORT, SG_JETSTREAM_PORT, SG_JETSTREAM_METRICS_PORT,
+// SG_MAILDEV_WEB_PORT, SG_MAILDEV_SMTP_PORT, SG_PROXY_PORT) are published on the snowglobe's own
+// loopback address (SG_BIND, else the one chosen at its first up and kept in its state folder), so
+// two snowglobes need no port settings; a port variable moves one, in the environment or .env. devnet-spaces, the shared devnet, is refused (exit 3) as
 // the project unless SG_RESET_OK=1, before anything else is done.
 
 import { createHash } from 'node:crypto';
@@ -45,8 +46,10 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { dirname, join, resolve } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { appEnding, appEndingMessage, formatApps, readApps, renderRoutes, writeApps } from '../apps.mjs';
-import { ROOT, addName, dc, ensureAdminPassword, snowglobeRequest, envGet, guardProject, makePrivate, oldDataNotice, paths, renamedDefaultNotice, resolveBind, resolveDomain } from '../env.mjs';
-import { claimState, session } from '../state.mjs';
+import { loadGlobe } from '../config.mjs';
+import { ROOT, addName, chooseBind, dc, ensureSecrets, projectHasData, snowglobeRequest, envGet, guardProject, makePrivate, oldDataNotice, paths, renamedDefaultNotice, resolveBind, resolveDomain } from '../env.mjs';
+import { prebuilt } from '../prebuilt.mjs';
+import { byName, claimState, pointedAt, session } from '../state.mjs';
 import { accountPrefixes, endingClash, mergeRoutes } from '../up.mjs';
 import { account } from './account.mjs';
 import { lexicons } from './lexicons.mjs';
@@ -55,12 +58,12 @@ import { writeGlobe } from './render.mjs';
 
 export const command = {
   name: 'up',
-  usage: 'up [<file> | --default]',
+  usage: 'up [<file> | <name>] [-f <file>] [--default]',
   // --default is the only way up runs the repo's default snowglobe; with no file and no
   // snowglobe.yml in this folder or above, up refuses.
-  options: { default: { type: 'boolean' } },
+  options: { default: { type: 'boolean' }, file: { type: 'string', short: 'f' } },
   positionals: [0, 1],
-  accepts: ({ values, positionals }) => !(values.default && positionals.length),
+  accepts: ({ values, positionals }) => !(values.default && (positionals.length || values.file)),
 };
 
 // How long a one-shot (init, relay-init) may take, and nginx to answer again after a restart.
@@ -80,8 +83,23 @@ async function waitServing(domain, { root, state, env }) {
   }
 }
 
-export async function run({ values, positionals: [file] }) {
-  await up({ file: values.default ? join(ROOT, 'snowglobe.default.yml') : file, log: (m) => console.error(m) });
+export async function run({ values, positionals: [word] }) {
+  let file;
+  if (values.default) file = join(ROOT, 'snowglobe.default.yml');
+  else {
+    const at = pointedAt({ file: values.file, word });
+    file = at.file;
+    if (at.name) {
+      // A snowglobe by its name is brought up from the file that owns it.
+      file = byName(at.name).path;
+      if (!file) throw new Error(`the file that owned the snowglobe ${at.name} is gone; bring it up from a file: snowglobe up -f <file>`);
+      // The file may have been renamed since (globe: changed): up would then start the new name.
+      const { globe } = loadGlobe(file);
+      if (globe && globe.globe !== at.name)
+        throw new Error(`${file} says globe: ${globe.globe} now, not ${at.name}; put globe: ${at.name} back to bring ${at.name} up, or snowglobe up ${file} to start ${globe.globe} as a new snowglobe`);
+    }
+  }
+  await up({ file, log: (m) => console.error(m) });
 }
 
 export async function up({ file, root = ROOT, env = process.env, log = () => {} }) {
@@ -98,13 +116,16 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   // Both are read as compose reads them, and refused here when they are not a domain and a
   // loopback address.
   const { set } = resolveDomain({ root, state, env, rendering: true });
-  resolveBind({ root, env });
+  resolveBind({ root, state, env });
 
   const { path, globe } = checkedGlobe(found.path, { domain: set || undefined });
   if (!globe) throw new Error(`${path} has problems (above); ${p.globe} is as it was`);
   // From here on the file's globe is the one this state folder is for.
   const took = claimState(found);
   if (took) log(took);
+  // Its own loopback address for every published port, chosen once, so a second snowglobe starts beside this one.
+  const bind = await chooseBind({ root, state, project, env });
+  if (bind !== '127.0.0.1') log(`${found.name} publishes its ports on ${bind}`);
   // Checked before the render changes, so a refused file leaves the running globe's render.
   const kept = readApps(p);
   const badEnding = appEnding(kept);
@@ -139,7 +160,10 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
 
   const facts = (name) => envGet(name, p.globeEnv).split(' ').filter(Boolean);
   // compose fills the file's ${SG_LEXICON_AUTHORITY_DID} from this.
-  const composeEnv = { ...env, SG_PDS_ADMIN_PASSWORD: ensureAdminPassword({ root, state, env }) };
+  const secrets = ensureSecrets({ root, state, env, hasData: () => projectHasData(project, env) });
+  if (secrets.kept.length)
+    log(`${found.name} has data made before its secrets were random, so it keeps the fixed ${secrets.kept.join(', ')}. snowglobe down -v, then up, starts it over with random ones (every account is lost).`);
+  const composeEnv = { ...env, ...secrets.values };
   const compose = (args, opts = {}) => {
     const res = dc(project, args, { root, state, env: composeEnv, ...opts });
     if (res.error) throw res.error;
@@ -189,8 +213,22 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   // A group host built from a folder is the folder as it is now; Docker's cache makes an
   // unchanged image quick.
   const builds = facts('SG_BUILDS');
-  log(`Building images${builds.length ? ` (${builds.join(' ')})` : ''}`);
-  compose(['build', '--quiet']);
+  // The images snowglobe publishes are pulled where the registry has the build of these very files
+  // (lib/prebuilt.mjs); only the rest are built. Compose fills in the ${...} defaults (an image's
+  // tag follows its commit); if it cannot say, everything is built, as before.
+  let toBuild = [];
+  try {
+    const services = JSON.parse(compose(['config', '--format', 'json'], { stdio: 'pipe', encoding: 'utf8' }).stdout).services;
+    const have = prebuilt({ root, services, env, log });
+    toBuild = Object.keys(services).filter((s) => services[s].build && !have.includes(s));
+  } catch {
+    toBuild = [];
+    compose(['build', '--quiet']);
+  }
+  if (toBuild.length) {
+    log(`Building images${builds.length ? ` (${builds.join(' ')})` : ''}`);
+    compose(['build', '--quiet', ...toBuild]);
+  }
 
   // A rerun starts the PDSes with the authority they already have, so pass 1 changes nothing.
   composeEnv.SG_LEXICON_AUTHORITY_DID = envGet('LEX_AUTHORITY_DID', p.accounts);
@@ -212,6 +250,12 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   if (did !== composeEnv.SG_LEXICON_AUTHORITY_DID) {
     composeEnv.SG_LEXICON_AUTHORITY_DID = did;
     log(`Pass 2: up with the lexicon authority ${did}`);
+    // Pass 2 recreates every PDS. Jetstream with no relay reads the first PDS itself and exits
+    // while it is gone; on a slow machine (a CI runner) it was still restarting when compose
+    // checked it, and up failed with "jetstream is unhealthy". Stopped first, it is started
+    // again only once the PDS is healthy.
+    const running = facts('SG_SERVICES');
+    if (running.includes('jetstream') && !running.includes('relay')) compose(['stop', 'jetstream'], { stdio: 'ignore' });
     await upStack();
   }
 

package/lib/config.mjs

@@ -214,6 +214,7 @@ export function checkGlobe(doc, { baseDir } = {}) {
   }
 
   // services
+  let tap = null;
   const services = { relay: 'auto', jetstream: true, tap: false, slingshot: true, pdsls: true, cdn: false };
   if (doc.services !== undefined) {
     if (!isMap(doc.services)) err('services', 'must be a map');
@@ -223,7 +224,10 @@ export function checkGlobe(doc, { baseDir } = {}) {
         const v = doc.services[k];
         if (v === undefined) continue;
         if (typeof v === 'boolean' || (k === 'relay' && v === 'auto')) services[k] = v;
-        else err(`services.${k}`, `must be true or false${k === 'relay' ? ', or auto' : ''}`);
+        else if (k === 'tap' && isMap(v)) {
+          services.tap = true;
+          tap = readTap(v, err);
+        } else err(`services.${k}`, `must be true or false${k === 'relay' ? ', or auto' : k === 'tap' ? ', or a map of webhook, signal_collection and collection_filters' : ''}`);
       }
     }
   }
@@ -374,7 +378,7 @@ export function checkGlobe(doc, { baseDir } = {}) {
     }
   }
 
-  const globe = { globe: doc.globe, domain, pds, grouphosts, services, lexicons, accounts, apps, hosted };
+  const globe = { globe: doc.globe, domain, pds, grouphosts, services, tap, lexicons, accounts, apps, hosted };
   // The names in the apps' settings, against the file as it now stands. Left until the rest is sound,
   // or a PDS that failed its own check would be reported again as an unknown name.
   if (!errors.length) for (const [where, msg] of checkSettings(globe)) err(where, msg);
@@ -460,6 +464,31 @@ function label(v, where, err) {
     err(where, `${show(v)} must be one lowercase DNS label (letters, digits, inner hyphens)`);
 }
 
+// services.tap as a map: where Tap sends events, and which collection it follows. The webhook may
+// hold ${...} placeholders (checkSettings looks them up); an account is found when it writes in the
+// signal collection, so the filters default to that collection alone.
+const NSID_RE = /^[a-zA-Z][a-zA-Z0-9-]*(\.[a-zA-Z0-9-]+){2,}$/;
+function readTap(map, err) {
+  unknownKeys(map, ['webhook', 'signal_collection', 'collection_filters'], 'services.tap', err);
+  const tap = { webhook: null, signal_collection: null, collection_filters: [] };
+  if (map.webhook !== undefined) {
+    if (typeof map.webhook !== 'string' || map.webhook === '') err('services.tap.webhook', 'must be a URL (it may hold ${...} names)');
+    else tap.webhook = map.webhook;
+  }
+  if (map.signal_collection !== undefined) {
+    if (typeof map.signal_collection !== 'string' || !NSID_RE.test(map.signal_collection))
+      err('services.tap.signal_collection', `${show(map.signal_collection)} must be a collection name, such as xyz.statusphere.status`);
+    else tap.signal_collection = map.signal_collection;
+  }
+  if (map.collection_filters !== undefined) {
+    if (!Array.isArray(map.collection_filters) || map.collection_filters.some((c) => typeof c !== 'string' || !NSID_RE.test(c)))
+      err('services.tap.collection_filters', 'must be a list of collection names');
+    else tap.collection_filters = map.collection_filters;
+  }
+  if (!tap.collection_filters.length && tap.signal_collection) tap.collection_filters = [tap.signal_collection];
+  return tap;
+}
+
 function unknownKeys(map, allowed, where, err) {
   for (const k of Object.keys(map))
     if (!allowed.includes(k)) err(where ? `${where}.${k}` : k, `unknown setting; known here: ${allowed.join(', ')}`);

package/lib/env.mjs

@@ -5,8 +5,9 @@
 
 import { spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { request } from 'node:https';
+import net from 'node:net';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -75,8 +76,12 @@ export function paths(root = ROOT, state) {
     // The snowglobe's own logins: the base init's alice, bob and invite code, the lexicon
     // authority, and accounts made by snowglobe account.
     accounts: join(data, 'accounts.env'),
-    // The PDSes' admin password, made by up (random, once) and read by account and invite.
-    // A file of its own: the base init rewrites accounts.env.
+    // The secrets the services start with (SECRETS below), made by up, once, and read by account
+    // and invite. A file of its own: the base init rewrites accounts.env.
+    secrets: join(data, 'secrets.env'),
+    // The loopback address this snowglobe publishes its ports on (chooseBind), one line.
+    bind: join(data, 'bind'),
+    // Where the admin password was kept before secrets.env (read, never written, for a snowglobe made then).
     admin: join(data, 'admin.env'),
     // App routes, "<name> <port> [<ending>]" per line (snowglobe app).
     apps: join(https, 'apps'),
@@ -248,17 +253,110 @@ export function globeFacts({ root = ROOT, state, env = process.env } = {}) {
   };
 }
 
-// The address nginx publishes 443 on, worked out as compose works out ${SG_BIND:-127.0.0.1}.
-// A loopback address only (127.x.y.z, one per globe run side by side): the globe's logins are
-// throwaway, so it is never published beyond this machine.
-export function resolveBind({ root = ROOT, env = process.env } = {}) {
-  const bind = setting('SG_BIND', { root, env }) || '127.0.0.1';
+// The loopback address nginx and every other published port use, worked out as compose works out
+// ${SG_BIND:-127.0.0.1}: SG_BIND where set, else the one `up` chose for this snowglobe (the bind
+// file in its state folder), else 127.0.0.1. A loopback address only (127.x.y.z, one per globe run
+// side by side): the globe's logins are throwaway, so it is never published beyond this machine.
+export function resolveBind({ root = ROOT, state, env = process.env } = {}) {
+  const saved = state && existsSync(paths(root, state).bind) ? readFileSync(paths(root, state).bind, 'utf8').trim() : '';
+  const bind = setting('SG_BIND', { root, env }) || saved || '127.0.0.1';
   const parts = bind.split('.');
   if (parts.length !== 4 || parts[0] !== '127' || parts.slice(1).some((x) => !/^[0-9]+$/.test(x) || Number(x) > 255))
     throw new Error(`SG_BIND=${bind} is not a loopback address 127.x.y.z (set in the environment or .env)`);
   return bind;
 }
 
+// The ports a snowglobe publishes on its address: nginx, and the tools (each can be moved with its SG_..._PORT).
+// Tap's is probed whether or not this globe runs Tap: an address another globe's Tap answers on is not free.
+const PUBLISHED = [['', 443], ['SG_PROXY_PORT', 1080], ['SG_MAILDEV_WEB_PORT', 1081], ['SG_MAILDEV_SMTP_PORT', 1026], ['SG_PLC_PORT', 2582], ['SG_JETSTREAM_PORT', 6008], ['SG_JETSTREAM_METRICS_PORT', 6009], ['SG_TAP_PORT', 2480]];
+
+// Whether something already answers on any port a snowglobe would publish on a loopback address.
+export async function addressBusy(address, { root = ROOT, env = process.env } = {}) {
+  const answers = (port) =>
+    new Promise((done) => {
+      const s = net.connect({ host: address, port, timeout: 500 });
+      s.on('connect', () => (s.destroy(), done(true)));
+      s.on('timeout', () => (s.destroy(), done(false)));
+      s.on('error', () => done(false));
+    });
+  const ports = PUBLISHED.map(([name, port]) => Number((name && setting(name, { root, env })) || port));
+  return (await Promise.all(ports.map(answers))).some(Boolean);
+}
+
+// Whether the compose project's own nginx is running now.
+export function ownNginxUp(project, env = process.env) {
+  const res = spawnSync('docker', ['ps', '-q', '--filter', `label=com.docker.compose.project=${project}`, '--filter', 'label=com.docker.compose.service=nginx'], { encoding: 'utf8', env });
+  return !res.error && res.status === 0 && res.stdout.trim() !== '';
+}
+
+/**
+ * The loopback address this snowglobe publishes on, chosen once and kept in its state folder, so a
+ * second snowglobe on the machine starts beside the first with no settings: it takes the first
+ * 127.0.0.N that no other snowglobe in the same user folder has kept and nothing answers on 443 or any other port it publishes.
+ * SG_BIND, where set, wins and nothing is written. A snowglobe that is already running with no
+ * address kept was made before this and is on 127.0.0.1, so it keeps that. Returns the address.
+ */
+export async function chooseBind({ root = ROOT, state, project, env = process.env, listening = (a) => addressBusy(a, { root, env }), ownUp = ownNginxUp } = {}) {
+  const p = paths(root, state);
+  if (setting('SG_BIND', { root, env }) || existsSync(p.bind)) return resolveBind({ root, state, env });
+  // Choosing reads the other bind files, waits on probes, then writes ours, so two first starts at
+  // once would both pick the same address and keep it. One at a time, under a lock beside the state folders.
+  return withLock(join(dirname(state), '.bind-lock'), async () => {
+    if (existsSync(p.bind)) return resolveBind({ root, state, env });
+    return pickBind({ p, state, project, env, listening, ownUp });
+  });
+}
+
+// Run `fn` holding a lock directory (mkdir is atomic). A lock older than `stale` ms was left by a
+// process that died. It is not taken over, since two starts taking it over at once could both
+// hold it; up stops and names the folder to remove.
+async function withLock(dir, fn, { stale = 60000, wait = 30000 } = {}) {
+  mkdirSync(dirname(dir), { recursive: true });
+  const until = Date.now() + wait;
+  for (;;) {
+    try {
+      mkdirSync(dir);
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      let age;
+      try {
+        age = Date.now() - statSync(dir).mtimeMs;
+      } catch {
+        continue; // released between the two calls
+      }
+      if (age > stale) throw new Error(`a snowglobe that stopped while choosing an address left ${dir}; remove that folder, then up again`);
+      if (Date.now() > until) throw new Error(`another snowglobe is choosing an address (${dir}); remove that folder if none is`);
+      await new Promise((r) => setTimeout(r, 25));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function pickBind({ p, state, project, env, listening, ownUp }) {
+  const used = new Set();
+  const top = dirname(state);
+  for (const d of existsSync(top) ? readdirSync(top) : []) {
+    const f = join(top, d, 'bind');
+    if (join(top, d) !== state && existsSync(f)) used.add(readFileSync(f, 'utf8').trim());
+  }
+  let bind = '127.0.0.1';
+  if (!ownUp(project, env)) {
+    bind = '';
+    for (let n = 1; n <= 50 && !bind; n++) {
+      const a = `127.0.0.${n}`;
+      if (!used.has(a) && !(await listening(a))) bind = a;
+    }
+    if (!bind) throw new Error('every loopback address from 127.0.0.1 to 127.0.0.50 is in use; set SG_BIND to one that is free');
+  }
+  writeFileSync(p.bind, `${bind}\n`);
+  return bind;
+}
+
 // Replace the lines of an env file matching `drop` with `add` (lines, no newlines). The file is
 // mode 600, and never readable by anyone else, even briefly: it is written aside at 600, then
 // renamed over the old one.
@@ -299,22 +397,86 @@ export function addName(host, { root = ROOT, state } = {}) {
   if (!lines(p.names).includes(host)) appendFileSync(p.names, `${host}\n`);
 }
 
-// The PDSes' admin password: SG_PDS_ADMIN_PASSWORD from the environment or .env (a globe on the
-// cluster has its own), else the one up made for this snowglobe in its admin.env; '' when neither.
-export function adminPassword({ root = ROOT, state, env = process.env } = {}) {
-  return setting('SG_PDS_ADMIN_PASSWORD', { root, env }) || (state ? envGet('SG_PDS_ADMIN_PASSWORD', paths(root, state).admin) : '');
-}
+// The secrets a snowglobe's services start with: the PDSes' admin password, JWT secret and PLC
+// rotation key, the relay's admin password and the PLC database's. `up` makes each one random,
+// once, per snowglobe (ensureSecrets); the compose files take them as ${SG_...:?}, so none has a
+// default. `bytes` is how many random bytes (the rotation key is a 32-byte secp256k1 key).
+// `legacy` is the fixed value every snowglobe used before they were random: a snowglobe whose data
+// was made under it keeps it, because Postgres keeps the password it was first started with and
+// a DID's PLC record names the rotation key that made it. The admin password was never fixed.
+export const SECRETS = {
+  SG_PDS_ADMIN_PASSWORD: { bytes: 24 },
+  SG_PDS_JWT_SECRET: { bytes: 24, legacy: 'devnet-jwt-secret-not-for-production' },
+  SG_PLC_ROTATION_KEY: { bytes: 32, legacy: '0123456789abcdef'.repeat(4) },
+  SG_RELAY_ADMIN_PASSWORD: { bytes: 24, legacy: 'devnet-relay-admin' },
+  SG_DB_PASSWORD: { bytes: 24, legacy: 'postgres' },
+};
 
-// adminPassword, made first when there is none: 24 random bytes, kept in admin.env (mode 600) so
-// the same one is used on every later up and read by account and invite. Never printed.
-export function ensureAdminPassword({ root = ROOT, state, env = process.env } = {}) {
-  const have = adminPassword({ root, state, env });
-  if (have) return have;
+// A secret's value: the environment's or .env's (a globe on the cluster has its own), else the
+// one up made for this snowglobe in its secrets.env (for the admin password, else its older admin.env); '' when none.
+export function secret(name, { root = ROOT, state, env = process.env } = {}) {
+  const set = setting(name, { root, env });
+  if (set || !state) return set || '';
   const p = paths(root, state);
-  mkdirSync(p.data, { recursive: true });
-  const password = randomBytes(24).toString('hex');
-  envPut(loginsFile(p.admin), /^SG_PDS_ADMIN_PASSWORD=/, [`SG_PDS_ADMIN_PASSWORD=${password}`]);
-  return password;
+  // The admin password up made before secrets.env existed is still the snowglobe's: its PDSes
+  // were started with it, so it is kept, not replaced by a new one.
+  return envGet(name, p.secrets) || (name === 'SG_PDS_ADMIN_PASSWORD' ? envGet(name, p.admin) : '');
+}
+
+export const adminPassword = (opts) => secret('SG_PDS_ADMIN_PASSWORD', opts);
+
+/**
+ * Every secret in SECRETS, made first where there is none: random, and kept in secrets.env (mode
+ * 600) so the same one is used on every later up. Where the snowglobe already has data (`hasData()`
+ * is true, asked only when a secret that used to be fixed is missing; null, Docker could not say, is refused) a secret that used to be fixed keeps its fixed
+ * value instead. Returns { values, kept }: each secret's value, and the names that kept a fixed
+ * one. A value set in the environment or .env is used and not written. Never prints a value.
+ */
+export function ensureSecrets({ root = ROOT, state, env = process.env, hasData = () => false } = {}) {
+  const values = {};
+  const kept = [];
+  const made = [];
+  let data;
+  for (const [name, { bytes, legacy }] of Object.entries(SECRETS)) {
+    let value = secret(name, { root, state, env });
+    if (!value) {
+      // Only a secret that used to be fixed depends on whether there is data; the answer is asked once.
+      if (legacy !== undefined && data === undefined) {
+        data = hasData();
+        if (data === null) throw new Error('Docker did not say whether this snowglobe already has data (docker volume ls failed), so up will not choose its secrets yet: start Docker, then run up again');
+      }
+      if (legacy !== undefined && data) {
+        value = legacy;
+        kept.push(name);
+      } else value = randomBytes(bytes).toString('hex');
+      made.push(name);
+    }
+    values[name] = value;
+  }
+  if (made.length) {
+    const p = paths(root, state);
+    mkdirSync(p.data, { recursive: true });
+    envPut(loginsFile(p.secrets), new RegExp(`^(${made.join('|')})=`), made.map((n) => `${n}=${values[n]}`));
+  }
+  return { values, kept };
+}
+
+/** Whether Docker holds volumes for the compose project: null when Docker cannot say, which is not an answer to act on. */
+export function projectHasData(project, env = process.env) {
+  const res = spawnSync('docker', ['volume', 'ls', '-q', '--filter', `label=com.docker.compose.project=${project}`], { encoding: 'utf8', env });
+  return res.error || res.status !== 0 ? null : res.stdout.trim() !== '';
+}
+
+/**
+ * After `down -v`, the fixed secrets (SECRETS' legacy values) are dropped from secrets.env: the
+ * data they were kept for is gone, so the next up makes random ones. Random ones stay, and a
+ * secret set in the environment or .env is not in the file.
+ */
+export function dropLegacySecrets({ root = ROOT, state } = {}) {
+  const file = paths(root, state).secrets;
+  if (!existsSync(file)) return;
+  const old = Object.entries(SECRETS).filter(([n, { legacy }]) => legacy !== undefined && envGet(n, file) === legacy).map(([n]) => n);
+  if (old.length) envPut(file, new RegExp(`^(${old.join('|')})=`));
 }
 
 // docker compose on `project` with the rendered globe. Its paths are from the repo root, which is
@@ -326,15 +488,15 @@ export function dc(project, args, { root = ROOT, state, stdio = 'inherit', encod
     const old = oldDataNotice(root, state);
     throw new Error(`No ${p.compose}: run snowglobe up, which renders it${old ? `\n${old}` : ''}`);
   }
-  // compose fills ${SG_PDS_ADMIN_PASSWORD} in the file from this, and refuses to read the file
-  // without it. up makes the real one first; down and ps on a snowglobe from before it have none,
-  // and need only a value for compose to read the file.
+  // compose fills the file's ${SG_...:?} secrets from these, and refuses to read the file without
+  // them. up makes the real ones first; down and ps on a snowglobe that up has not made them for
+  // need only a value for compose to read the file.
   const base = env ?? process.env;
-  const password = adminPassword({ root, state, env: base }) || 'unset-run-snowglobe-up';
+  const secrets = Object.fromEntries(Object.keys(SECRETS).map((n) => [n, secret(n, { root, state, env: base }) || 'unset-run-snowglobe-up']));
   return spawnSync('docker', ['compose', '-p', project, '--project-directory', root, '-f', p.compose, ...args], {
     stdio,
     encoding,
-    env: { ...base, SG_PDS_ADMIN_PASSWORD: password },
+    env: { ...base, ...secrets, SG_BIND: resolveBind({ root, state, env: base }) },
   });
 }
 
@@ -346,7 +508,7 @@ export function snowglobeRequest(url, { method = 'GET', headers = {}, body, root
   const pub = env.SG_PUBLIC === '1';
   const options = { method, headers };
   if (!pub) {
-    const bind = resolveBind({ root, env });
+    const bind = resolveBind({ root, state, env });
     options.ca = readFileSync(paths(root, state).ca);
     options.lookup = (_host, opts, cb) =>
       opts?.all ? cb(null, [{ address: bind, family: 4 }]) : cb(null, bind, 4);

package/lib/prebuilt.mjs

@@ -0,0 +1,56 @@
+// The images snowglobe builds from its own folders that are also published (scripts/publish-images.mjs),
+// so `up` pulls them where it can and builds only what it cannot. A pulled image is used only when
+// its source label equals the hash of the folder's files in this checkout, so an edited Dockerfile
+// or patch is built, never silently served from the registry.
+
+import { spawnSync } from 'node:child_process';
+import { contextHash } from './render.mjs';
+
+export const REGISTRY = 'ghcr.io/openmeet-team';
+export const SOURCE_LABEL = 'at.snowglobe.source';
+
+// Image name (the part of the compose image before the tag): its folder, and the files its Dockerfile uses.
+export const PUBLISHED = {
+  'snowglobe-slingshot': ['stack/slingshot', ['Dockerfile']],
+  'snowglobe-pdsls': ['stack/pdsls', ['Dockerfile', 'network.patch', 'server.mjs']],
+  'snowglobe-relay': ['stack/relay', ['Dockerfile', 'allow-private-hosts.patch']],
+};
+
+/** The source label an image of this name should carry for the files in `root`. */
+export const sourceHash = (root, name) => contextHash(root, ...PUBLISHED[name]);
+
+const docker = (args) => spawnSync('docker', args, { encoding: 'utf8', stdio: 'pipe' });
+
+/**
+ * Of the rendered compose file's services, those whose image is already here or can be pulled
+ * from the registry with a matching source label. Returns their names; the caller builds the rest.
+ * SG_PREBUILT=0 pulls nothing and uses nothing (an image is then built, as it always was).
+ */
+export function prebuilt({ root, services, env = process.env, run = docker, log = () => {} }) {
+  if (env.SG_PREBUILT === '0') return [];
+  const registry = (env.SG_IMAGE_REGISTRY ?? REGISTRY).replace(/\/$/, '');
+  const label = (ref) => {
+    const r = run(['image', 'inspect', '-f', `{{index .Config.Labels "${SOURCE_LABEL}"}}`, ref]);
+    return r.status === 0 ? r.stdout.trim() : null;
+  };
+  const ready = [];
+  const pulled = [];
+  for (const [service, def] of Object.entries(services)) {
+    const ref = def.build && def.image;
+    const name = ref?.split(':')[0];
+    if (!(name in PUBLISHED)) continue;
+    const want = sourceHash(root, name);
+    if (label(ref) === want) {
+      ready.push(service);
+      continue;
+    }
+    if (!registry) continue;
+    if (run(['pull', '-q', `${registry}/${ref}`]).status !== 0) continue;
+    if (run(['tag', `${registry}/${ref}`, ref]).status === 0 && label(ref) === want) {
+      ready.push(service);
+      pulled.push(service);
+    }
+  }
+  if (pulled.length) log(`Pulled prebuilt images (${pulled.join(' ')})`);
+  return ready;
+}

package/lib/render.mjs

@@ -19,6 +19,7 @@ import { readdirSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
 import { parse, stringify } from 'yaml';
 import { IMAGE_NAMES, RESERVED } from './config.mjs';
+import { lookup, parseValue } from './settings.mjs';
 
 // Every PDS listens on this port inside its own container, and every group host on the other.
 export const PDS_PORT = 3000;
@@ -60,6 +61,18 @@ export function loadBase(root) {
   };
 }
 
+/** TAP's settings from services.tap's map: where it sends events and which collection it follows. */
+function tapSettings(globe) {
+  const t = globe.tap;
+  if (!t) return {};
+  const webhook = t.webhook && parseValue(t.webhook).parts.map((x) => (x.text !== undefined ? x.text : lookup(globe, x.name).value)).join('');
+  return {
+    ...(webhook && { TAP_WEBHOOK_URL: webhook }),
+    ...(t.signal_collection && { TAP_SIGNAL_COLLECTION: t.signal_collection }),
+    ...(t.collection_filters.length && { TAP_COLLECTION_FILTERS: t.collection_filters.join(',') }),
+  };
+}
+
 /**
  * Render a checked globe. stateDir is the snowglobe's state folder (an absolute path): the
  * compose file mounts the CA (in ca/ beside it), the leaf and nginx's routes from it, and init
@@ -103,15 +116,15 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
   services.maildev = {
     ...copy(base.test.maildev),
     ports: [
-      '127.0.0.1:${SG_MAILDEV_WEB_PORT:-1081}:1080',
-      '127.0.0.1:${SG_MAILDEV_SMTP_PORT:-1026}:1025',
+      '${SG_BIND:-127.0.0.1}:${SG_MAILDEV_WEB_PORT:-1081}:1080',
+      '${SG_BIND:-127.0.0.1}:${SG_MAILDEV_SMTP_PORT:-1026}:1025',
     ],
   };
 
   services.plc = {
     ...copy(base.base.plc),
     depends_on: { postgres: healthy },
-    ports: ['127.0.0.1:${SG_PLC_PORT:-2582}:2582'],
+    ports: ['${SG_BIND:-127.0.0.1}:${SG_PLC_PORT:-2582}:2582'],
   };
 
   const pdsBase = base.base.pds;
@@ -254,21 +267,26 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
         JETSTREAM_WS_URL: `${feed.replace(/^http/, 'ws')}/xrpc/com.atproto.sync.subscribeRepos`,
       },
       ports: [
-        '127.0.0.1:${SG_JETSTREAM_PORT:-6008}:6008',
-        '127.0.0.1:${SG_JETSTREAM_METRICS_PORT:-6009}:6009',
+        '${SG_BIND:-127.0.0.1}:${SG_JETSTREAM_PORT:-6008}:6008',
+        '${SG_BIND:-127.0.0.1}:${SG_JETSTREAM_METRICS_PORT:-6009}:6009',
       ],
     };
   }
 
   if (on.tap) {
-    // Resync fetches repos through an SSRF-safe transport, which refuses nginx's address, so
-    // TAP follows the stream but cannot resync a repo here.
+    // TAP runs in tap-dns's network namespace, whose DNS answers every name under the domain with
+    // nginx: so it reaches the webhook's app and checks a handle at its https name. It follows the
+    // stream and finds an account when it writes in the signal collection; its crawl of the
+    // collection's repos is refused by the PDS (HTTP 401) and finds none.
     services.tap = {
       ...copy(base.base.tap),
       depends_on: on.relay ? { relay: healthy } : { [svc(globe.pds[0])]: healthy },
-      environment: { ...copy(base.base.tap.environment), TAP_RELAY_URL: feed },
+      environment: { ...copy(base.base.tap.environment), TAP_RELAY_URL: feed, ...tapSettings(globe) },
       volumes: [...base.base.tap.volumes, GO_CA],
+      network_mode: 'service:tap-dns',
+      depends_on: { 'tap-dns': { condition: 'service_started' }, ...(on.relay ? { relay: healthy } : { [svc(globe.pds[0])]: healthy }) },
     };
+    delete services.tap.networks;
     delete services.tap.ports;
   }
 
@@ -326,6 +344,19 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
     healthcheck: { test: ['CMD', 'nginx', '-t', '-q'], interval: '5s', timeout: '3s', retries: 10 },
   };
 
+  if (on.tap) {
+    services['tap-dns'] = {
+      build: './stack/https/dns',
+      image: base.tags['snowglobe-dns'],
+      restart: 'unless-stopped',
+      environment: { SG_DOMAIN: D },
+      dns: ['127.0.0.1'],
+      depends_on: { nginx: healthy },
+      ports: ['${SG_BIND:-127.0.0.1}:${SG_TAP_PORT:-2480}:2480'],
+      networks: [NETWORK],
+    };
+  }
+
   if (on.slingshot) {
     // Slingshot (microcosm-rs) answers com.bad-example.identity.resolveMiniDoc, a handle's DID
     // and PDS, from this globe's PLC and Jetstream. It reaches the handles' names over TLS,
@@ -377,7 +408,7 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
     restart: 'unless-stopped',
     depends_on: { nginx: healthy },
     environment: { PROXY_DOMAIN: D, PROXY_UPSTREAM: 'nginx:443' },
-    ports: ['127.0.0.1:${SG_PROXY_PORT:-1080}:1080'],
+    ports: ['${SG_BIND:-127.0.0.1}:${SG_PROXY_PORT:-1080}:1080'],
     networks: [NETWORK],
     healthcheck: { test: ['CMD', 'wget', '-q', '-O', '/dev/null', 'http://127.0.0.1:1080/_health'], interval: '5s', timeout: '3s', retries: 10 },
   };
@@ -421,14 +452,14 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
   }
 
   const header = (c) =>
-    `${c} Written by bin/snowglobe.mjs render from ${source}; render again instead of editing.\n`;
+    `${c} Written by snowglobe render from ${source}; render again instead of editing.\n`;
 
   const compose =
     header('#') +
     `# The https globe "${globe.globe}" at ${D}: ${globe.pds.map((p) => p.name).join(', ')}` +
     (globe.grouphosts.length ? `; group hosts ${globe.grouphosts.map((g) => g.name).join(', ')}` : '') +
     '.\n' +
-    '# Run it with bin/snowglobe.mjs up, which renders this file first.\n\n' +
+    '# Run it with snowglobe up, which renders this file first.\n\n' +
     // YAML 1.1 quoting, so a value such as restart's "no" stays a string to compose.
     stringify({ services, volumes, networks: { [NETWORK]: null } }, { lineWidth: 0, nullStr: '', aliasDuplicateObjects: false, version: '1.1' });
 
@@ -483,15 +514,18 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
     const named = Object.entries(IMAGE_NAMES).find(([, ref]) => ref === image)?.[0];
     return named ?? image.split('/').pop().replace(/@sha256:([0-9a-f]{12})[0-9a-f]+$/, '@sha256:$1…');
   };
+  // What the globe is made of, as the page's first line names it: only what runs.
+  const parts = [globe.pds.length === 1 ? 'PDS' : 'PDSs', 'PLC directory', on.relay && 'relay', on.jetstream && 'Jetstream'].filter(Boolean);
   const page = {
     globe: globe.globe,
     domain: D,
     about:
-      'An atproto network on this machine: its own PDSs, PLC directory, relay and Jetstream. Its accounts live in its own directory, not the public one, so Bluesky cannot find anything here. An app is handed this network\'s addresses (snowglobe env), not Bluesky\'s.',
+      `An atproto network on this machine: its own ${parts.slice(0, -1).join(', ')} and ${parts.at(-1)}. Its accounts live in its own directory, not the public one, so Bluesky cannot find anything here. An app is handed this network's addresses (snowglobe env), not Bluesky's.`,
     accountsNote:
       `Every account on the network, on each of its ${globe.pds.length} PDS${globe.pds.length === 1 ? '' : 's'}` +
       (globe.grouphosts.length ? `, and every group on its group host${globe.grouphosts.length === 1 ? '' : 's'}.` : '.'),
-    ...(on.jetstream ? { feed: '/subscribe' } : {}),
+    // Without Jetstream the page has no feed to follow, and says so instead of reconnecting.
+    feed: on.jetstream ? '/subscribe' : false,
     services: [
       ...globe.pds.map((p) => [
         'PDS',

package/lib/settings.mjs

@@ -93,13 +93,13 @@ export function lookup(globe, name, later) {
         slingshot: { url: `https://slingshot.${D}` },
         pdsls: { url: `https://pdsls.${D}` },
         mail: { url: null },
+        tap: { url: null },
       };
-      if (svc === 'tap') return fail('services.tap has no address an app can take (it has no https name)');
       if (!svc || !Object.hasOwn(svcs, svc)) return fail(`${svc ? `services.${svc}` : name} is not a service with an address: ${list(Object.keys(svcs))}`);
       if (field === undefined || more.length || !Object.hasOwn(svcs[svc], field))
         return fail(`${name} is not a value of services.${svc}; it has ${list(Object.keys(svcs[svc]).map((f) => `services.${svc}.${f}`))}`);
       if (svc !== 'plc' && svc !== 'mail' && !globe.services[svc]) return fail(`services.${svc} is off in this file, so it has no address`);
-      return svc === 'mail' ? after() : { value: svcs[svc][field] };
+      return svc === 'mail' || svc === 'tap' ? after() : { value: svcs[svc][field] };
     }
     case 'accounts': {
       if (rest.length === 1 && rest[0] === 'file') return after();
@@ -130,6 +130,16 @@ export function lookup(globe, name, later) {
 /** The problems with the names in every apps[].env of `globe`, as [where, message] pairs. */
 export function checkSettings(globe) {
   const problems = [];
+  if (globe.tap?.webhook) {
+    const { parts, error } = parseValue(globe.tap.webhook);
+    if (error) problems.push(['services.tap.webhook', error]);
+    else
+      for (const part of parts) {
+        const found = part.name && lookup(globe, part.name);
+        if (found?.error) problems.push(['services.tap.webhook', found.error]);
+        else if (found?.later) problems.push(['services.tap.webhook', `${part.name} is known only after snowglobe up, so Tap cannot be given it`]);
+      }
+  }
   globe.apps.forEach((app, i) => {
     for (const [key, text] of Object.entries(app.env)) {
       const at = `apps[${i}].env.${key}`;

package/lib/state.mjs

@@ -5,7 +5,7 @@
 // folder records which file owns it, so two files that say `globe: t1` cannot share one folder,
 // or one compose project.
 
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { globeName } from './config.mjs';
 import { ROOT, stateRoot } from './env.mjs';
@@ -35,6 +35,40 @@ export function findFile({ file, env = process.env, cwd = process.cwd(), allowDe
 // The file that owns a state folder is recorded here, as an absolute path.
 const OWNER = 'owner';
 
+/** The file recorded as owning the state folder `state`, or '' when none is. */
+export function ownerOf(state) {
+  const record = join(state, OWNER);
+  return existsSync(record) ? readFileSync(record, 'utf8').trim() : '';
+}
+
+/**
+ * The file `up` or `down` was pointed at, from its -f option and its one word, which is a file
+ * or the name of a snowglobe (snowglobe ls shows them): { file } for a file, { name } for a
+ * snowglobe, {} for neither given (the file found from the folder you are in). A word that is a
+ * file that exists is that file; else it is a name when a state folder is called that. Throws
+ * when it is neither, or both -f and a word are given.
+ */
+export function pointedAt({ file, word, env = process.env } = {}) {
+  if (file && word) throw new Error(`give the snowglobe once: -f ${file} or ${word}, not both`);
+  if (file) return { file };
+  if (!word) return {};
+  if (existsSync(word) && statSync(word).isFile()) return { file: word };
+  if (!/[\\/]/.test(word) && existsSync(join(stateRoot(env), word))) return { name: word };
+  throw new Error(`${word} is not a file, and no snowglobe is called that (snowglobe ls lists them)`);
+}
+
+/**
+ * The snowglobe called `name`, as session returns it, for a command that stops or reads one
+ * without its file: `path` is the file recorded as its owner, '' when that file is gone. Throws
+ * when no state folder has the name.
+ */
+export function byName(name, { env = process.env } = {}) {
+  const state = join(stateRoot(env), name);
+  if (!existsSync(state)) throw new Error(`no snowglobe is called ${name} (snowglobe ls lists them)`);
+  const owner = ownerOf(state);
+  return { path: owner && existsSync(owner) ? owner : '', name, state, project: env.SG_PROJECT || name };
+}
+
 /**
  * Refuse a state folder whose recorded owner is another file that still exists. With `claim`, a
  * folder with no owner, or whose owner is gone (moved or deleted), is recorded as this file's.
@@ -43,7 +77,7 @@ function owned({ name, state }, file, claim) {
   // Returns a line to tell the user when a file took over a name whose first file is gone.
   const mine = realpathSync(resolve(file));
   const record = join(state, OWNER);
-  const first = existsSync(record) ? readFileSync(record, 'utf8').trim() : '';
+  const first = ownerOf(state);
   if (first && first !== mine && existsSync(first))
     throw new Error(
       `the snowglobe ${name} belongs to ${first} (its state is in ${state}), and ${mine} also says globe: ${name}. ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmeet/snowglobe",
-  "version": "0.3.0-rc.0",
+  "version": "0.3.0",
   "description": "Standalone, testable ATProto development network for local development and CI",
   "type": "module",
   "bin": {

package/snowglobe.default.yml

@@ -1,8 +1,11 @@
 # The default snowglobe: one current PDS, a PLC directory and Jetstream, all at https names, with
 # Slingshot and PDSls (the record browser) beside them.
-# Copy this file to snowglobe.yml (here, or in your app's repo) and run bin/snowglobe.mjs up.
-# The commented sections below add more; docs/snowglobe.md says what each one does, and
-# docs/examples/atmo.yml is the whole thing: three PDSes, a relay and a lexicon authority.
+# Copy this file to snowglobe.yml (here, or in your app's repo) and run snowglobe up
+# (bin/snowglobe.mjs up from a checkout of snowglobe). The commented sections below add more.
+# What each one does:
+#   https://github.com/OpenMeet-Team/snowglobe/blob/main/docs/snowglobe.md
+# The whole thing, three PDSes, a relay and a lexicon authority:
+#   https://github.com/OpenMeet-Team/snowglobe/blob/main/docs/examples/atmo.yml
 
 globe: snowglobe
 domain: local.snowglobe.at     # every name below is under it
@@ -26,7 +29,7 @@ services:                      # these are the defaults, each true or false
   jetstream: true
   slingshot: true              # answers a handle's DID and PDS inside the network; needs jetstream
   pdsls: true                  # https://pdsls.local.snowglobe.at, a browser for the network's records
-  tap: false                   # syncs and backfills repos for an app that attaches to it
+  tap: false                   # sends an app the events of one collection (true, or a map; see snowglobe.md above)
   # relay: auto                # auto: on when there is more than one PDS
 
 # Where every PDS resolves lexicons (NSIDs) from. Name a PDS that is in this file.
@@ -45,7 +48,8 @@ accounts:                      # <name>@<pds>; up makes each one
   - bob@main
 
 # Your app, reached at https://myapp.app.local.snowglobe.at, with settings from the snowglobe.
-# `snowglobe env` hands them over; docs/your-app.md has the names.
+# `snowglobe env` hands them over. The names:
+#   https://github.com/OpenMeet-Team/snowglobe/blob/main/docs/your-app.md
 # apps:
 #   - name: myapp
 #     local: { port: 5173 }

package/stack/docker-compose.relay.yml

@@ -14,7 +14,7 @@
 # A relay only adds localhost hosts through its admin API, so a PDS cannot register
 # itself with requestCrawl. relay-init adds each PDS once the relay is up.
 
-x-relay-admin-password: &relay-admin-password ${SG_RELAY_ADMIN_PASSWORD:-${DEVNET_RELAY_ADMIN_PASSWORD:-devnet-relay-admin}}
+x-relay-admin-password: &relay-admin-password ${SG_RELAY_ADMIN_PASSWORD:?snowglobe up makes it}
 
 services:
   pds:

package/stack/docker-compose.test.yml

@@ -9,7 +9,7 @@ services:
     restart: unless-stopped
     environment:
       POSTGRES_USER: ${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}
-      POSTGRES_PASSWORD: ${SG_DB_PASSWORD:-${DEVNET_DB_PASSWORD:-postgres}}
+      POSTGRES_PASSWORD: ${SG_DB_PASSWORD:?snowglobe up makes it}
       POSTGRES_DB: ${SG_DB_NAME:-${DEVNET_DB_NAME:-plc}}
     ports:
       - "${SG_POSTGRES_PORT:-${DEVNET_POSTGRES_PORT:-5433}}:5432"

package/stack/docker-compose.yml

@@ -25,11 +25,11 @@ services:
     environment:
       PORT: 2582
       DEVNET_DB_USER: ${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}
-      DEVNET_DB_PASSWORD: ${SG_DB_PASSWORD:-${DEVNET_DB_PASSWORD:-postgres}}
+      DEVNET_DB_PASSWORD: ${SG_DB_PASSWORD:?snowglobe up makes it}
       DEVNET_DB_HOST: ${SG_DB_HOST:-${DEVNET_DB_HOST:-postgres}}
       DEVNET_DB_PORT: ${SG_DB_PORT:-${DEVNET_DB_PORT:-5432}}
       DEVNET_DB_NAME: ${SG_DB_NAME:-${DEVNET_DB_NAME:-plc}}
-      DATABASE_URL: "postgres://${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}:${SG_DB_PASSWORD:-${DEVNET_DB_PASSWORD:-postgres}}@${SG_DB_HOST:-${DEVNET_DB_HOST:-postgres}}:${SG_DB_PORT:-${DEVNET_DB_PORT:-5432}}/${SG_DB_NAME:-${DEVNET_DB_NAME:-plc}}"
+      DATABASE_URL: "postgres://${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}:${SG_DB_PASSWORD:?snowglobe up makes it}@${SG_DB_HOST:-${DEVNET_DB_HOST:-postgres}}:${SG_DB_PORT:-${DEVNET_DB_PORT:-5432}}/${SG_DB_NAME:-${DEVNET_DB_NAME:-plc}}"
       ENABLE_MIGRATIONS: "true"
       LOG_ENABLED: "true"
       LOG_LEVEL: info
@@ -78,8 +78,8 @@ services:
       PDS_DISABLE_SSRF_PROTECTION: "true"
       PDS_INVITE_REQUIRED: "true"
       PDS_ADMIN_PASSWORD: ${SG_PDS_ADMIN_PASSWORD:?snowglobe up makes it}
-      PDS_JWT_SECRET: devnet-jwt-secret-not-for-production
-      PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+      PDS_JWT_SECRET: ${SG_PDS_JWT_SECRET:?snowglobe up makes it}
+      PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX: ${SG_PLC_ROTATION_KEY:?snowglobe up makes it}
       PDS_EMAIL_SMTP_URL: ${SG_SMTP_URL:-${DEVNET_SMTP_URL:-smtp://maildev:1025}}
       PDS_EMAIL_FROM_ADDRESS: noreply@devnet.test
       PDS_HANDLE_DOMAINS: ${SG_HANDLE_DOMAIN:-${DEVNET_HANDLE_DOMAIN:-.devnet.test}}
@@ -124,7 +124,8 @@ services:
 
   # ── TAP (repo sync + backfill) ───────────────────────────────────
   tap:
-    image: ghcr.io/bluesky-social/indigo/tap:latest
+    # Pinned by digest (indigo revision 4f47add4, built 2026-03-11): the one the Statusphere flow was run against.
+    image: ghcr.io/bluesky-social/indigo/tap@sha256:5e20bfe416d29fcd215ed8bf99f10b2ab825a6de4e5599846dd33967ade2abeb
     restart: unless-stopped
     depends_on:
       pds:

package/stack/https/nginx.conf.template

@@ -96,7 +96,7 @@ server {
     listen 443 ssl;
     server_name *.app.${SG_DOMAIN};
     if ($snowglobe_app = "") {
-        return 404 "No app is registered at $host (bin/snowglobe.mjs app).\n";
+        return 404 "No app is registered at $host (snowglobe app).\n";
     }
     location / {
         proxy_pass http://$snowglobe_app;

package/stack/page/index.html

@@ -233,7 +233,8 @@
     if (tally.people != null) parts.push(plural(tally.people, "person", "people"));
     if (tally.groups) parts.push(plural(tally.groups, "group", "groups"));
     var line = parts.length ? parts.join(" and ") + ". " : "";
-    document.getElementById("tally").textContent = line + plural(tally.writes, "write", "writes") + " in the last 24 hours.";
+    // writes is null on a network with no feed to count them from.
+    document.getElementById("tally").textContent = line + (tally.writes == null ? "" : plural(tally.writes, "write", "writes") + " in the last 24 hours.");
   }
 
   function health(domain, services) {
@@ -380,6 +381,15 @@
     connect();
   }
 
+  // A network with no Jetstream has no feed: the panel says so instead of reconnecting forever.
+  function noActivity() {
+    document.getElementById("stream").style.display = "none";
+    document.getElementById("count").parentNode.style.display = "none";
+    var body = document.getElementById("events");
+    body.textContent = "";
+    add(body, el("p", { "class": "empty" }, "This network runs no Jetstream, so its writes are not followed here."));
+  }
+
   getJSON("/snowglobe.json").then(function (g) {
     document.title = g.globe + " · Snowglobe network";
     document.getElementById("title").textContent = g.globe;
@@ -396,12 +406,14 @@
     }
     if (g.about) document.getElementById("about").textContent = g.about;
     if (g.accountsNote) document.getElementById("accounts-note").textContent = g.accountsNote;
-    var feed = g.feed || "wss://jetstream." + g.domain + "/subscribe";
-    if (feed.charAt(0) === "/") feed = "wss://" + location.host + feed;
+    // feed false: the network runs no Jetstream. Unset, Jetstream is at its usual public name.
+    var feed = g.feed === false ? null : g.feed || "wss://jetstream." + g.domain + "/subscribe";
+    if (feed && feed.charAt(0) === "/") feed = "wss://" + location.host + feed;
+    if (!feed) { tally.writes = null; noActivity(); }
     showTally();
     health(g.domain, g.services || SERVICES);
     // The feed names accounts by handle, so it waits for the account list.
-    accounts(g.accounts || ACCOUNTS).catch(function () {}).then(function () { activity(feed); });
+    accounts(g.accounts || ACCOUNTS).catch(function () {}).then(function () { if (feed) activity(feed); });
   });
 })();
 </script>