@underpostnet/cyberia 3.3.0 → 3.3.73

package/src/runtime/cyberia-client/Dockerfile

@@ -14,7 +14,6 @@ RUN make -f Web.mk clean all BUILD_MODE=${BUILD_MODE} OUTPUT_DIR=bin/
 
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
-ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 
 RUN set -eux; \
@@ -28,9 +27,15 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
-    dnf clean all; rm -rf /var/cache/dnf; \
-    npm cache clean --force
+    dnf clean all; rm -rf /var/cache/dnf
+
+
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version
 
 # Path + server layout is the contract with conf.instances.json mmo-client cmd,
 # which execs `python3 /home/dd/engine/cyberia-client/docker-driver.py <port>

package/src/runtime/cyberia-client/Dockerfile.dev

@@ -43,7 +43,6 @@ RUN make -f Web.mk all BUILD_MODE=${BUILD_MODE} OUTPUT_DIR=bin/
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
 
-ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 RUN set -eux; \
     dnf -y update; \
@@ -60,9 +59,16 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
     dnf clean all
 
+
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version
+
 WORKDIR /home/dd/engine/cyberia-client
 
 COPY --from=builder /cyberia-client/docker-driver.py ./docker-driver.py

package/src/runtime/cyberia-server/Dockerfile

@@ -11,7 +11,6 @@ RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o server ./cmd/cyberia-se
 
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
-ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 
 RUN set -eux; \
@@ -25,9 +24,15 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
-    dnf clean all; rm -rf /var/cache/dnf; \
-    npm cache clean --force
+    dnf clean all; rm -rf /var/cache/dnf
+
+
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version
 
 # Path is the contract with conf.instances.json mmo-server cmd, which execs
 # /home/dd/engine/cyberia-server/server in both development and production.

package/src/runtime/cyberia-server/Dockerfile.dev

@@ -25,7 +25,6 @@ RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
 # --- Runtime Image ---
 FROM rockylinux/rockylinux:9 AS runtime
 
-ARG UNDERPOST_VERSION=3.3.0
 ARG NODE_VERSION=24.15.0
 RUN set -eux; \
     dnf -y update; \
@@ -42,9 +41,16 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
     dnf clean all
 
+
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version
+
 WORKDIR /home/dd/engine/cyberia-server
 
 COPY --from=builder /build/server ./server

package/src/runtime/engine-cyberia/Dockerfile

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.3.0
+ARG UNDERPOST_VERSION=3.3.73
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0
@@ -14,7 +14,7 @@ ENV NODE_ENV=production
 
 RUN set -eux; \
     # `sudo` is required because underpost's build steps shell out to
-    # `sudo cp`/`sudo rm` (src/server/start.js); the build runs as root so sudo
+    # `sudo cp`/`sudo rm` (src/server/runtime/start.js); the build runs as root so sudo
     # is just a passthrough, but the binary must exist.
     dnf install -y git openssl tar xz sudo; \
     arch="$(uname -m)"; \
@@ -26,10 +26,22 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
     dnf clean all; rm -rf /var/cache/dnf; \
     npm cache clean --force
 
+
+# The builder's own `underpost clone` calls below run on this same CLI, and the runtime stage
+# inherits it through `COPY --from=builder /usr/local/`.
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version; \
+    # The staged package must be the pinned release: a drift here would ship a CLI the
+    # deployment manifests were not built against.
+    underpost --version | grep -Fq "${UNDERPOST_VERSION}"
+
 WORKDIR /home/dd
 
 # Comma-separated instance codes to provision (backup dir + optional saga).
@@ -38,7 +50,7 @@ WORKDIR /home/dd
 # `--build-arg INSTANCE_CODES=...`. Declared as an ARG (not a marker-wrapped
 # shell string) so the value is clean — a `/** … */` literal in the shell would
 # glob-expand in the `for` loop below.
-ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST"
+ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST,TEST"
 
 RUN --mount=type=secret,id=github_username \
     # --mount=type=secret,id=github_token \
@@ -83,7 +95,7 @@ RUN --mount=type=secret,id=github_username \
     cd /home/dd/engine; \
     # --- install deps + env, then replay build-safe itc provisioning ----------
     npm install; \
-    node bin env dd-cyberia production; \
+    node bin app load --env production --args deploy-id=dd-cyberia; \
     ( cd /home/dd/engine/hardhat && npm install --include=dev ); \
     # --- build the client bundle (assets are now in place) --------------------
     cd /home/dd/engine; \
