@underpostnet/cyberia 3.2.80 → 3.2.90

package/bin/deploy.js

@@ -223,21 +223,23 @@ try {
         .readFileSync(`./engine-private/deploy/dd.router`, 'utf8')
         .split(`,`)
         .concat(['dd-cron'])) {
-        if (fs.existsSync(`./engine-private/conf/${deployId}/build/development/deployment.yaml`))
-          fs.copySync(
-            `./engine-private/conf/${deployId}/build/development/deployment.yaml`,
-            `./manifests/deployment/${deployId}-development/deployment.yaml`,
-          );
-        if (fs.existsSync(`./engine-private/conf/${deployId}/build/development/proxy.yaml`))
-          fs.copySync(
-            `./engine-private/conf/${deployId}/build/development/proxy.yaml`,
-            `./manifests/deployment/${deployId}-development/proxy.yaml`,
-          );
-        if (fs.existsSync(`./engine-private/conf/${deployId}/build/development/pv-pvc.yaml`))
-          fs.copySync(
-            `./engine-private/conf/${deployId}/build/development/pv-pvc.yaml`,
-            `./manifests/deployment/${deployId}-development/pv-pvc.yaml`,
-          );
+        // The same set `deploy --build-manifest` mirrors. Anything missing here
+        // is a manifest the project repo silently stops carrying while the
+        // private build dir still has it.
+        for (const file of [
+          'deployment.yaml',
+          'proxy.yaml',
+          'gateway.yaml',
+          'httproute.yaml',
+          'pv-pvc.yaml',
+          'traffic-service.yaml',
+          'grpc-service.yaml',
+        ]) {
+          const source = `./engine-private/conf/${deployId}/build/development/${file}`;
+          const target = `./manifests/deployment/${deployId}-development/${file}`;
+          if (fs.existsSync(source)) fs.copySync(source, target);
+          else fs.removeSync(target);
+        }
         shellExec(`node bin new --dev --default-conf --deploy-id ${deployId}`);
       }
       break;
