@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/infrastructure/service-resolver.js

@@ -7,29 +7,134 @@
  * Into concrete Docker container definitions:
  *   { name: 'omnitron-postgres', image: 'postgres:17-alpine', ports: [...], env: [...] }
  */
-/**
- * Container naming: {project}-{stack}-{service}
- * Examples: myproj-dev-postgres, myproj-dev-redis, myproj-test-minio
- * Omnitron's own containers: omnitron-pg, omnitron-nginx (no project/stack prefix)
- *
- * Docker labels for stack grouping (Docker Desktop groups containers visually):
- *   com.docker.compose.project = omnitron-{project}-{stack}
- *   com.docker.compose.service = {service}
- *   omnitron.project = {project}
- *   omnitron.stack = {stack}
- */
+import fs from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { configFilesHash } from './config-payload.js';
+import { gatewayStaticLinkName } from '../services/static-carry-forward.js';
+import { CONFIG_ROOT_PREFIX, shippedMountPath } from './shipped-config.js';
+import { bindService } from './service-binding.js';
+const infrastructureScopes = new AsyncLocalStorage();
 let CONTAINER_PREFIX = 'omnitron';
+/** Concurrent operations own their names/networks/volumes; ownerless work starts clean. */
+export function withInfrastructureScope(project, stack, work) {
+    if ((project === undefined) !== (stack === undefined))
+        throw new Error('Infrastructure ownership requires project and stack together');
+    const labels = project === undefined
+        ? {}
+        : {
+            'omnitron.project': project,
+            'omnitron.stack': stack,
+            'com.docker.compose.project': `omnitron-${project}-${stack}`,
+        };
+    return infrastructureScopes.run({ prefix: project === undefined ? 'omnitron' : `${project}-${stack}`, labels }, work);
+}
 /** Set the container prefix for project-scoped infrastructure */
 export function setContainerPrefix(project, env) {
-    CONTAINER_PREFIX = `${project}-${env}`;
+    const scope = infrastructureScopes.getStore();
+    if (scope)
+        scope.prefix = `${project}-${env}`;
+    else
+        CONTAINER_PREFIX = `${project}-${env}`;
 }
 /** Get current prefix */
 export function getContainerPrefix() {
-    return CONTAINER_PREFIX;
+    return infrastructureScopes.getStore()?.prefix ?? CONTAINER_PREFIX;
+}
+/**
+ * A named volume two services of one stack mount by the same name:
+ * `source: 'shared:gateway-socket'` is `<prefix>-gateway-socket` wherever it
+ * is declared.
+ *
+ * Every other named volume is its service's — `<prefix>-<service>-<key>`,
+ * whatever its `source` says — so nothing a stack could write gave two
+ * containers one volume. The onion needed exactly that: Tor resolved
+ * `sample-test-gateway` once, at start, and on 2026-09-26 a deploy gave the
+ * gateway's old address to Nominatim; for ~10 minutes the onion served
+ * Nominatim's Apache and nobody could sign in. A unix socket on a volume
+ * both containers mount has no address to go stale.
+ */
+export const SHARED_VOLUME_PREFIX = 'shared:';
+/** A declared volume as docker mounts it for `service`: shared, bound, or the service's own. */
+function resolveNamedOrBound(service, key, vol) {
+    if (typeof vol === 'string')
+        return { source: `${getContainerPrefix()}-${service}-${key}`, target: vol };
+    const shared = vol.source.startsWith(SHARED_VOLUME_PREFIX) ? vol.source.slice(SHARED_VOLUME_PREFIX.length) : null;
+    if (shared !== null && !/^[a-z0-9][a-z0-9_.-]*$/.test(shared)) {
+        // Docker would refuse the name anyway; saying which declaration it was is
+        // the useful part.
+        throw new Error(`Volume "${key}" of ${service}: "${vol.source}" does not name a shared volume (lower-case letters, digits, «_.-»)`);
+    }
+    const isBindMount = vol.source.startsWith('/') || vol.source.startsWith('.');
+    const entry = {
+        source: shared !== null
+            ? `${getContainerPrefix()}-${shared}`
+            : isBindMount
+                ? vol.source
+                : `${getContainerPrefix()}-${service}-${key}`,
+        target: vol.target,
+    };
+    if (vol.readonly)
+        entry.readonly = vol.readonly;
+    return entry;
+}
+/**
+ * Where to PUBLISH the gateway, which is not where it listens.
+ *
+ * After preset expansion `ports` holds CONTAINER ports — openresty's
+ * `defaultPorts.http` is 80, because that is what the image listens on — and
+ * a port named in the config becomes a HOST mapping under
+ * `docker.portMappings`. Reading `ports.http` takes the first for the second,
+ * so a stack asking for 8080 gets a gateway published on 80.
+ *
+ * Measured on the dev stand: `omnitron.config.ts` declares
+ * `gateway.ports.http = 8080` and its own comment says ":8080" three times,
+ * while `sample-dev-gateway` published `80/tcp -> 0.0.0.0:80`. The consequence
+ * is quiet rather than loud — a browser arriving on :80 sends
+ * `Origin: http://localhost` with no port, which is not in the gateway's
+ * allow-list, so the portal cannot call the API through it at all. The portal
+ * is reachable on 7080, so nothing complained.
+ *
+ * `resolveServiceRequirement` has read it correctly all along:
+ * `host: docker.portMappings?.[name] ?? containerPort`. Same expression here,
+ * because it is the same question — and a port the preset does not declare
+ * really is a container port, which is why the fallback is not a mistake.
+ */
+export function gatewayHostPort(service, legacy) {
+    return service?.docker?.portMappings?.['http'] ?? service?.ports?.['http'] ?? legacy?.port ?? 8080;
 }
 function containerName(service) {
-    return `${CONTAINER_PREFIX}-${service}`;
+    return `${getContainerPrefix()}-${service}`;
 }