@@ -136,11 +148,15 @@ COPY --from=builder /usr/local/ /usr/local/
 RUN dnf install -y libstdc++ git sudo && dnf clean all && rm -rf /var/cache/dnf && \
     useradd --create-home --home-dir /home/dd --shell /usr/sbin/nologin dd && \
     # The runtime runs as `dd`, but `underpost start --build` shells out to `sudo cp`/`sudo rm`
-    # (src/server/start.js). Grant passwordless sudo so those succeed without a TTY/password.
+    # (src/server/runtime/start.js). Grant passwordless sudo so those succeed without a TTY/password.
     printf 'dd ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/dd && chmod 0440 /etc/sudoers.d/dd && \
-    # underpost persists its global env at $(npm root -g)/underpost/.env; the
-    # non-root runtime user must be able to write it (fixes EACCES on start).
-    chown -R dd:dd /usr/local/lib/node_modules/underpost
+    # underpost persists its global env and container state under
+    # `$(npm root -g)/underpost` (getUnderpostRootPath). That path is a STORE directory, not
+    # the CLI package tree: the staged package installs under its own package name, and
+    # `underpost start --build` re-links the bin at the pulled checkout without moving the
+    # store (src/server/runtime/start.js#linkRuntimeCli). Create it here — the non-root
+    # runtime user cannot mkdir inside /usr/local itself (EACCES on the first state write).
+    mkdir -p "$(npm root -g)/underpost" && chown -R dd:dd "$(npm root -g)/underpost"
 
 # Copy ONLY the scrubbed runtime tree — no .git, no token, no caches.
 COPY --from=builder --chown=dd:dd /home/dd/engine /home/dd/engine

package/src/runtime/engine-cyberia/Dockerfile.dev

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.3.0
+ARG UNDERPOST_VERSION=3.3.73
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0
@@ -14,7 +14,7 @@ ENV NODE_ENV=development
 
 RUN set -eux; \
     # `sudo` is required because underpost's build steps shell out to
-    # `sudo cp`/`sudo rm` (src/server/start.js); the build runs as root so sudo
+    # `sudo cp`/`sudo rm` (src/server/runtime/start.js); the build runs as root so sudo
     # is just a passthrough, but the binary must exist.
     dnf install -y git openssl tar xz sudo; \
     arch="$(uname -m)"; \
@@ -26,10 +26,22 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
     dnf clean all; rm -rf /var/cache/dnf; \
     npm cache clean --force
 
+
+# The builder's own `underpost clone` calls below run on this same CLI, and the runtime stage
+# inherits it through `COPY --from=builder /usr/local/`.
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version; \
+    # The staged package must be the pinned release: a drift here would ship a CLI the
+    # deployment manifests were not built against.
+    underpost --version | grep -Fq "${UNDERPOST_VERSION}"
+
 WORKDIR /home/dd
 
 # Comma-separated instance codes to provision (backup dir + optional saga).
@@ -38,7 +50,7 @@ WORKDIR /home/dd
 # `--build-arg INSTANCE_CODES=...`. Declared as an ARG (not a marker-wrapped
 # shell string) so the value is clean — a `/** … */` literal in the shell would
 # glob-expand in the `for` loop below.
-ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST"
+ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST,TEST"
 
 RUN --mount=type=secret,id=github_username \
     # --mount=type=secret,id=github_token \
@@ -83,7 +95,7 @@ RUN --mount=type=secret,id=github_username \
     cd /home/dd/engine; \
     # --- install deps + env, then replay build-safe itc provisioning ----------
     npm install; \
-    node bin env dd-cyberia development; \
+    node bin app load --env development --args deploy-id=dd-cyberia; \
     ( cd /home/dd/engine/hardhat && npm install --include=dev ); \
     # --- build the client bundle (assets are now in place) --------------------
     cd /home/dd/engine; \
@@ -136,11 +148,15 @@ COPY --from=builder /usr/local/ /usr/local/
 RUN dnf install -y libstdc++ git sudo && dnf clean all && rm -rf /var/cache/dnf && \
     useradd --create-home --home-dir /home/dd --shell /usr/sbin/nologin dd && \
     # The runtime runs as `dd`, but `underpost start --build` shells out to `sudo cp`/`sudo rm`