@@ -763,7 +765,7 @@ nvidia/gpu-operator \
 
     case 'pw-conf': {
       const scriptPath = process.argv[3];
-      shellExec(`kubectl delete configmap playwright-script`);
+      shellExec(`kubectl delete configmap playwright-script --ignore-not-found`);
       shellExec(`kubectl create configmap playwright-script \
   --from-file=script.js=${scriptPath} \
   --dry-run=client -o yaml | kubectl apply -f -

package/bin/index.js

@@ -17,7 +17,7 @@ import { shellExec } from '../src/server/process.js';
 import { loggerFactory } from '../src/server/logger.js';
 import { generateBesuManifests, deployBesu, removeBesu } from '../src/projects/cyberia/besu-genesis-generator.js';
 import { DataBaseProviderService } from '../src/db/DataBaseProvider.js';
-import { loadConfServerJson } from '../src/server/conf.js';
+import { etcHostFactory, loadConfServerJson, normalizeInstanceTopology } from '../src/server/conf.js';
 import {
   ObjectLayerEngine,
   resolveCanonicalCid,
@@ -51,6 +51,7 @@ import {
 } from '../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
 
 import {
+  DEFAULT_INSTANCE_CODE,
   ITEM_TYPES as itemTypes,
   DefaultCyberiaItems,
 } from '../src/client/components/cyberia/SharedDefaultsCyberia.js';
@@ -95,6 +96,22 @@ async function connectDbForChain({ envPath, mongoHost }) {
 /** @type {Function} */
 const logger = loggerFactory(import.meta);
 
+const CYBERIA_DOCKER_HOST_ALIASES = ['cyberia-client', 'cyberia-server', 'engine-cyberia'];
+
+const installCyberiaDockerHostAliases = () => {
+  try {
+    const { changed } = etcHostFactory(CYBERIA_DOCKER_HOST_ALIASES, {
+      append: true,
+      blockId: 'dd-cyberia-docker-compose',
+    });
+    return { aliases: CYBERIA_DOCKER_HOST_ALIASES, changed };
+  } catch (error) {
+    if (error?.code === 'EACCES' || error?.code === 'EPERM')
+      throw new Error('Cannot update /etc/hosts for Cyberia Docker aliases. Re-run the workflow as root.');
+    throw error;
+  }
+};
+
 try {
   const program = new Command();
 
@@ -219,7 +236,6 @@ try {
           deployId,
           host,
           path,
-          db,
         });
 
         await DataBaseProviderService.load({
@@ -1954,7 +1970,7 @@ try {
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('instance env', { env: options.envPath, deployId, host, path, db });
+      logger.info('instance env', { env: options.envPath, deployId, host, path });
 
       await DataBaseProviderService.load({
         apis: [
@@ -3892,7 +3908,7 @@ try {
             ? db.host
             : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-        logger.info('generate-saga', { deployId, host, path, db });
+        logger.info('generate-saga', { deployId, host, path });
 
         await DataBaseProviderService.load({
           apis: [
@@ -4835,6 +4851,7 @@ try {
       '--clean',
       'Restore repositories to canonical state (git checkout Dockerfile, etc.) before updating compose.env',
     )
+    .option('--test', 'Test DNS connectivity accross cyberia deployments')
     .option('--reset', 'Reset the development environment before updating compose.env')
     .action((options) => {
       if (options.reset) {
@@ -4848,6 +4865,25 @@ try {
         shellExec(`node bin run clean ./cyberia-client`);
         return;
       }
+      if (options.test) {
+        const testHosts = [
+          'localhost',
+          'localhost:4005',
+          'localhost:8081',
+          'localhost:8082',
+          'engine-cyberia',
+          'cyberia-server',
+          'cyberia-client',
+        ];
+        const testPaths = ['/', '/TEST', '/FOREST'];
+        for (const host of testHosts) {
+          for (const path of testPaths) {
+            shellExec(`curl -L -v -i -s http://${host}${path} | head -n 10`, {
+              silentOnError: true,
+            });
+          }
+        }
+      }
       const envPath = `./engine-private/conf/dd-cyberia/docker-compose/cyberia/compose.env`;
       const canonicalDevDockerfile = './src/runtime/engine-cyberia/Dockerfile.dev';
       fs.writeFileSync(
@@ -4930,7 +4966,7 @@ try {
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('drop-db', { deployId, host, path, db });
+      logger.info('drop-db', { deployId, host, path });
 
       const cyberiaCollections = [
         'cyberia-entity',
@@ -4997,7 +5033,7 @@ try {
       // no funca
       if (options.loadTar) {
         for (const imageId of dockerImageIds)
-          if (imageId === id || id === '.') shellExec(`docker load -i ./${imageId}-dev_v3.2.80.tar`);
+          if (imageId === id || id === '.') shellExec(`docker load -i ./${imageId}-dev_v3.2.90.tar`);
         return;
       }
       switch (id) {
@@ -5008,7 +5044,7 @@ node bin/build dd-cyberia --update-private
 node bin image --path src/runtime/engine-cyberia \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name engine-cyberia-dev:v3.2.80 \
+  --image-name engine-cyberia-dev:v3.2.90 \
   --image-out-path .
 `);
           break;
@@ -5019,7 +5055,7 @@ cp -f src/runtime/cyberia-server/Dockerfile.dev cyberia-server/Dockerfile.dev
 node bin image --path cyberia-server \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name cyberia-server-dev:v3.2.80 \
+  --image-name cyberia-server-dev:v3.2.90 \
   --image-out-path .
 `);
           break;
@@ -5029,7 +5065,7 @@ cp -f src/runtime/cyberia-client/Dockerfile.dev cyberia-client/Dockerfile.dev
 node bin image --path cyberia-client \
   --docker-compose --pull-base --build \
   --dockerfile-name Dockerfile.dev \
-  --image-name cyberia-client-dev:v3.2.80 \
+  --image-name cyberia-client-dev:v3.2.90 \
   --image-out-path .
 `);
           break;
@@ -5038,6 +5074,10 @@ node bin image --path cyberia-client \
 
   for (const [cmd, action] of Object.entries(DOCKER_SCRIPTS))
     runner.command(cmd).action(() => {
+      if (cmd === 'docker:up' || cmd === 'docker:up:build' || cmd === 'docker:restart') {
+        const { aliases, changed } = installCyberiaDockerHostAliases();
+        logger.info(`Docker host aliases ${changed ? 'installed' : 'already configured'}`, { aliases });
+      }
       shellExec(action);
     });
 
@@ -5074,7 +5114,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-dialogues', { deployId, host, path, db });
+      logger.info('seed-dialogues', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-dialogue'], host, path, db });
 
@@ -5129,7 +5169,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-actions-quests', { deployId, host, path, db });
+      logger.info('seed-actions-quests', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-action', 'cyberia-quest'], host, path, db });
 
@@ -5185,7 +5225,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-skills', { deployId, host, path, db });
+      logger.info('seed-skills', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-skill'], host, path, db });
 
@@ -5245,7 +5285,7 @@ node bin image --path cyberia-client \
           ? db.host
           : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-      logger.info('seed-entities', { deployId, host, path, db });
+      logger.info('seed-entities', { deployId, host, path });
 
       await DataBaseProviderService.load({ apis: ['cyberia-entity-type-default'], host, path, db });
 
@@ -5353,6 +5393,84 @@ node bin image --path cyberia-client \
       logger.info('All semantic examples generated.');
     });
 
+  // Instance id → project root. Single source of truth for the workloads this
+  // workflow builds: both the k8s manifests and the status page artifacts each
+  // project ships are resolved from this list plus conf.instances.json.
+  const CYBERIA_INSTANCE_PROJECTS = [
+    { id: 'mmo-client', rootPath: './cyberia-client' },
+    { id: 'mmo-server', rootPath: './cyberia-server' },
+  ];
+  const CYBERIA_CONF_INSTANCES_PATH = './engine-private/conf/dd-cyberia/conf.instances.json';
+  const CYBERIA_CONF_SSR_PATH = './engine-private/conf/dd-cyberia/conf.ssr.json';
+  // Copy shared by the server and the client for a given status code. A status
+  // without an entry falls back to its conf.ssr.json view title.
+  const CYBERIA_STATUS_PAGE_META = {
+    404: {
+      title: 'Cyberia — Sector Not Found',
+      description: 'Cyberia Online 404 — the requested sector is not on the grid.',
+    },
+  };
+
+  /**
+   * Reads the raw (unexpanded) conf.instances.json entries.
+   * @returns {Array<object>} Instance entries, or an empty list when unavailable.
+   */
+  const readCyberiaConfInstances = () => {
+    try {
+      return JSON.parse(fs.readFileSync(CYBERIA_CONF_INSTANCES_PATH, 'utf8'));
+    } catch (err) {
+      logger.warn(`Could not read ${CYBERIA_CONF_INSTANCES_PATH}: ${err.message}`);
+      return [];
+    }
+  };
+
+  /**
+   * Resolves the SSR view that renders a status page. The view is declared in
+   * conf.ssr.json as a route whose path is the bare status code (`/404`), the
+   * same declaration the PWA build turns into `/404/index.html`.
+   * @param {string} status - HTTP status code.
+   * @returns {{ client: string, title: string }|null} View descriptor, or null when undeclared.
+   */
+  const resolveStatusPageView = (status) => {
+    if (!fs.existsSync(CYBERIA_CONF_SSR_PATH)) return null;
+    const confSSR = JSON.parse(fs.readFileSync(CYBERIA_CONF_SSR_PATH, 'utf8'));
+    for (const clientConf of Object.values(confSSR))
+      for (const view of clientConf?.views || []) if (view.path === `/${status}`) return view;
+    return null;
+  };
+
+  /**
+   * Renders one custom status page to a static HTML artifact. The workloads no
+   * longer serve error pages themselves — the document is carried into the
+   * gateway config by `run instance-build-manifest`, so this only has to place
+   * it at the `hostPath` the instance declares.
+   * @param {string} status - HTTP status code.
+   * @param {string} outputPath - Destination HTML path.
+   * @param {boolean} [dev] - Render the development variant.
+   * @returns {boolean} True when the artifact was rendered.
+   */
+  const buildCyberiaStatusPage = ({ status, outputPath, dev = false }) => {
+    const view = resolveStatusPageView(status);
+    const pagePath = `./src/client/ssr/views/${view?.client || `Cyberia${status}`}.js`;
+    if (!fs.existsSync(pagePath)) {
+      logger.warn(`[build-status-page] No SSR view for status ${status}; skipping`, { pagePath, outputPath });
+      return false;
+    }
+    const meta = CYBERIA_STATUS_PAGE_META[status] || {};
+    const title = meta.title || view?.title || `Cyberia — ${status}`;
+    const description = meta.description || `Cyberia Online ${status}.`;
+    shellExec(
+      `node bin static --page ${pagePath}` +
+        ` --output-path ${outputPath}` +
+        ` --title '${title}'` +
+        ` --favicon /favicon.ico` +
+        ` --description '${description}'` +
+        ` --lang en` +
+        ` --env ${dev ? 'development' : 'production'}`,
+    );
+    return true;
+  };
+
   runner
     .command('build-manifest')
     .option(
@@ -5385,24 +5503,24 @@ node bin image --path cyberia-client \
       // A variant declared in conf.instances.json without the instance
       // directory is silently skipped so the Dockerfile never tries to
       // copy a non-existent directory and the container build does not fail.
-      const confInstancesPath = './engine-private/conf/dd-cyberia/conf.instances.json';
       const cyberiaInstancesDir = '/home/dd/cyberia-instances';
       let instanceCodes = 'amethyst-strata-expansion,FOREST'; // fallback
+      const confInstancesEntries = readCyberiaConfInstances();
       try {
-        const confInstances = JSON.parse(fs.readFileSync(confInstancesPath, 'utf8'));
-        const serverInstances = confInstances.filter((inst) => inst.runtime === 'cyberia-server');
+        const serverInstances = confInstancesEntries.filter((inst) => inst.runtime === 'cyberia-server');
         const codes = new Set();
         for (const inst of serverInstances) {
           if (inst.multiInstance?.variants) {
-            for (const v of inst.multiInstance.variants) {
-              if (!v.code) continue;
+            const topology = normalizeInstanceTopology(inst.multiInstance, `dd-cyberia/${inst.id}`);
+            for (const v of topology.variants) {
+              const code = v.path === '/' ? DEFAULT_INSTANCE_CODE : v.code;
               // Skip codes that have no on-disk instance backup dir
-              const instanceDir = `${cyberiaInstancesDir}/instances/${v.code}`;
+              const instanceDir = `${cyberiaInstancesDir}/instances/${code}`;
               if (!fs.existsSync(instanceDir)) {
-                logger.info(`[build-manifest] Skipping code "${v.code}": no instance dir at ${instanceDir}`);
+                logger.info(`[build-manifest] Skipping code "${code}": no instance dir at ${instanceDir}`);
                 continue;
               }
-              codes.add(v.code);
+              codes.add(code);
             }
           }
         }
@@ -5413,7 +5531,7 @@ node bin image --path cyberia-client \
           logger.warn(`[build-manifest] No valid instance codes found; keeping fallback: ${instanceCodes}`);
         }
       } catch (err) {
-        logger.warn(`[build-manifest] Could not read ${confInstancesPath}: ${err.message}; using fallback`);
+        logger.warn(`[build-manifest] Could not read ${CYBERIA_CONF_INSTANCES_PATH}: ${err.message}; using fallback`);
       }
 
       // ── Update Dockerfile.dev + Dockerfile INSTANCE_CODES build arg ──────
@@ -5474,29 +5592,38 @@ node bin image --path cyberia-client \
         logger.warn(`[build-manifest] Could not update ${catalogPath}: ${err.message}`);
       }
 
+      // ── Build SSR views ──────────────────────────────────────────────────
+      // Status pages are rendered BEFORE the manifests: the gateway manifests
+      // embed each document declared under an instance's `customStatusPages`,
+      // so the artifact has to exist at its `hostPath` by manifest time.
+      const statusPagesBuilt = [];
+      for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS) {
+        const instance = confInstancesEntries.find((entry) => entry.id === id);
+        for (const page of instance?.customStatusPages || []) {
+          if (!page?.status || !page?.hostPath) continue;
+          const outputPath = nodePath.normalize(`${rootPath}/${page.hostPath}`);
+          if (buildCyberiaStatusPage({ status: page.status, outputPath, dev: isDev }))
+            statusPagesBuilt.push({ instance: id, status: page.status, outputPath });
+        }
+      }
+      logger.info('[build-manifest] Custom status pages built', statusPagesBuilt);
+      shellExec(
+        `node bin/cyberia run-workflow build-server-dashboard --output-path ./cyberia-server/public/index.html`,
+      );
+
       // ── Build dev manifests (always --kind --dev) ────────────────────────
       {
         const flags = `--kind --dev${nodeFlag}`;
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' ${flags}`);
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' ${flags}`);
+        for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS)
+          shellExec(`node bin run instance-build-manifest 'dd-cyberia,${id},${rootPath}' ${flags}`);
       }
       // ── Build prod manifests (--kubeadm, no --dev) ───────────────────────
       if (!isDev) {
         const flags = `--kubeadm${nodeFlag}`;
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' ${flags}`);
-        shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' ${flags}`);
+        for (const { id, rootPath } of CYBERIA_INSTANCE_PROJECTS)
+          shellExec(`node bin run instance-build-manifest 'dd-cyberia,${id},${rootPath}' ${flags}`);
       }
 
-      // ── Build SSR views ──────────────────────────────────────────────────
-      const env404 = isDev ? ' --dev' : '';
-      shellExec(
-        `node bin/cyberia run-workflow build-cyberia-404 --output-path ./cyberia-server/public/404.html${env404}`,
-      );
-      shellExec(`node bin/cyberia run-workflow build-cyberia-404 --output-path ./cyberia-client/bin/404.html${env404}`);
-      shellExec(
-        `node bin/cyberia run-workflow build-server-dashboard --output-path ./cyberia-server/public/index.html`,
-      );
-
       // Copy canonical doc sources into the generated project READMEs.
       // Edit the canonical sources; never hand-edit these generated outputs.
       fs.copyFileSync('./src/client/public/cyberia-docs/CYBERIA-CLIENT.md', './cyberia-client/README.md');
@@ -5565,27 +5692,54 @@ node bin image --path cyberia-client \
       );
     });
 