+/**
+ * How one managed container reaches another.
+ *
+ * Every container omnitron provisions joins the stack's named network, and
+ * the network exists so they can address each other by name — the comment on
+ * `networkName` below says exactly that. The gateway did not: it was given
+ * `host.docker.internal` and the HOST-published port, and went out to the
+ * host and back.
+ *
+ * That works on a developer's Mac, where `host.docker.internal` reaches the
+ * host's loopback. It cannot work on a Linux node, where `host-gateway`
+ * resolves to the docker0 bridge address and omnitron publishes every managed
+ * port on `127.0.0.1` — deliberately, so a container is not reachable from
+ * the LAN. Measured on the test node: the gateway sat on 172.19.0.2, redis on
+ * 172.19.0.4 of the same network, and every request the gateway served spent
+ * 200ms on `lua tcp socket connect timed out, upstream: 172.17.0.1:6379`
+ * before failing open. The hardening that bound the ports closed this path,
+ * and the only evidence was a warning nobody was reading.
+ *
+ * The port is the CONTAINER port for the same reason the host is a container
+ * name: a stack whose redis is published on 6380 still listens on 6379
+ * inside. Host and port are one decision and are answered here together,
+ * because answering half of it is how a correct name ends up on the wrong
+ * port.
+ */
+export function containerEndpoint(service, containerPort) {
+    return { host: containerName(service), port: containerPort };
+}
+/** Redis, as a container on the stack network sees it. */
+export const REDIS_CONTAINER_PORT = 6379;
 /**
  * Convention-derived managed network name.
  *
@@ -55,7 +160,7 @@ function containerName(service) {
  * adjacent infrastructure.
  */
 export function getManagedNetwork() {
-    return `${CONTAINER_PREFIX}_default`;
+    return `${getContainerPrefix()}_default`;
 }
 /**
  * Stamp the managed network onto a container spec when it doesn't already
@@ -65,6 +170,32 @@ export function getManagedNetwork() {
 export function applyManagedDefaults(spec) {
     if (spec.network === undefined)
         spec.network = getManagedNetwork();
+    // Published ports bind to loopback unless a container asks otherwise.
+    //
+    // Docker's default is every interface, and Docker's iptables rules are
+    // inserted ahead of ufw's — so a published port is reachable from the
+    // internet no matter what the host firewall says. Measured on the test
+    // server, whose ufw allows 22/tcp and nothing else:
+    //
+    //     nc -vz 37.27.130.185 9700   → timed out (ufw, as configured)
+    //     nc -vz 37.27.130.185 5480   → OPEN      (docker, straight past it)
+    //
+    // 5480 is omnitron's own Postgres. An operator who reads their firewall
+    // rules and concludes the database is private is reading a control that
+    // does not cover it, which is the worst kind of wrong: a check that
+    // answers confidently about something it cannot see.
+    //
+    // The applications that use these containers run on the same host and
+    // reach them over loopback. Anything further away comes through
+    // omnitron's own transport, which is authenticated. So the default costs
+    // nothing and the exposure had no beneficiary.
+    //
+    // A container that genuinely must be reachable says so by setting
+    // `bindHost` — a deliberate line in a config, reviewable in a diff.
+    for (const port of spec.ports ?? []) {
+        if (port.bindHost === undefined)
+            port.bindHost = '127.0.0.1';
+    }
     return spec;
 }
 /**
@@ -75,20 +206,29 @@ export function applyManagedDefaults(spec) {
 let STACK_LABELS = {};
 /** Set stack labels for subsequent container creation calls */
 export function setStackLabels(project, stack) {
-    STACK_LABELS = {
+    const labels = {
         'omnitron.project': project,
         'omnitron.stack': stack,
         // Docker Desktop groups containers by com.docker.compose.project label
         'com.docker.compose.project': `omnitron-${project}-${stack}`,
     };
+    const scope = infrastructureScopes.getStore();
+    if (scope)
+        scope.labels = labels;
+    else
+        STACK_LABELS = labels;
 }
 /** Clear stack labels (for internal/global containers) */
 export function clearStackLabels() {
-    STACK_LABELS = {};
+    const scope = infrastructureScopes.getStore();
+    if (scope)
+        scope.labels = {};
+    else
+        STACK_LABELS = {};
 }
 /** Get current stack labels */
 function stackLabels() {
-    return { ...STACK_LABELS };
+    return { ...(infrastructureScopes.getStore()?.labels ?? STACK_LABELS) };
 }
 // =============================================================================
 // Service Requirement → ResolvedContainer (generic resolver for ALL services)
@@ -102,47 +242,111 @@ function stackLabels() {
  * - Service is disabled by stack override
  * - Stack override provides an external address
  */
-export function resolveServiceRequirement(serviceName, requirement, override, appName) {
-    // Skip disabled or external services
-    if (override?.disabled)
-        return null;
-    if (override?.external)
+/**
+ * An HTTP probe that works in the image it runs in.
+ *
+ * `curl -sf` was the generic form, and alpine-based images do not ship curl.
+ * Measured on the gateway: `/bin/sh: curl: not found`, exit 1, every ten
+ * seconds forever — a container serving traffic correctly (the onion in
+ * front of it answered 200) reported `unhealthy` for its whole life, and
+ * `provisionStack` reported the stack NOT ready because of it.
+ *
+ * The lesson was already learned once in this file: `resolveOmnitronNginx`
+ * uses wget with a comment saying curl is not in the image. It was learned
+ * for one container and not for the generic path every other service takes.
+ *
+ * Tries curl, then wget, then falls back to failing. Both spellings, because
+ * busybox wget and GNU wget disagree about flags but agree about these:
+ * `-q` quiet, `-O -` to stdout, `-T` timeout.
+ */
+/**
+ * Which port an HTTP health check should knock on.
+ *
+ * The probe was `http://localhost<path>` — port 80, always. The gateway
+ * listens on 8080, so the check connected to nothing:
+ *
+ *     wget: can't connect to remote host: Connection refused
+ *
+ * on a container that was serving correctly on its own port, through an
+ * onion address that answered 200. Every service whose port is not 80 had
+ * an unanswerable health check, and an unanswerable check is a permanent
+ * negative — `provisionStack` reported the stack not ready because of it.
+ *
+ * A check may name its port, as the jsonrpc one already does. Otherwise the
+ * service's own: `http` by convention, then whatever single port it
+ * declares — a service with one port cannot mean another.
+ */
+function healthPort(check, ports) {
+    const named = check.port;
+    if (named && ports?.[named])
+        return ports[named];
+    if (ports?.['http'])
+        return ports['http'];
+    const declared = Object.values(ports ?? {});
+    if (declared.length === 1)
+        return declared[0];
+    // Several ports and no way to choose: 80 is the convention, and saying so
+    // here is better than an arbitrary pick that happens to work once.
+    return 80;
+}
+function httpProbe(url) {
+    return (`curl -sf --max-time 5 ${url} >/dev/null 2>&1 ` +
+        `|| wget -q -O /dev/null -T 5 ${url} >/dev/null 2>&1 ` +
+        '|| exit 1');
+}
+export function resolveServiceRequirement(serviceName, requirement, override, appName, 
+/** Where each service's shipped config directory is on THIS machine — see `shipped-config.ts`. */
+configRoots) {
+    // A container only for a service this stack runs as one — not one it
+    // disables, reaches elsewhere, or runs on the node as a system service
+    // (`bindService`).
+    const binding = bindService(requirement, override);
+    if (binding.provisioning !== 'docker')
         return null;
     const baseDocker = requirement.docker;
     if (!baseDocker)
-        return null; // No Docker config = external-only
+        return null;
     // Deep-merge: base → networkMode variant → stack override
     let docker = { ...baseDocker };
-    if (requirement.networkMode && baseDocker.variants?.[requirement.networkMode]) {
-        docker = deepMergeDocker(docker, baseDocker.variants[requirement.networkMode]);
+    // The stack's answer first: an application declares the network that is
+    // right on a laptop, and a stack is the scope that knows when it is not.
+    const networkMode = override?.networkMode ?? requirement.networkMode;
+    if (networkMode && baseDocker.variants?.[networkMode]) {
+        docker = deepMergeDocker(docker, baseDocker.variants[networkMode]);
     }
     if (override?.docker) {
         docker = deepMergeDocker(docker, override.docker);
     }
     // Resolve image
     const image = docker.image ?? docker.build?.tag ?? `${serviceName}:latest`;
-    // Map ports: requirement.ports defines container ports, docker.portMappings overrides host ports
-    const ports = Object.entries(requirement.ports).map(([name, containerPort]) => ({
+    // The ports the service listens on in this stack's network are the
+    // container's (`bindService`); `docker.portMappings` says where each is published.
+    const ports = Object.entries(binding.ports).map(([name, containerPort]) => ({
         host: docker.portMappings?.[name] ?? containerPort,
         container: containerPort,
     }));
     // Resolve volumes
+    const shippedRoots = new Set();
     const volumes = Object.entries(docker.volumes ?? {}).map(([name, vol]) => {
-        if (typeof vol === 'string') {
-            return { source: `${CONTAINER_PREFIX}-${serviceName}-${name}`, target: vol };
+        if (typeof vol !== 'string' && vol.source.startsWith(CONFIG_ROOT_PREFIX)) {
+            // The node's copy of a directory the master shipped. Unresolved — no
+            // copy arrived — it stays as it is, and docker refuses it by name.
+            const local = shippedMountPath(vol.source, configRoots);
+            if (local)
+                shippedRoots.add(local.root);
+            const entry = {
+                source: local?.path ?? vol.source,
+                target: vol.target,
+            };
+            if (vol.readonly)
+                entry.readonly = vol.readonly;
+            return entry;
         }
-        const isBindMount = vol.source.startsWith('/') || vol.source.startsWith('.');
-        const entry = {
-            source: isBindMount ? vol.source : `${CONTAINER_PREFIX}-${serviceName}-${name}`,
-            target: vol.target,
-        };
-        if (vol.readonly)
-            entry.readonly = vol.readonly;
-        return entry;
+        return resolveNamedOrBound(serviceName, name, vol);
     });
     // Convert IServiceHealthCheck → ContainerHealthCheck
-    const healthCheck = docker.healthCheck ?? convertHealthCheck(requirement.healthCheck, requirement.ports);
-    return applyManagedDefaults({
+    const healthCheck = docker.healthCheck ?? convertHealthCheck(requirement.healthCheck, binding.ports);
+    const spec = applyManagedDefaults({
         name: containerName(serviceName),
         image,
         ports,
@@ -170,12 +374,25 @@ export function resolveServiceRequirement(serviceName, requirement, override, ap
         // stamps in the project-wide bridge.
         ...(typeof docker.network === 'string' ? { network: docker.network } : {}),
     });
+    // The content of what it mounts from shipped directories, so a changed
+    // script recreates the container — the same reason as the gateway's.
+    for (const root of shippedRoots) {
+        const digest = mountedConfigDigest(root, spec.volumes);
+        if (digest)
+            spec.configDigest = spec.configDigest
+                ? configFilesHash([
+                    { path: 'a', content: spec.configDigest, mode: '644' },
+                    { path: 'b', content: digest, mode: '644' },
+                ])
+                : digest;
+    }
+    return spec;
 }
 /**
  * Resolve all app-declared infrastructure services into ResolvedContainer[].
  * Respects dependsOn ordering — dependencies come first.
  */
-export function resolveAppInfrastructure(infrastructure, overrides, appName) {
+export function resolveAppInfrastructure(infrastructure, overrides, appName, configRoots) {
     const containers = [];
     const resolved = new Set();
     const pending = new Map(Object.entries(infrastructure));
@@ -191,7 +408,7 @@ export function resolveAppInfrastructure(infrastructure, overrides, appName) {
                 resolve(dep, depReq);
         }
         const override = overrides?.[`${appName}/${name}`] ?? overrides?.[name];
-        const container = resolveServiceRequirement(name, req, override, appName);
+        const container = resolveServiceRequirement(name, req, override, appName, configRoots);
         if (container)
             containers.push(container);
     };
@@ -204,45 +421,57 @@ export function resolveAppInfrastructure(infrastructure, overrides, appName) {
 function convertHealthCheck(check, ports) {
     if (!check)
         return undefined;
-    const parseInterval = (s) => s ?? '30s';
+    // One helper per default, not one helper for every duration field. A
+    // single `(s) => s ?? '30s'` used to serve all three, which gave `timeout`
+    // the interval's default: probes ran with a 30s deadline where the type
+    // and the documentation both promise 10s, so an unresponsive service was
+    // marked unhealthy up to three times later than stated — and with the
+    // deadline equal to the gap between probes, they can overlap.
+    const everyDefault = (s) => s ?? '30s';
+    const deadlineDefault = (s) => s ?? '10s';
     switch (check.type) {
         case 'command':
             return {
                 test: ['CMD-SHELL', check.target],
-                interval: parseInterval(check.interval),
-                timeout: parseInterval(check.timeout),
+                interval: everyDefault(check.interval),
+                timeout: deadlineDefault(check.timeout),
                 retries: check.retries ?? 5,
-                startPeriod: parseInterval(check.startPeriod),
+                startPeriod: everyDefault(check.startPeriod),
             };
         case 'tcp':
             return {
                 test: ['CMD-SHELL', `nc -z localhost ${check.target} || exit 1`],
-                interval: parseInterval(check.interval),
-                timeout: parseInterval(check.timeout),
+                interval: everyDefault(check.interval),
+                timeout: deadlineDefault(check.timeout),
                 retries: check.retries ?? 5,
-                startPeriod: parseInterval(check.startPeriod),
+                startPeriod: everyDefault(check.startPeriod),
             };
         case 'http':
             return {
-                test: ['CMD-SHELL', `curl -sf http://localhost${check.target} || exit 1`],
-                interval: parseInterval(check.interval),
-                timeout: parseInterval(check.timeout),
+                test: ['CMD-SHELL', httpProbe(`http://localhost:${healthPort(check, ports)}${check.target}`)],
+                interval: everyDefault(check.interval),
+                timeout: deadlineDefault(check.timeout),
                 retries: check.retries ?? 5,
-                startPeriod: parseInterval(check.startPeriod),
+                startPeriod: everyDefault(check.startPeriod),
             };
         case 'jsonrpc': {
             const portName = check.jsonrpc?.port ?? 'rpc';
             const port = ports?.[portName] ?? portName;
             const method = check.jsonrpc?.method ?? check.target;
             const auth = check.jsonrpc?.auth;
-            const authStr = auth ? `-u ${auth.user}:${auth.password} ${auth.type === 'digest' ? '--digest' : ''}` : '';
+            const authStr = auth && auth.type !== 'cookie'
+                ? `-u ${auth.user}:${auth.password} ${auth.type === 'digest' ? '--digest' : ''}`
+                : '';
             const rpcPath = check.jsonrpc?.path ?? '/json_rpc';
             return {
-                test: ['CMD-SHELL', `curl -sf ${authStr} -X POST http://localhost:${port}${rpcPath} -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"health","method":"${method}"}' || exit 1`],
-                interval: parseInterval(check.interval),
-                timeout: parseInterval(check.timeout),
+                test: [
+                    'CMD-SHELL',
+                    `curl -sf ${authStr} -X POST http://localhost:${port}${rpcPath} -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"health","method":"${method}"}' || exit 1`,
+                ],
+                interval: everyDefault(check.interval),
+                timeout: deadlineDefault(check.timeout),
                 retries: check.retries ?? 5,
-                startPeriod: parseInterval(check.startPeriod),
+                startPeriod: everyDefault(check.startPeriod),
             };
         }
         default:
@@ -261,8 +490,11 @@ function deepMergeDocker(base, overlay) {
     if (base.labels || overlay.labels) {
         merged.labels = { ...base.labels, ...overlay.labels };
     }
-    if (overlay.volumes === undefined && base.volumes) {
-        merged.volumes = base.volumes;
+    // By key, like the environment: an overlay that adds a volume keeps the
+    // base's. Replaced wholesale, a stack that gave Tor one more mount would
+    // have taken away `/var/lib/tor` — its onion keys, and with them its address.
+    if (base.volumes || overlay.volumes) {
+        merged.volumes = { ...base.volumes, ...overlay.volumes };
     }
     if (overlay.resources === undefined && base.resources) {
         merged.resources = base.resources;
@@ -283,7 +515,7 @@ export function resolveOmnitronPg(options) {
     const user = options?.user ?? 'omnitron';
     const password = options?.password ?? 'omnitron';
     return applyManagedDefaults({
-        name: `${CONTAINER_PREFIX}-pg`,
+        name: `${getContainerPrefix()}-pg`,
         image,
         ports: [{ host: port, container: 5432 }],
         environment: {
@@ -291,15 +523,17 @@ export function resolveOmnitronPg(options) {
             POSTGRES_PASSWORD: password,
             POSTGRES_DB: 'omnitron',
         },
-        volumes: [
-            { source: `${CONTAINER_PREFIX}-pg-data`, target: '/var/lib/postgresql/data' },
-        ],
+        volumes: [{ source: `${getContainerPrefix()}-pg-data`, target: '/var/lib/postgresql/data' }],
         command: [
             'postgres',
-            '-c', 'max_connections=50',
-            '-c', 'shared_buffers=64MB',
-            '-c', 'log_statement=none',
-            '-c', 'log_min_duration_statement=500',
+            '-c',
+            'max_connections=50',
+            '-c',
+            'shared_buffers=64MB',
+            '-c',
+            'log_statement=none',
+            '-c',
+            'log_min_duration_statement=500',
         ],
         healthCheck: {
             test: ['CMD-SHELL', `pg_isready -U ${user} -d omnitron`],
@@ -327,6 +561,59 @@ export function resolveOmnitronPg(options) {
  *
  * Port 9800 (public) → nginx → port 9801 (internal daemon HTTP)
  */
+/**
+ * A digest of every file a container mounts from under `root`.
+ *
+ * `configFilesHash` was written for this — its docblock says it is «folded
+ * into the container's spec hash by the caller, so a changed template
+ * recreates the container» — and had no caller. So a node wrote each new
+ * nginx.conf over the old one and kept serving the old one: the gateway
+ * renders its template once, at start, and a reconcile that compares volume
+ * PATHS saw nothing to do. The test gateway was recreated only when its
+ * static bundle changed, which carried the config along by accident.
+ *
+ * Taken from the volumes themselves rather than a list of file names, so a
+ * mount added later is covered without anyone remembering this function.
+ * Read from disk on the machine that will run the container: on a node that
+ * is the copy just written from the master's payload, on a master the
+ * project's own files. Synchronous, because the resolver is — and small: the
+ * sample gateway's files are 65 KB, read once per provision.
+ *
+ * `undefined` when there is nothing under `root` to read, or it cannot be
+ * read — the spec hash then stays what it was without this.
+ */
+export function mountedConfigDigest(root, volumes) {
+    const prefix = root.endsWith('/') ? root : `${root}/`;
+    const files = [];
+    const visit = (abs) => {
+        const stat = fs.statSync(abs);
+        if (stat.isDirectory()) {
+            for (const name of fs.readdirSync(abs).sort())
+                visit(`${abs}/${name}`);
+        }
+        else if (stat.isFile()) {
+            // latin1 maps bytes to code units one to one, so the digest sees the
+            // bytes the container will, text or not.
+            files.push({
+                path: abs.slice(prefix.length),
+                content: fs.readFileSync(abs, 'latin1'),
+                mode: (stat.mode & 0o777).toString(8),
+            });
+        }
+    };
+    try {
+        for (const v of volumes) {
+            // The root itself too: a service may mount its whole shipped directory
+            // (`shipped-config.ts`), where the gateway mounts files inside it.
+            if (v.source === root || v.source.startsWith(prefix))
+                visit(v.source);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return files.length > 0 ? configFilesHash(files) : undefined;
+}
 /**
  * Resolve API gateway container (OpenResty + Lua).
  *
@@ -337,6 +624,34 @@ export function resolveOmnitronPg(options) {
  * @param redisConfig  Stack's Redis connection info (host, port, password)
  * @param projectRoot  Absolute path to project root (for resolving configDir)
  */
+/**
+ * The gateway's config as the stack declares it: every field `resolveGateway`
+ * reads, the preset's block first and the legacy `infrastructure.gateway`
+ * after. The stack manager used to hand it two of them — `configDir` and
+ * `staticDir` — so `env`, declared on `GatewayServiceConfig` as «passed to the
+ * gateway container», reached nothing, and `volumes`, which carries the
+ * onion's socket, would have reached nothing either.
+ */
+export function gatewayConfigOf(presetConfig, legacy, port, redisDb) {
+    const pick = (key) => presetConfig?.[key] ?? legacy?.[key];
+    const staticDir = pick('staticDir');
+    const env = pick('env');
+    const volumes = pick('volumes');
+    return {
+        port,
+        configDir: pick('configDir') ?? 'infra/nginx',
+        redisDb,
+        ...(staticDir ? { staticDir } : {}),
+        ...(env ? { env } : {}),
+        ...(volumes ? { volumes } : {}),
+    };
+}
+/** Only the OpenResty preset owns the shipped template contract.
+ * A service called "gateway" can declare a completely different container.
+ */
+export function usesGatewayTemplate(service) {
+    return service?._preset === 'openresty';
+}
 export function resolveGateway(config, redisConfig, projectRoot) {
     const image = config.image ?? 'openresty/openresty:alpine';
     const port = config.port ?? 8080;
@@ -345,15 +660,56 @@ export function resolveGateway(config, redisConfig, projectRoot) {
     // Resolve absolute path to config directory
     // Use join via string concatenation (ESM-safe, avoids sync require)
     const absConfigDir = projectRoot.endsWith('/') ? projectRoot + configDir : projectRoot + '/' + configDir;
+    // The frontend, if this stack serves one. Absolute already means "a path on
+    // the machine that will run this", which is how a node names its own copy;
+    // a relative path is resolved against the project, like the config is.
+    const staticDir = config.staticDir;
+    const absStaticDir = !staticDir
+        ? null
+        : staticDir.startsWith('/')
+            ? staticDir
+            : `${projectRoot.replace(/\/$/, '')}/${staticDir.replace(/^\.\//, '')}`;
+    /**
+     * Mount the ROOT and serve through the link, when the node sent one.
+     *
+     * The build directory's path changes with every release, and it is the ONLY
+     * field of this spec that does — `mountedConfigDigest` is rooted at the
+     * config directory and the node's config root
+     * (`~/.omnitron/stack-config/<project>/<stack>/<service>`) is stable. So the
+     * container was recreated for every deployment, and that cost **1 s of 000**
+     * on the gateway, measured on release 4 (81 s of deploy). Mounting the root
+     * instead makes the mount a constant, and the swap of
+     * `current-<project>-<stack>` inside it is what changes — atomically, with
+     * `rename(2)`, picked up with no reload because nginx resolves `root` per
+     * request and this config sets no `open_file_cache`.
+     *
+     * Only when the node says so. On a master `staticDir` is a path inside the
+     * project — sample declares `apps/portal/dist` — and mounting ITS parent would
+     * put `src/`, `node_modules` and `vite.config.ts` under the web root, while
+     * `current-…` would not exist there at all and the entrypoint would fall
+     * back to proxying a Vite that is not running.
+     */
+    const linkRoot = config.staticLinkRoot;
+    const linkName = config.staticLinkName;
+    const servesThroughLink = Boolean(linkRoot && linkName);
+    const portalMount = servesThroughLink ? linkRoot : absStaticDir;
+    const portalRoot = servesThroughLink ? `/var/www/portal/${linkName}` : '/var/www/portal';
     // Default upstream host — host.docker.internal for Docker, overridable for bare-metal/cluster
     const upstreamHost = 'host.docker.internal';
-    return {
+    const spec = applyManagedDefaults({
         name: containerName('gateway'),
         image,
         ports: [{ host: port, container: 80 }],
         environment: {
-            // Redis for maintenance mode + future PoW/rate-limit state
-            REDIS_HOST: 'host.docker.internal',
+            // Redis for maintenance mode + future PoW/rate-limit state.
+            //
+            // `redisConfig.host`, not a literal: this took the host as a parameter
+            // alongside the port, the db and the password, and then ignored that
+            // one field. Three of the four came from the caller and the fourth was
+            // hard-coded to the developer's machine, which is why nothing in the
+            // signature hinted that the gateway could not reach its Redis anywhere
+            // else.
+            REDIS_HOST: redisConfig.host,
             REDIS_PORT: String(redisConfig.port),
             REDIS_DB: String(redisDb),
             ...(redisConfig.password ? { REDIS_PASSWORD: redisConfig.password } : {}),
@@ -362,14 +718,24 @@ export function resolveGateway(config, redisConfig, projectRoot) {
             UPSTREAM_MAIN_PORT: '3001',
             UPSTREAM_STORAGE_HOST: upstreamHost,
             UPSTREAM_STORAGE_PORT: '3002',
-            UPSTREAM_PRICEVERSE_HOST: upstreamHost,
-            UPSTREAM_PRICEVERSE_PORT: '3003',
-            UPSTREAM_PAYSYS_HOST: upstreamHost,
-            UPSTREAM_PAYSYS_PORT: '3004',
+            UPSTREAM_PRICING_HOST: upstreamHost,
+            UPSTREAM_PRICING_PORT: '3003',
+            UPSTREAM_PAYMENTS_HOST: upstreamHost,
+            UPSTREAM_PAYMENTS_PORT: '3004',
             UPSTREAM_MESSAGING_HOST: upstreamHost,
             UPSTREAM_MESSAGING_PORT: '3005',
             UPSTREAM_MESSAGING_WS_HOST: upstreamHost,
             UPSTREAM_MESSAGING_WS_PORT: '3006',
+            UPSTREAM_GEO_HOST: upstreamHost,
+            UPSTREAM_GEO_PORT: '3007',
+            // Where the entrypoint serves `/` from. `/var/www/portal` unless the
+            // node mounted the root, in which case the link inside it — so the
+            // gateway is pointed at a new build by a symlink swap and not by a new
+            // container.
+            PORTAL_ROOT: portalRoot,
+            // User-supplied env overrides/additions (e.g. PORTAL_DEV_UPSTREAM). Merged
+            // last so config can override a preset default when intended.
+            ...(config.env ?? {}),
         },
         volumes: [
             // nginx.conf template — rendered by entrypoint via envsubst
@@ -380,10 +746,20 @@ export function resolveGateway(config, redisConfig, projectRoot) {
             { source: `${absConfigDir}/lua`, target: '/etc/nginx/lua', readonly: true },
             // Maintenance mode HTML page
             { source: `${absConfigDir}/maintenance.html`, target: '/etc/nginx/html/maintenance.html', readonly: true },
+            // The built frontend, when the stack declares one. `/var/www/portal` is
+            // the path nginx.conf serves `/` from whenever `PORTAL_DEV_UPSTREAM` is
+            // unset, which is every deployment that has no Vite beside it.
+            ...(portalMount ? [{ source: portalMount, target: '/var/www/portal', readonly: true }] : []),
+            // What the stack adds — the onion's unix socket above all, on a
+            // `shared:` volume the Tor container mounts too.
+            ...Object.entries(config.volumes ?? {}).map(([key, vol]) => resolveNamedOrBound('gateway', key, vol)),
         ],
         entrypoint: ['/bin/sh', '/docker-entrypoint.sh'],
         healthCheck: {
-            test: ['CMD-SHELL', '[ -S /usr/local/openresty/nginx/logs/nginx.pid ] || kill -0 $(cat /usr/local/openresty/nginx/logs/nginx.pid 2>/dev/null) 2>/dev/null || exit 1'],
+            test: [
+                'CMD-SHELL',
+                '[ -S /usr/local/openresty/nginx/logs/nginx.pid ] || kill -0 $(cat /usr/local/openresty/nginx/logs/nginx.pid 2>/dev/null) 2>/dev/null || exit 1',
+            ],
             interval: '10s',
             timeout: '5s',
             retries: 3,
@@ -397,7 +773,11 @@ export function resolveGateway(config, redisConfig, projectRoot) {
         restart: 'unless-stopped',
         extraHosts: ['host.docker.internal:host-gateway'],
         resources: config.resources,
-    };
+    });
+    const configDigest = mountedConfigDigest(absConfigDir, spec.volumes);
+    if (configDigest)
+        spec.configDigest = configDigest;
+    return spec;
 }
 // =============================================================================
 // Omnitron Admin Console (separate from API gateway)
@@ -416,9 +796,9 @@ export function resolveOmnitronNginx(options) {
         volumes.push({ source: webappDist, target: '/usr/share/nginx/html', readonly: true });
     }
     return applyManagedDefaults({
-        name: `${CONTAINER_PREFIX}-nginx`,
+        name: `${getContainerPrefix()}-nginx`,
         image,
-        ports: [{ host: port, container: 80 }],
+        ports: [{ host: port, container: 80, bindHost: options?.bindHost ?? '127.0.0.1' }],
         environment: {
             OMNITRON_API_HOST: 'host.docker.internal',
             OMNITRON_API_PORT: String(internalPort),
@@ -431,8 +811,13 @@ export function resolveOmnitronNginx(options) {
         // base image, so the previous CMD-SHELL test was permanently
         // unhealthy on a vanilla alpine nginx until someone bind-mounted curl
         // in. wget is always present.
+        //
+        // Probe 127.0.0.1 (not `localhost`): musl resolves `localhost` to ::1
+        // first, but nginx only `listen 80;` on IPv4, so an IPv6 probe gets
+        // ECONNREFUSED and the container is reported permanently unhealthy even
+        // though the console is serving fine over IPv4.
         healthCheck: {
-            test: ['CMD-SHELL', 'wget -q --spider http://localhost/ || exit 1'],
+            test: ['CMD-SHELL', 'wget -q --spider http://127.0.0.1/ || exit 1'],
             interval: '10s',
             timeout: '5s',
             retries: 3,
@@ -461,10 +846,78 @@ export function resolveOmnitronNginx(options) {
  * Resolve an InfrastructureConfig into concrete container specs.
  * Uses preset-normalized services map — all services go through resolveServiceRequirement().
  */
-export function resolveInfrastructure(_config, normalizedServices) {
+export function resolveInfrastructure(_config, normalizedServices, 
+/**
+ * Stack overrides — `disabled`, `external`, per-service docker changes.
+ *
+ * This did not take them, and `resolveAppInfrastructure` was called
+ * without them, so `serviceOverrides` was honoured for services an
+ * APPLICATION declares and read by nothing for the ones a stack declares.
+ * An operator writing `tiles: { disabled: true }` got tiles.
+ *
+ * Measured on the test server: a stack that disabled the geocoder and the
+ * tile server provisioned both — a geocoding database that can reach tens
+ * of gigabytes, on a host chosen for a payment system.
+ */
+overrides, 
+/**
+ * Where a service's config files live on THIS machine, by service name.
+ *
+ * The gateway is not an ordinary preset container: it needs four bind
+ * mounts, an entrypoint and fifteen upstream variables, and `resolveGateway`
+ * is the only thing that produces them. On a master they come from the
+ * project root; on a node there is no project, so the files are sent over
+ * and written locally, and this names where.
+ *
+ * Without it a node built its gateway through the generic preset path —
+ * whose own `defaultDocker` comment says "Volumes and entrypoint configured
+ * by resolveGateway" — and got bare openresty: an empty `Mounts` array, a
+ * null entrypoint, zero UPSTREAM variables, and an onion serving
+ * `Welcome to OpenResty!`.
+ */
+configRoots, gatewayContext) {
     if (!normalizedServices || Object.keys(normalizedServices).length === 0) {
         return [];
     }
-    return resolveAppInfrastructure(normalizedServices);
+    const gatewayRoot = configRoots?.get('gateway');
+    if (!gatewayRoot ||
+        !normalizedServices['gateway'] ||
+        !usesGatewayTemplate(normalizedServices['gateway']) ||
+        !gatewayContext) {
+        return resolveAppInfrastructure(normalizedServices, overrides, undefined, configRoots);
+    }
+    // One resolver for the gateway, wherever it runs. The rest go through the
+    // generic path, which is right for them — with the node's copies of what
+    // they mount from shipped directories (`shipped-config.ts`).
+    const { gateway: _gateway, ...rest } = normalizedServices;
+    const containers = resolveAppInfrastructure(rest, overrides, undefined, configRoots);
+    const port = gatewayHostPort(normalizedServices['gateway'], undefined);
+    // The stack's whole gateway block — its env and its volumes as on a master
+    // (`gatewayConfigOf`) — with the two paths a node names for itself. This
+    // road passed port, configDir and staticDir only: on 2026-09-26 the node
+    // built sample/test's gateway without GATEWAY_UNIX_SOCKET and without the
+    // shared socket volume, Tor pointed at a socket nobody listened on, and the
+    // onion was down for ~11 minutes. f0e19089 had fixed the master's road.
+    const { staticDir: _declaredStaticDir, ...declared } = gatewayConfigOf(normalizedServices['gateway']._presetConfig, undefined, port, gatewayContext.redis.db);
+    const staticRoot = gatewayContext.staticRoots?.get('gateway');
+    const staticLinkRoot = gatewayContext.staticLinkRoots?.get('gateway');
+    containers.push(resolveGateway({
+        ...declared,
+        configDir: '.',
+        // Absolute: a node names its own copy, not a path relative to a
+        // project it does not have.
+        ...(staticRoot ? { staticDir: staticRoot } : {}),
+        // The project and the stack are not parameters here and do not need
+        // to be: `setStackLabels` has already put them where every container
+        // of this stack reads them, and the link is spelled by the one
+        // function that spells it anywhere.
+        ...(staticLinkRoot
+            ? {
+                staticLinkRoot,
+                staticLinkName: gatewayStaticLinkName(stackLabels()['omnitron.project'] ?? '', stackLabels()['omnitron.stack'] ?? ''),
+            }
+            : {}),
+    }, gatewayContext.redis, gatewayRoot));
+    return containers;
 }
 //# sourceMappingURL=service-resolver.js.map