-    # (src/server/start.js). Grant passwordless sudo so those succeed without a TTY/password.
+    # (src/server/runtime/start.js). Grant passwordless sudo so those succeed without a TTY/password.
     printf 'dd ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/dd && chmod 0440 /etc/sudoers.d/dd && \
-    # underpost persists its global env at $(npm root -g)/underpost/.env; the
-    # non-root runtime user must be able to write it (fixes EACCES on start).
-    chown -R dd:dd /usr/local/lib/node_modules/underpost
+    # underpost persists its global env and container state under
+    # `$(npm root -g)/underpost` (getUnderpostRootPath). That path is a STORE directory, not
+    # the CLI package tree: the staged package installs under its own package name, and
+    # `underpost start --build` re-links the bin at the pulled checkout without moving the
+    # store (src/server/runtime/start.js#linkRuntimeCli). Create it here — the non-root
+    # runtime user cannot mkdir inside /usr/local itself (EACCES on the first state write).
+    mkdir -p "$(npm root -g)/underpost" && chown -R dd:dd "$(npm root -g)/underpost"
 
 # Copy ONLY the scrubbed runtime tree — no .git, no token, no caches.
 COPY --from=builder --chown=dd:dd /home/dd/engine /home/dd/engine

package/src/runtime/engine-cyberia/Dockerfile.test

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.3.0
+ARG UNDERPOST_VERSION=3.3.73
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0
@@ -14,7 +14,7 @@ ENV NODE_ENV=development
 
 RUN set -eux; \
     # `sudo` is required because underpost's build steps shell out to
-    # `sudo cp`/`sudo rm` (src/server/start.js); the build runs as root so sudo
+    # `sudo cp`/`sudo rm` (src/server/runtime/start.js); the build runs as root so sudo
     # is just a passthrough, but the binary must exist.
     dnf install -y git openssl tar xz sudo; \
     arch="$(uname -m)"; \
@@ -71,7 +71,7 @@ RUN --mount=type=secret,id=github_token \
     \
     # --- install deps + env, then replay build-safe itc provisioning ----------
     npm install; \
-    node bin env dd-cyberia development; \
+    node bin app load --env development --args deploy-id=dd-cyberia; \
     node bin fs --pull --recursive --deploy-id dd-cyberia --storage-file-path './engine-private/conf/dd-cyberia/storage.engine-cyberia.json'; \
     ( cd /home/dd/engine/hardhat && npm install --include=dev ); \
     ( cd /home/dd/engine && underpost clone underpostnet/cyberia-server ); \
@@ -140,7 +140,7 @@ COPY --from=builder /usr/local/ /usr/local/
 RUN dnf install -y libstdc++ git sudo && dnf clean all && rm -rf /var/cache/dnf && \
     useradd --create-home --home-dir /home/dd --shell /usr/sbin/nologin dd && \
     # The runtime runs as `dd`, but `underpost start --build` shells out to `sudo cp`/`sudo rm`
-    # (src/server/start.js). Grant passwordless sudo so those succeed without a TTY/password.
+    # (src/server/runtime/start.js). Grant passwordless sudo so those succeed without a TTY/password.
     printf 'dd ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/dd && chmod 0440 /etc/sudoers.d/dd && \
     # underpost persists its global env at $(npm root -g)/underpost/.env; the
     # non-root runtime user must be able to write it (fixes EACCES on start).

package/src/runtime/engine-cyberia/docker-compose.yml

@@ -135,7 +135,7 @@ services:
   # server starts but rejects connections until seeded). Serves REST/WS on 4005
   # and the engine gRPC data service on 50051.
   engine-cyberia-runtime:
-    image: ${ENGINE_CYBERIA_IMAGE:-underpost/engine-cyberia-dev}:${ENGINE_CYBERIA_TAG:-v3.3.0}
+    image: ${ENGINE_CYBERIA_IMAGE:-underpost/engine-cyberia-dev}:${ENGINE_CYBERIA_TAG:-v3.3.73}
     container_name: dd-cyberia-engine
     command:
       - /bin/sh
@@ -190,7 +190,7 @@ services:
   # gateway on host port 8081, so one port can route every instance path.
 
   cyberia-server-runtime:
-    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.0}
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.73}
     container_name: dd-cyberia-server
     environment:
       INSTANCE_CODE: amethyst-strata-expansion
@@ -226,7 +226,7 @@ services:
     restart: unless-stopped
 
   cyberia-server-forest:
-    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.0}
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.73}
     container_name: dd-cyberia-server-forest
     environment:
       INSTANCE_CODE: FOREST