+  runner
+    .command('build-status-page')
+    .requiredOption(
+      '--status <status>',
+      'HTTP status code to render (must be declared as an SSR view in conf.ssr.json).',
+    )
+    .option('--dev', 'Build a development variant of the status page.')
+    .option(
+      '--output-path <path>',
+      'Output path for the rendered HTML. Defaults to the `hostPath` the mmo-server instance declares for the status.',
+    )
+    .description(
+      'Build one custom status page artifact. The SSR view is resolved from the conf.ssr.json route whose path is ' +
+        'the bare status code; the rendered document is served by the gateway, not by the workload.',
+    )
+    .action((options) => {
+      const status = `${options.status}`;
+      const statusPage = (
+        readCyberiaConfInstances().find((entry) => entry.id === 'mmo-server')?.customStatusPages || []
+      ).find((page) => `${page.status}` === status);
+      const outputPath =
+        options.outputPath || (statusPage ? nodePath.normalize(`./cyberia-server/${statusPage.hostPath}`) : null);
+      if (!outputPath) {
+        logger.error(`[build-status-page] No --output-path and no customStatusPages entry for status ${status}`);
+        return;
+      }
+      buildCyberiaStatusPage({ status, outputPath, dev: !!options.dev });
+    });
+
   runner
     .command('build-cyberia-404')
     .option('--dev', 'Build a development variant of the 404 page.')
     .option(
       '--output-path <path>',
       'Output path for the rendered 404.html (default: ./cyberia-server/public/404.html). ' +
-        'The same page is served, sub-path aware, by every instance variant of both the ' +
-        'cyberia-server (Go static server) and cyberia-client (docker-driver).',
+        'The same page is served, sub-path aware, by the gateway for every instance variant of both the ' +
+        'cyberia-server and cyberia-client workloads.',
+    )
+    .description(
+      'Build the cyberpunk pixel-art "sector not found" (404) page shared by the Cyberia server + client. ' +
+        'Thin alias of `build-status-page --status 404`, kept as the entrypoint the instance CI workflows call.',
     )
-    .description('Build the cyberpunk pixel-art "sector not found" (404) page shared by the Cyberia server + client.')
     .action((options) => {
-      const outputPath = options.outputPath || './cyberia-server/public/404.html';
-      shellExec(
-        `node bin static --page ./src/client/ssr/views/Cyberia404.js` +
-          ` --output-path ${outputPath}` +
-          ` --title 'Cyberia — Sector Not Found'` +
-          ` --favicon /favicon.ico` +
-          ` --description 'Cyberia Online 404 — the requested sector is not on the grid.'` +
-          ` --lang en` +
-          ` --env ${options.dev ? 'development' : 'production'}`,
-      );
+      buildCyberiaStatusPage({
+        status: '404',
+        outputPath: options.outputPath || './cyberia-server/public/404.html',
+        dev: !!options.dev,
+      });
     });
 
   // Passthrough check: if the user invoked a command that is OWNED by the

package/compose.env

@@ -40,29 +40,27 @@ VALKEY_HOST=valkey-service
 VALKEY_PORT=6379
 
 # --- Cyberia instance wiring (compose service DNS) ---------------------------
-# cyberia-server-* -> engine-cyberia authority endpoints. INTERNAL only: these
-# use the docker service DNS (engine-cyberia) and must never leak to browser
-# clients. Per-instance INSTANCE_CODE is set on each generated server service
-# from conf.instances.json (multiInstance) — not here.
-ENGINE_API_BASE_URL=http://engine-cyberia:4005
-ENGINE_GRPC_ADDRESS=engine-cyberia:50051
+# cyberia-server-* -> stable engine gateway for HTTP and the raw engine runtime
+# for gRPC. The public engine-cyberia name belongs to nginx, avoiding ambiguous
+# Docker DNS while keeping one stable HTTP endpoint for every module.
+ENGINE_API_BASE_URL=http://engine-cyberia
+ENGINE_GRPC_ADDRESS=engine-cyberia-runtime:50051
 
 # Client-visible Content Authority origin, forwarded to browser/Raylib clients
 # for every engine-cyberia content/asset/metadata request. Host-reachable