@@ -262,7 +262,7 @@ services:
     restart: unless-stopped
 
   cyberia-server-test:
-    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.0}
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.73}
     container_name: dd-cyberia-server-test
     environment:
       INSTANCE_CODE: TEST
@@ -309,7 +309,7 @@ services:
   #   cyberia-server-test   -> cyberia-client-test
 
   cyberia-client-runtime:
-    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.0}
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.73}
     container_name: dd-cyberia-client
     environment:
       CYBERIA_PORT: '8081'
@@ -334,7 +334,7 @@ services:
     restart: unless-stopped
 
   cyberia-client-forest:
-    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.0}
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.73}
     container_name: dd-cyberia-client-forest
     environment:
       CYBERIA_PORT: '8081'
@@ -359,7 +359,7 @@ services:
     restart: unless-stopped
 
   cyberia-client-test:
-    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.0}
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.73}
     container_name: dd-cyberia-client-test
     environment:
       CYBERIA_PORT: '8081'

package/src/runtime/express/Express.js

@@ -12,18 +12,19 @@ import swaggerUi from 'swagger-ui-express';
 import compression from 'compression';
 import { createServer } from 'http';
 
-import { loggerFactory, loggerMiddleware } from '../../server/logger.js';
+import { loggerFactory, loggerMiddleware } from '../../server/ops/logger.js';
 import { getCapVariableName, newInstance } from '../../client/components/core/CommonJs.js';
 import { MailerProvider } from '../../mailer/MailerProvider.js';
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { createPeerServer } from '../../server/peer.js';
-import { createValkeyConnection } from '../../server/valkey.js';
-import { applySecurity, authMiddlewareFactory } from '../../server/auth.js';
+import { createPeerServer } from '../../server/network/peer.js';
+import { createValkeyConnection } from '../../db/valkey/Valkey.js';
+import { applySecurity, authMiddlewareFactory } from '../../server/security/auth.js';
 import { ssrMiddlewareFactory } from '../../client-builder/ssr.js';
 import { buildSwaggerUiOptions } from '../../client-builder/client-build-docs.js';
 
-import { shellExec } from '../../server/process.js';
-import { devProxyHostFactory, isDevProxyContext, isTlsDevProxy } from '../../server/conf.js';
+import { shellExec } from '../../server/runtime/process.js';
+import { devProxyHostFactory, isDevProxyContext, isTlsDevProxy } from '../../server/runtime/conf.js';
+import { metricsPathFactory } from '../../server/ops/monitoring.js';
 
 import Underpost from '../../index.js';
 
@@ -113,8 +114,9 @@ class ExpressService {
       return next();
     });
 