-# (docker publishes engine-cyberia :4005). Distinct from ENGINE_API_BASE_URL:
+# (Docker publishes the raw engine runtime on host :4005). Unlike the internal
+# ENGINE_API_BASE_URL, this value is consumed outside the Compose network:
 # the two responsibilities must never overwrite each other.
 ENGINE_PUBLIC_URL=http://localhost:4005
 ENGINE_GRPC_RELOAD_INTERVAL_SEC=300
 
 # --- Browser-facing client runtime config (injected by docker-driver.py) -----
 # The single WASM bundle resolves its instance from the URL sub-path and builds
-# its endpoints from these origins. They point at the nginx proxy on localhost:80
-# (the single gateway that path-routes WS -> server, /api + /assets -> engine),
-# NOT at the raw client/engine container ports — a WS to the client port (8082)
-# has no server behind it. So this must be the proxy origin, not :8082 / :4005.
-#   http://localhost/          -> default instance,  ws -> ws://localhost/ws
-#   http://localhost/FOREST    -> FOREST instance,    ws -> ws://localhost/FOREST/ws
-CYBERIA_WS_ORIGIN=ws://localhost
+# its endpoints from these origins. HTTP client/API traffic uses nginx on :80;
+# WebSocket traffic uses the dedicated multi-path server gateway on :8081.
+#   http://localhost/          -> default, ws://localhost:8081/ws
+#   http://localhost/FOREST    -> FOREST,  ws://localhost:8081/FOREST/ws
+CYBERIA_WS_ORIGIN=ws://localhost:8081
 CYBERIA_ENGINE_API_ORIGIN=http://localhost
 CYBERIA_DEFAULT_INSTANCE=amethyst-strata-expansion
 