-    // Metrics endpoint
-    app.get(`${path === '/' ? '' : path}/metrics`, async (req, res) => {
+    // Metrics endpoint. The route is shared with the Prometheus scrape config
+    // so a target can never point at a path this server does not serve.
+    app.get(metricsPathFactory(path), async (req, res) => {
       res.set('Content-Type', promRegister.contentType);
       return res.end(await promRegister.metrics());
     });
@@ -163,19 +165,22 @@ class ExpressService {
     // Create HTTP server for regular instances (required for WebSockets)
     const server = createServer({}, app);
 
-    if (!apiBaseHost) {
-      // Swagger path definition
-      const swaggerJsonPath = `./public/${host}${path === '/' ? path : `${path}/`}swagger-output.json`;
-      const swaggerPath = `${path === '/' ? `/api-docs` : `${path}/api-docs`}`;
-
-      // Flag swagger requests before security middleware
-      if (fs.existsSync(swaggerJsonPath)) {
-        app.use(swaggerPath, (req, res, next) => {
-          res.locals.isSwagger = true;
-          next();
-        });
-      }
+    // Swagger path definition. The UI is served by every instance that renders the
+    // client, so a split client/API deployment keeps `api-docs` same-origin with the
+    // page that frames it.
+    const swaggerJsonPath = `./public/${host}${path === '/' ? path : `${path}/`}swagger-output.json`;
+    const swaggerPath = `${path === '/' ? `/api-docs` : `${path}/api-docs`}`;
+    const swaggerEnabled = fs.existsSync(swaggerJsonPath);
+
+    // Flag swagger requests before security middleware
+    if (swaggerEnabled) {
+      app.use(swaggerPath, (req, res, next) => {
+        res.locals.isSwagger = true;
+        next();
+      });
+    }
 
+    if (!apiBaseHost) {
       // Security and CORS — must run before swagger-ui so CSP headers are included in swagger responses
       if (process.env.NODE_ENV === 'development' && useLocalSsl)
         origins = origins.map((origin) => origin.replace('http', 'https'));
@@ -184,13 +189,6 @@ class ExpressService {
         origin: origins,
       });
 
-      // Swagger UI setup (after security middleware so responses carry correct CSP headers)
-      if (fs.existsSync(swaggerJsonPath)) {
-        const swaggerDoc = JSON.parse(fs.readFileSync(swaggerJsonPath, 'utf8'));
-        const swaggerUiOptions = await buildSwaggerUiOptions();
-        app.use(swaggerPath, swaggerUi.serve, swaggerUi.setup(swaggerDoc, swaggerUiOptions));
-      }
-
       // Database and Valkey connections
       if (db && apis) await DataBaseProviderService.load({ apis, host, path, db });
 
@@ -261,6 +259,13 @@ class ExpressService {
       }
     }
 
+    // Swagger UI setup (after security middleware so responses carry correct CSP headers)
+    if (swaggerEnabled) {
+      const swaggerDoc = JSON.parse(fs.readFileSync(swaggerJsonPath, 'utf8'));
+      const swaggerUiOptions = await buildSwaggerUiOptions();
+      app.use(swaggerPath, swaggerUi.serve, swaggerUi.setup(swaggerDoc, swaggerUiOptions));
+    }
+
     // SSR middleware loading
     const ssr = await ssrMiddlewareFactory({ app, directory, rootHostPath, path });
     for (const [_, ssrMiddleware] of Object.entries(ssr)) app.use(ssrMiddleware);

package/src/runtime/lampp/Lampp.js

@@ -6,8 +6,9 @@
  */
 
 import fs from 'fs-extra';
-import { getRootDirectory, shellCd, shellExec } from '../../server/process.js';
-import { loggerFactory } from '../../server/logger.js';
+import { getRootDirectory, shellCd, shellExec } from '../../server/runtime/process.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import Underpost from '../../index.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -71,12 +72,8 @@ class LamppService {
    * @memberof LamppService
    */
   async initService(options = { daemon: false }) {
-    let cmd;
-
-    // 1. Write the current virtual host router configuration
     fs.writeFileSync(`/opt/lampp/etc/extra/httpd-vhosts.conf`, this.router || '', 'utf8');
 
-    // 2. Ensure the vhosts file is included in the main httpd.conf
     const httpdConfPath = `/opt/lampp/etc/httpd.conf`;
     fs.writeFileSync(
       httpdConfPath,
@@ -86,12 +83,9 @@ class LamppService {
       'utf8',
     );
 
-    // 3. Stop the service before making port changes
-    cmd = `sudo /opt/lampp/lampp stop`;
-    shellExec(cmd);
+    shellExec(`sudo /opt/lampp/lampp stop`);
 
-    // 4. Comment out default port Listen directives (80 and 443) to prevent conflicts
-    // Modify httpd.conf (port 80)
+    // Every vhost declares its own Listen, so the stock 80/443 directives would double-bind.
     if (!fs.readFileSync(httpdConfPath, 'utf8').match(/# Listen 80/))
       fs.writeFileSync(
         httpdConfPath,
@@ -99,7 +93,6 @@ class LamppService {
         'utf8',
       );
 
-    // Modify httpd-ssl.conf (port 443)
     const httpdSslConfPath = `/opt/lampp/etc/extra/httpd-ssl.conf`;
     if (fs.existsSync(httpdSslConfPath) && !fs.readFileSync(httpdSslConfPath, 'utf8').match(/# Listen 443/))
       fs.writeFileSync(
@@ -108,7 +101,8 @@ class LamppService {
         'utf8',
       );
 
-    // 5. Modify the lampp startup script to bypass port checking for 80 and 443
+    // The startup script aborts when 80/443 are already held by the ingress proxy; short-circuit
+    // its probes so the service still comes up behind one.
     const lamppScriptPath = `/opt/lampp/lampp`;
     if (!fs.readFileSync(lamppScriptPath, 'utf8').match(/testport 443 && false/))
       fs.writeFileSync(
@@ -123,9 +117,7 @@ class LamppService {
         'utf8',
       );
 
-    // 6. Start the service
-    cmd = `sudo /opt/lampp/lampp start`;
-    shellExec(cmd);
+    shellExec(`sudo /opt/lampp/lampp start`);
   }
 
   /**
@@ -217,13 +209,15 @@ class LamppService {
    * @param {string} options.path - The base path for error documents (e.g., '/app').
    * @param {string} [options.directory] - Optional absolute path to the document root.
    * @param {string} [options.rootHostPath] - Relative path from the root directory to the document root, used if `directory` is not provided.
+   * @param {string} [options.repository] - Repository backing the document root. Each conf route
+   *   declares its own, so one host serves as many repositories as it has routes.
    * @param {boolean} [options.redirect] - If true, enables RewriteEngine for redirection.
    * @param {string} [options.redirectTarget] - The target URL for redirection.
    * @param {boolean} [options.resetRouter] - If true, clears the existing router configuration before appending the new one.
    * @returns {{disabled: boolean}} An object indicating if the service is disabled.
    * @memberof LamppService
    */
-  createApp({ port, host, path, directory, rootHostPath, redirect, redirectTarget, resetRouter }) {
+  createApp({ port, host, path, directory, rootHostPath, repository, redirect, redirectTarget, resetRouter }) {
     if (!this.enabled()) return { disabled: true };
 
     if (!this.ports.includes(port)) this.ports.push(port);
@@ -231,7 +225,17 @@ class LamppService {
 
     const documentRoot = directory ? directory : `${getRootDirectory()}${rootHostPath}`;
 
-    // Append the new VirtualHost configuration
+    if (repository) {
+      const { accessible } = Underpost.repo.provisionSiteRoot({ host, siteRoot: documentRoot, repository });
+      // The checkout keeps its `.git` so the backup pipeline can commit and push it back; the
+      // vhost below denies it over HTTP.
+      if (accessible) Underpost.repo.initLocalRepo({ path: documentRoot, origin: repository });
+      // The vhost is still emitted, so the host answers rather than vanishing from the router —
+      // but Apache cannot stat a DocumentRoot that was never created and turns every request into
+      // a blanket 403. Named here, because that 403 carries nothing pointing back at this step.
+      else logger.error(`${host}: ${documentRoot} not provisioned — this vhost will answer 403 until it is`);
+    }
+
     this.appendRouter(`
 Listen ${port}
 
@@ -305,55 +309,3 @@ Listen ${port}
 const Lampp = new LamppService();
 
 export { Lampp };
-
-// -- helper info --
-
-// ERR too many redirects:
-// Check: SELECT * FROM database.wp_options where option_name = 'siteurl' or option_name = 'home';
-// Check: wp-config.php
-// if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
-//   $_SERVER['HTTPS'] = 'on';
-// }
-// For plugins:
-// define( 'FS_METHOD', 'direct' );
-
-// ErrorDocument 404 /custom_404.html
-// ErrorDocument 500 /custom_50x.html
-// ErrorDocument 502 /custom_50x.html
-// ErrorDocument 503 /custom_50x.html
-// ErrorDocument 504 /custom_50x.html
-
-// Respond When Error Pages are Directly Requested
-
-// <Files "custom_404.html">
-//     <If "-z %{ENV:REDIRECT_STATUS}">
-//         RedirectMatch 404 ^/custom_404.html$
-//     </If>
-// </Files>
-
-// <Files "custom_50x.html">
-//     <If "-z %{ENV:REDIRECT_STATUS}">
-//         RedirectMatch 404 ^/custom_50x.html$
-//     </If>
-// </Files>
-
-// Add www or https with htaccess rewrite
-
-// Options +FollowSymLinks
-// RewriteEngine On
-// RewriteCond %{HTTP_HOST} ^example.com [NC]
-// RewriteRule ^(.*)$ http://example.com/$1 [R=301,L]
-
-// Redirect http to https with htaccess rewrite
-
-// RewriteEngine On
-// RewriteCond %{SERVER_PORT} 80
-// RewriteRule ^(.*)$ https://www.example.com/$1 [R,L]
-
-// Redirect to HTTPS with www subdomain
-
-// RewriteEngine On
-// RewriteCond %{HTTPS} off [OR]
-// RewriteCond %{HTTP_HOST} ^www\. [NC]
-// RewriteCond %{HTTP_HOST} ^(?:www\.)?(.+)$ [NC]
-// RewriteRule ^ https://%1%{REQUEST_URI} [L,NE,R=301]

package/src/runtime/nginx/Nginx.js

@@ -9,7 +9,7 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);