@@ -82,6 +80,7 @@ NODE_OPTIONS=--max-old-space-size=8192
 BASE_API=api
 DEFAULT_DEPLOY_ID=dd-cyberia
 DEPLOY_ID=dd-cyberia
+# Configuration/DB selector from conf.server.json; this is not a Docker DNS alias.
 DEFAULT_DEPLOY_HOST=www.cyberiaonline.com
 DEFAULT_DEPLOY_PATH=/
 DISABLE_API_RATE_LIMIT=true
@@ -131,7 +130,25 @@ IPFS_CLUSTER_API_URL=http://ipfs-cluster:9094
 # in docker-compose.yml). Override for a real/shared cluster.
 # CLUSTER_SECRET=
 
-# --- Host-published ports ----------------------------------------------------
+# --- Local access ------------------------------------------------------------
+# Client gateway:  http://localhost/{,FOREST,TEST}
+# Client port alias: http://localhost:8082/{,FOREST,TEST}
+# Server gateway:  http://localhost:8081/{,FOREST,TEST}
+# Engine authority: http://localhost:4005
+# Docker-network gateways:
+#   http://cyberia-client/{,FOREST,TEST}
+#   http://cyberia-server/{,FOREST,TEST}
+#   http://engine-cyberia/
+#
+# The *.localhost aliases normally resolve to loopback without configuration:
+#   http://client.cyberia.localhost/{,FOREST,TEST}
+#   http://server.cyberia.localhost/{,FOREST,TEST}
+#   http://engine.cyberia.localhost/
+# `node bin/cyberia run-workflow docker:up` maintains this host entry (the
+# aliases already work between containers):
+#   127.0.0.1 cyberia-client cyberia-server engine-cyberia
+#
+# Host-published ports:
 PROXY_HTTP_PORT=80
 IPFS_API_PORT=5001
 IPFS_GATEWAY_PORT=8080
@@ -140,5 +157,7 @@ MONGO_HOST_PORT=27017
 VALKEY_NODEPORT=32079
 ENGINE_CYBERIA_REST_PORT=4005
 ENGINE_CYBERIA_GRPC_PORT=50051
+# Multi-path nginx server gateway, not a single server container publication.
 CYBERIA_SERVER_PORT=8081
+# Multi-path nginx client gateway; raw client containers remain internal.
 CYBERIA_CLIENT_PORT=8082