underpost 3.2.21 → 3.2.22

package/src/cli/monitor.js

@@ -378,34 +378,77 @@ class UnderpostMonitor {
       return deployStatusPort(deployId, env) ?? 3000;
     },
     /**
-     * Reads Phase-2 runtime readiness from a single pod over HTTP, tunneling
-     * through `kubectl port-forward` to the in-pod internal status endpoint.
+     * Reads Phase-2 runtime status from a single pod using the selected transport.
      *
-     * Transport failures (port-forward down, connection refused, HTTP error)
-     * are reported as `{ ok: false }` and must never be interpreted as success
-     * by callers — they are retried, not promoted. A reachable endpoint returns
-     * `{ ok: true, status }` with the normalized runtime contract value.
+     *   - `exec` (default): `kubectl exec … underpost config get container-status`
+     *     reads the env-file value. Synchronous, no background process — required
+     *     for custom instances (cyberia-server/client) and the safe choice for
+     *     CI/SSH. See `Deploy custom instance to K8S.md`.
+     *   - `http`: port-forward to the in-pod `/_internal/status` endpoint served
+     *     by the `underpost start` launcher (dd-* runtime deploys). Opt-in.
+     *
+     * Transport failures are reported as `{ ok: false }` and must never be read
+     * as success — they are retried, not promoted.
      *
      * @param {string} podName
      * @param {string} namespace
      * @param {number} internalPort
+     * @param {('http'|'exec')} [transport='exec']
      * @returns {Promise<{ok: boolean, status?: (string|null), transportError?: string}>}
      * @memberof UnderpostMonitor
      */
-    async readRuntimeStatus(podName, namespace, internalPort) {
-      // The local side of the tunnel MUST be an ephemeral free port: pinning it
-      // to internalPort collides with any host-local service on that number
-      // (e.g. a dev runtime on the same machine as the cluster), which makes
-      // port-forward fail to bind and every read return a false transport error.
+    async readRuntimeStatus(podName, namespace, internalPort, transport = 'exec') {
+      return transport === 'exec'
+        ? Underpost.monitor.readRuntimeStatusViaExec(podName, namespace)
+        : Underpost.monitor.readRuntimeStatusViaHttp(podName, namespace, internalPort);
+    },
+    /**
+     * Phase-2 read over `kubectl exec` (env-file transport). Works for any pod
+     * whose image bakes the underpost CLI — notably custom instances that stamp
+     * `container-status` from `lifecycle.postStart`/`preStop` hooks.
+     * @param {string} podName
+     * @param {string} namespace
+     * @returns {{ok: boolean, status?: (string|null), transportError?: string}}
+     * @memberof UnderpostMonitor
+     */
+    readRuntimeStatusViaExec(podName, namespace) {
+      try {
+        const raw = shellExec(
+          `sudo kubectl exec ${podName} -n ${namespace} -- sh -c 'underpost config get container-status --plain'`,
+          { silent: true, disableLog: true, stdout: true, silentOnError: true },
+        );
+        const status = normalizeContainerStatus(raw ? raw.toString().trim() : '');
+        return status === undefined ? { ok: false, transportError: 'empty_status' } : { ok: true, status };
+      } catch (error) {
+        return { ok: false, transportError: error?.code || error?.message || 'exec_failed' };
+      }
+    },
+    /**
+     * Phase-2 read over `kubectl port-forward` + HTTP `/_internal/status`.
+     *
+     * The local side of the tunnel MUST be an ephemeral free port: pinning it to
+     * internalPort collides with any host-local service on that number (e.g. a
+     * dev runtime on the same machine as the cluster), making port-forward fail
+     * to bind and every read return a false transport error.
+     *
+     * @param {string} podName
+     * @param {string} namespace
+     * @param {number} internalPort
+     * @returns {Promise<{ok: boolean, status?: (string|null), transportError?: string}>}
+     * @memberof UnderpostMonitor
+     */
+    async readRuntimeStatusViaHttp(podName, namespace, internalPort) {
       const override = parseInt(process.env.UNDERPOST_PF_LOCAL_PORT);
       const localPort = Number.isNaN(override) ? await Underpost.monitor.findFreePort() : override;
       const url = `http://127.0.0.1:${localPort}${INTERNAL_STATUS_PATH}`;
       let portForward;
       try {
-        // `exec` collapses the shell so the tracked child PID is the
-        // sudo/kubectl process, letting the SIGTERM teardown reach the tunnel.
+        // `exec` makes the tracked child the sudo/kubectl process (so kill
+        // reaches it); stdio is redirected to /dev/null so the tunnel never
+        // inherits — and therefore never holds open — a CI/SSH session's pipes,
+        // which would hang the job after a successful deploy.
         portForward = shellExec(
-          `exec sudo kubectl port-forward pod/${podName} ${localPort}:${internalPort} -n ${namespace}`,
+          `exec sudo kubectl port-forward pod/${podName} ${localPort}:${internalPort} -n ${namespace} </dev/null >/dev/null 2>&1`,
           { async: true, silent: true, disableLog: true, silentOnError: true },
         );
       } catch (_) {
@@ -440,12 +483,26 @@ class UnderpostMonitor {
      * two-phase state machine.
      *
      *   Phase 1 (Kubernetes): pod `Ready` condition via `checkDeploymentReadyStatus`.
-     *   Phase 2 (Runtime):    `running-deployment` from the in-pod internal
-     *                         status endpoint, read over HTTP (`readRuntimeStatus`).
+     *   Phase 2 (Runtime):    `container-status`, read via the selected transport.
+     *
+     * Two deployment shapes are supported via `options`:
+     *   - `runtime` gate (default, dd-* deploys): the `underpost start` launcher
+     *     stamps `running-deployment`. Success requires K8S Ready AND every pod
+     *     reporting `running-deployment`.
+     *   - `kubernetes` gate (custom instances, e.g. cyberia): the runtime is a
+     *     bare binary; K8S `readinessProbe` (TCP) IS the running signal and
+     *     `container-status` is stamped to `initializing`/`stopping` by lifecycle
+     *     hooks. Success requires K8S Ready; the status read is used only for
+     *     fast `error` detection and display.
+     *
+     * Phase-2 transport defaults to `exec` (`kubectl exec`, no background
+     * process). The `http` transport (`kubectl port-forward` → `/_internal/status`)
+     * is opt-in via `options.statusTransport='http'` or
+     * `UNDERPOST_STATUS_TRANSPORT=http`; it must not be used in CI/SSH sessions
+     * where a stray tunnel can hang the job.
      *
-     * Contract:
-     *   - Success requires BOTH phases; runtime readiness is never declared
-     *     before Kubernetes readiness.
+     * Contract (both shapes):
+     *   - Runtime readiness is never declared before Kubernetes readiness.
      *   - An explicit runtime `error` (or a fatal pod status) transitions
      *     immediately to `failed` (throw → CD exit 1).
      *   - Transport failures never count as success and never advance state.
@@ -457,16 +514,27 @@ class UnderpostMonitor {
      * @param {string} targetTraffic - Target traffic status for the deployment.
      * @param {Array<string>} ignorePods - List of pod names to ignore.
      * @param {string} [namespace='default'] - Kubernetes namespace for the deployment.
+     * @param {object} [options] - Monitoring shape.
+     * @param {('runtime'|'kubernetes')} [options.readyGate='runtime'] - Running-signal owner.
+     * @param {('http'|'exec')} [options.statusTransport='http'] - Phase-2 read transport.
      * @returns {object} - Object containing the ready status of the deployment.
      * @memberof UnderpostMonitor
      */
-    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default') {
+    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default', options = {}) {
       const delayMs = parseInt(process.env.UNDERPOST_MONITOR_DELAY_MS) || 1000;
       const maxIterations = parseInt(process.env.UNDERPOST_MONITOR_MAX_ITERATIONS) || 3000;
       const deploymentId = `${deployId}-${env}-${targetTraffic}`;
       const tag = `[${deploymentId}]`;
       const expectedStatus = RUNTIME_STATUS.RUNNING;
-      const internalPort = await Underpost.monitor.deployInternalPort(deployId, env);
+      const readyGate = options.readyGate === 'kubernetes' ? 'kubernetes' : 'runtime';
+      // Default to `exec`: a single synchronous `kubectl exec` read leaves no
+      // background process behind. The `http` transport spawns `kubectl
+      // port-forward` children that, if orphaned, inherit a CI/SSH session's
+      // stdio and hang the job after a successful deploy — opt in explicitly.
+      const statusTransport =
+        (options.statusTransport || process.env.UNDERPOST_STATUS_TRANSPORT) === 'http' ? 'http' : 'exec';
+      const internalPort =
+        statusTransport === 'http' ? await Underpost.monitor.deployInternalPort(deployId, env) : null;
       const podErrorStates = ['error', 'crashloopbackoff', 'oomkilled', 'imagepullbackoff', 'errimagepull'];
 
       const emit = (state, status) =>
@@ -478,7 +546,15 @@ class UnderpostMonitor {
           timestamp: new Date().toISOString(),
         });
 
-      logger.info('Deployment init', { deployId, env, targetTraffic, namespace, internalPort });
+      logger.info('Deployment init', {
+        deployId,
+        env,
+        targetTraffic,
+        namespace,
+        internalPort,
+        readyGate,
+        statusTransport,
+      });
       emit('pending');
 
       const runtimeStatusCache = new Map();
@@ -513,12 +589,12 @@ class UnderpostMonitor {
         const allPodsK8sReady = result.notReadyPods.length === 0;
         if (allPodsK8sReady) emit('pod_ready');
 
-        // Phase 2: runtime readiness over HTTP. Transport failures neither
-        // advance state nor count as success; explicit `error` is terminal.
+        // Phase 2: runtime status via the selected transport. Transport failures
+        // neither advance state nor count as success; explicit `error` is terminal.
         let allRuntimeRead = true;
         for (const pod of allPods) {
           if (!pod?.NAME) continue;
-          const read = await Underpost.monitor.readRuntimeStatus(pod.NAME, namespace, internalPort);
+          const read = await Underpost.monitor.readRuntimeStatus(pod.NAME, namespace, internalPort, statusTransport);
           if (!read.ok) {
             allRuntimeRead = false;
             emit('runtime_booting', `transport:${read.transportError}`);
@@ -526,6 +602,9 @@ class UnderpostMonitor {
           }
           const status = read.status;
           if (status === RUNTIME_STATUS.ERROR) throw new Error(`Pod ${pod.NAME} reported runtime status=error`);
+          // Regression (advanced → empty/build) means a pod restarted. Under the
+          // kubernetes gate the runtime never advances past `initializing`, so
+          // only treat a drop to empty/build as a regression there.
           if (advancedPods.has(pod.NAME) && (!status || status === RUNTIME_STATUS.BUILD))
             throw new Error(`Pod ${pod.NAME} runtime status regressed (${status ?? 'empty'}) — pod likely restarted`);
           if (status && status !== RUNTIME_STATUS.BUILD) advancedPods.add(pod.NAME);
@@ -533,8 +612,13 @@ class UnderpostMonitor {
           emit('runtime_booting', status);
         }
 
+        // Under the kubernetes gate the readinessProbe is the running signal, so
+        // K8S Ready alone confirms Phase 2; the status read above is kept only
+        // for `error` fast-fail and display.
         const allRuntimeReady =
-          allRuntimeRead && allPods.every((pod) => runtimeStatusCache.get(pod.NAME) === expectedStatus);
+          readyGate === 'kubernetes'
+            ? true
+            : allRuntimeRead && allPods.every((pod) => runtimeStatusCache.get(pod.NAME) === expectedStatus);
 
         for (const pod of allPods) {
           const status = runtimeStatusCache.get(pod.NAME) || 'waiting for status';
@@ -550,11 +634,12 @@ class UnderpostMonitor {
           );
         }
 
-        // Terminal success requires BOTH phases. runtime_ready cannot precede
+        // Terminal success requires both phases. runtime_ready cannot precede
         // Kubernetes readiness.
         if (allPodsK8sReady && allRuntimeReady) {
-          emit('runtime_ready', expectedStatus);
-          logger.info(`${tag} | Deployment ready (K8S Ready + runtime ${expectedStatus})`);
+          const readySignal = readyGate === 'kubernetes' ? 'K8S readinessProbe' : `runtime ${expectedStatus}`;
+          emit('runtime_ready', readyGate === 'kubernetes' ? 'k8s-ready' : expectedStatus);
+          logger.info(`${tag} | Deployment ready (K8S Ready + ${readySignal})`);
           return result;
         }
 

package/src/cli/repository.js

@@ -8,6 +8,7 @@ import dotenv from 'dotenv';
 import { commitData } from '../client/components/core/CommonJs.js';
 import { pbcopy, shellCd, shellExec } from '../server/process.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
+import path from 'path';
 import fs from 'fs-extra';
 import {
   getNpmRootPath,
@@ -1738,6 +1739,8 @@ Prevent build private config repo.`,
       if (!fs.existsSync(repoPath)) {
         shellExec(`cd .. && underpost clone ${gitUri}`, { silent: true });
       } else {
+        const repoAbsPath = path.resolve(repoPath);
+        shellExec(`git config --global --add safe.directory '${repoAbsPath}'`);
         shellExec(`cd ${repoPath} && git checkout . && git clean -f -d && underpost pull . ${gitUri}`, {
           silent: true,
         });

package/src/cli/run.js

@@ -120,6 +120,7 @@ const logger = loggerFactory(import.meta);
  * @property {boolean} skipFullBuild - Whether to skip the full client bundle build during deployment (supported by: sync, template-deploy).
  * @property {boolean} pullBundle - Whether to pull the bundle before running. Use together with --skip-full-build to skip the local build entirely (supported by: sync, template-deploy).
  * @property {boolean} remove - Whether to remove/teardown resources instead of creating them (e.g. delete-expose for k3s proxy devices in dev-cluster).
+ * @property {boolean} test - Whether to enable test/generic-purpose mode (e.g. use self-signed TLS instead of cert-manager).
  * @memberof UnderpostRun
  */
 const DEFAULT_OPTION = {
@@ -188,6 +189,7 @@ const DEFAULT_OPTION = {
   skipFullBuild: false,
   pullBundle: false,
   remove: false,
+  test: false,
 };
 
 /**
@@ -223,7 +225,7 @@ class UnderpostRun {
         shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''}`);
 
         shellExec(
-          `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb4 --service-host ${mongoHosts.join(
+          `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb --service-host ${mongoHosts.join(
             ',',
           )} --pull-image`,
         );
@@ -1007,8 +1009,19 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
             // pathRewritePolicy,
           });
         if (options.tls) {
-          shellExec(`sudo kubectl delete Certificate ${_host} -n ${options.namespace} --ignore-not-found`);
-          proxyYaml += Underpost.deploy.buildCertManagerCertificate({ ...options, host: _host });
+          if (options.test) {
+            const sslDir = `./engine-private/ssl/${_host}`;
+            const nameSafe = _host.replace(/[^a-zA-Z0-9_.-]/g, '_');
+            fs.mkdirpSync(sslDir);
+            shellExec(`bash ./scripts/ssl.sh "${sslDir}" "${_host}"`);
+            shellExec(`kubectl delete secret ${_host} -n ${options.namespace} --ignore-not-found`);
+            shellExec(
+              `kubectl create secret tls ${_host} --cert="${sslDir}/${nameSafe}.pem" --key="${sslDir}/${nameSafe}-key.pem" -n ${options.namespace}`,
+            );
+          } else {
+            shellExec(`sudo kubectl delete Certificate ${_host} -n ${options.namespace} --ignore-not-found`);
+            proxyYaml += Underpost.deploy.buildCertManagerCertificate({ ...options, host: _host });
+          }
         }
         // console.log(proxyYaml);
         shellExec(`kubectl delete HTTPProxy ${_host} --namespace ${options.namespace} --ignore-not-found`);
@@ -1077,6 +1090,7 @@ EOF
         // Examples images:
         // `underpost/underpost-engine:${Underpost.version}`
         // `localhost/rockylinux9-underpost:${Underpost.version}`
+        if (options.imageName) _image = options.imageName;
         if (!_image) _image = `underpost/underpost-engine:${Underpost.version}`;
 
         if (_image && !_image.startsWith('localhost'))
@@ -1172,12 +1186,16 @@ EOF
 `,
           { disableLog: true },
         );
+        // Custom instances run a bare binary (no `underpost start` / internal
+        // HTTP endpoint): Kubernetes readiness is the running signal and
+        // container-status is read via exec. See `Deploy custom instance to K8S.md`.
         const { ready, readyPods } = await Underpost.monitor.monitorReadyRunner(
           _deployId,
           env,
           targetTraffic,
           ignorePods,
           options.namespace,
+          { readyGate: 'kubernetes', statusTransport: 'exec' },
         );
 
         if (!ready) {
@@ -1187,7 +1205,7 @@ EOF
         shellExec(
           `${baseCommand} run${baseClusterCommand} --namespace ${options.namespace}` +
             `${options.nodeName ? ` --node-name ${options.nodeName}` : ''}` +
-            `${options.tls ? ` --tls` : ''}` +
+            `${options.tls ? ` --tls ${options.test ? '--test' : ''}` : ''}` +
             ` instance-promote '${path}'`,
         );
       }

package/src/client/components/core/PanelForm.js

@@ -73,7 +73,7 @@ class PanelForm {
       parentIdModal: undefined,
       route: 'home',
       htmlFormHeader: async () => '',
-      firsUpdateEvent: async () => { },
+      firsUpdateEvent: async () => {},
       share: {
         copyLink: false,
         copySourceMd: false,
@@ -196,12 +196,12 @@ class PanelForm {
               <img
                 class="abs center"
                 style="${renderCssAttr({
-              style: {
-                width: '100px',
-                height: '100px',
-                opacity: 0.2,
-              },
-            })}"
+                  style: {
+                    width: '100px',
+                    height: '100px',
+                    opacity: 0.2,
+                  },
+                })}"
                 src="${defaultUrlImage}"
               />
             `,
@@ -382,15 +382,15 @@ class PanelForm {
             // It will be filtered from the tags array to keep visibility control separate from content tags
             const tags = data.tags
               ? uniqueArray(
-                data.tags
-                  .replaceAll('/', ',')
-                  .replaceAll('-', ',')
-                  .replaceAll(' ', ',')
-                  .split(',')
-                  .map((t) => t.trim())
-                  .filter((t) => t)
-                  .concat(prefixTags),
-              )
+                  data.tags
+                    .replaceAll('/', ',')
+                    .replaceAll('-', ',')
+                    .replaceAll(' ', ',')
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t)
+                    .concat(prefixTags),
+                )
               : prefixTags;
             let originObj, originFileObj, indexOriginObj;
             if (editId) {
@@ -432,8 +432,8 @@ class PanelForm {
               // In edit mode, null means user cleared the file - we need to tell server to remove it
               const isFileCleared = data.fileId === null && editId;
               await (async () => {
-                // When file is null and not the first iteration or not in edit mode, skip upload
-                if (!file && !isFileCleared) return;
+                // When file is null, no markdown content, and not clearing a file, skip upload
+                if (!file && !isFileCleared && !hasMdContent) return;
                 // When user cleared file in edit mode, set fileId=null so server removes the reference
                 if (isFileCleared) {
                   fileId = null;
@@ -489,8 +489,8 @@ class PanelForm {
                 message: documentMessage,
                 data: documentData,
               } = originObj && indexFormDoc === 0
-                  ? await DocumentService.put({ id: originObj._id, body })
-                  : await DocumentService.post({
+                ? await DocumentService.put({ id: originObj._id, body })
+                : await DocumentService.post({
                     body,
                   });
               const newDoc = {
@@ -518,12 +518,12 @@ class PanelForm {
                 fileId: {
                   fileBlob: file
                     ? {
-                      data: {
-                        data: await getDataFromInputFile(file),
-                      },
-                      mimetype: file.type,
-                      name: file.name,
-                    }
+                        data: {
+                          data: await getDataFromInputFile(file),
+                        },
+                        mimetype: file.type,
+                        name: file.name,
+                      }
                     : undefined,
                   filePlain: undefined,
                 },
@@ -742,36 +742,36 @@ class PanelForm {
             <div
               class="in fll ssr-shimmer-search-box"
               style="${renderCssAttr({
-            style: {
-              width: '80%',
-              height: '30px',
-              top: '-13px',
-              left: '10px',
-            },
-          })}"
+                style: {
+                  width: '80%',
+                  height: '30px',
+                  top: '-13px',
+                  left: '10px',
+                },
+              })}"
             ></div>
           </div>`,
           createdAt: html`<div class="fl">
             <div
               class="in fll ssr-shimmer-search-box"
               style="${renderCssAttr({
-            style: {
-              width: '50%',
-              height: '30px',
-              left: '-5px',
-            },
-          })}"
+                style: {
+                  width: '50%',
+                  height: '30px',
+                  left: '-5px',
+                },
+              })}"
             ></div>
           </div>`,
           mdFileId: html`<div class="fl section-mp">
             <div
               class="in fll ssr-shimmer-search-box"
               style="${renderCssAttr({
-            style: {
-              width: '80%',
-              height: '30px',
-            },
-          })}"
+                style: {
+                  width: '80%',
+                  height: '30px',
+                },
+              })}"
             ></div>
           </div>`.repeat(random(2, 4)),
           ssr: true,

package/src/index.js

@@ -44,7 +44,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.2.21';
+  static version = 'v3.2.22';
 
   /**
    * Required Node.js major version

package/src/server/conf.js

@@ -1856,6 +1856,7 @@ const syncPrivateConf = (deployId, extraPaths = []) => {
   if (!fs.existsSync(privateRepoPath)) {
     shellExec(`cd .. && underpost clone ${privateGitUri}`, { silent: true });
   } else {
+    shellExec(`git config --global --add safe.directory '${dir.resolve(privateRepoPath)}'`);
     shellExec(`cd ${privateRepoPath} && git checkout . && git clean -f -d && underpost pull . ${privateGitUri}`, {
       silent: true,
     });
@@ -1941,15 +1942,9 @@ const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-te
     )
   ).filter((p) => !p.startsWith('.git'));
 
-  // Clone the template from 0 if missing; otherwise reset it to a clean pristine checkout.
-  if (!fs.existsSync(toPath)) {
-    shellExec(`cd .. && node engine/bin clone ${githubUsername}/pwa-microservices-template`);
-  } else {
-    shellExec(`cd ${toPath} && git reset && git checkout . && git clean -f -d`);
-    shellExec(`node bin pull ${toPath} ${githubUsername}/pwa-microservices-template`);
-    shellExec(`sudo rm -rf ${toPath}/engine-private`);
-    shellExec(`sudo rm -rf ${toPath}/logs`);
-  }
+  fs.removeSync(`${githubUsername}/pwa-microservices-template`);
+  shellExec(`cd .. && node engine/bin clone ${githubUsername}/pwa-microservices-template`);
+
   shellExec(`cd ${toPath} && git config core.filemode false`);
 
   for (const copyPath of sourceFiles) {
@@ -2052,6 +2047,59 @@ git add .`);
   }
 };
 
+/**
+ * @method updatePrivateEngineTestRepo
+ * @description Publishes a deploy id's freshly assembled template to its private
+ * **test** source repo `engine-test-<idPart>` (separate from the production
+ * `engine-<idPart>`). A pod started with `underpost start --build --private-test-repo`
+ * clones this repo, so work-in-progress engine source can be tested end to end
+ * without touching the production source. Mirrors {@link updatePrivateTemplateRepo}
+ * but per-deploy-id and against the test repo.
+ *
+ * Assumes the deploy id template has already been assembled at the template path
+ * (run `node bin/build <deployId>` first, or use `node bin/build <deployId> --update-private`).
+ * @param {string} deployId - Concrete deploy id (e.g. `dd-core`).
+ * @returns {Promise<void>}
+ * @memberof ServerConfBuilder
+ */
+const updatePrivateEngineTestRepo = async (deployId) => {
+  const username = process.env.GITHUB_USERNAME || 'underpostnet';
+  const repoName = `engine-test-${deployId.split('-')[1]}`;
+  const templatePath = '/home/dd/pwa-microservices-template';
+  if (!fs.existsSync(templatePath))
+    throw new Error(`updatePrivateEngineTestRepo: assemble the template first (node bin/build ${deployId})`);
+
+  // Detach the assembled working tree from any engine-build git history.
+  shellExec(`sudo rm -rf ${templatePath}/.git`);
+
+  // Adopt the test repo's existing history when present (so the push is a delta);
+  // otherwise publish a fresh history on first push.
+  shellExec(`cd /home/dd && sudo rm -rf ./${repoName}.git && underpost clone --bare ${username}/${repoName}`, {
+    silent: true,
+    disableLog: true,
+    silentOnError: true,
+  });
+  if (fs.existsSync(`/home/dd/${repoName}.git`)) shellExec(`mv /home/dd/${repoName}.git ${templatePath}/.git`);
+
+  // `git init` converts the moved bare repo into a normal work-tree repo (bare
+  // clones have no work tree, so `git add` would fail), and bootstraps a fresh
+  // repo on first publish. Idempotent — mirrors updatePrivateTemplateRepo.
+  shellExec(`cd ${templatePath}
+git init
+git config user.name '${username}'
+git config user.email 'development@underpost.net'
+git add .`);
+
+  const hasChanges = shellExec(`node bin cmt ${templatePath} --has-changes`, {
+    stdout: true,
+    silent: true,
+    disableLog: true,
+  }).trim();
+  if (hasChanges === '1')
+    shellExec(`cd ${templatePath} && git commit -m 'Update ${repoName}' && underpost push . ${username}/${repoName}`);
+  else logger.info('No changes to publish', { repoName });
+};
+
 export {
   Config,
   loadConf,
@@ -2104,4 +2152,5 @@ export {
   syncDeployIdSources,
   buildTemplate,
   updatePrivateTemplateRepo,
+  updatePrivateEngineTestRepo,
 };

package/src/server/ipfs-client.js

@@ -12,6 +12,7 @@
  */
 import stringify from 'fast-json-stable-stringify';
 import { loggerFactory } from './logger.js';
+import Underpost from '../index.js';
 const logger = loggerFactory(import.meta);
 const DEFAULT_IPFS_HTTP_TIMEOUT_MS = Number(process.env.IPFS_HTTP_TIMEOUT_MS || 10000);
 const getRequestTimeoutMs = (kind = 'kubo') => {
@@ -46,21 +47,22 @@ const fetchWithTimeout = async (url, options = {}, { kind = 'kubo', label = url
  * @returns {string}
  */
 const getIpfsApiUrl = () =>
-  process.env.IPFS_API_URL || `http://${process.env.NODE_ENV === 'development' ? 'localhost' : 'ipfs-cluster'}:5001`;
+  process.env.IPFS_API_URL ||
+  `http://${process.env.NODE_ENV === 'development' && !Underpost.env.isInsideContainer() ? 'localhost' : 'ipfs-cluster'}:5001`;
 /**
  * Base URL of the IPFS Cluster REST API (port 9094).
  * @returns {string}
  */
 const getClusterApiUrl = () =>
   process.env.IPFS_CLUSTER_API_URL ||
-  `http://${process.env.NODE_ENV === 'development' ? 'localhost' : 'ipfs-cluster'}:9094`;
+  `http://${process.env.NODE_ENV === 'development' && !Underpost.env.isInsideContainer() ? 'localhost' : 'ipfs-cluster'}:9094`;
 /**
  * Base URL of the IPFS HTTP Gateway (port 8080).
  * @returns {string}
  */
 const getGatewayUrl = () =>
   process.env.IPFS_GATEWAY_URL ||
-  `http://${process.env.NODE_ENV === 'development' ? 'localhost' : 'ipfs-cluster'}:8080`;
+  `http://${process.env.NODE_ENV === 'development' && !Underpost.env.isInsideContainer() ? 'localhost' : 'ipfs-cluster'}:8080`;
 // ─────────────────────────────────────────────────────────
 //  Core: add content
 // ─────────────────────────────────────────────────────────

package/src/server/start.js

@@ -152,10 +152,16 @@ class UnderpostStartUp {
       // observable through every lifecycle phase, including build and init. Bind
       // the deployment-resolved port so it always matches the monitor's target.
       startInternalStatusServer(deployStatusPort(deployId, env));
-      setRuntimeStatus(deployId, env, RUNTIME_STATUS.BUILD);
-      if (options.build === true) await Underpost.start.build(deployId, env, options);
-      setRuntimeStatus(deployId, env, RUNTIME_STATUS.INIT);
-      if (options.run === true) await Underpost.start.run(deployId, env, options);
+      try {
+        setRuntimeStatus(deployId, env, RUNTIME_STATUS.BUILD);
+        if (options.build === true) await Underpost.start.build(deployId, env, options);
+        setRuntimeStatus(deployId, env, RUNTIME_STATUS.INIT);
+        if (options.run === true) await Underpost.start.run(deployId, env, options);
+      } catch (error) {
+        logger.error('Deployment build/init failed', { deployId, env, message: error?.message });
+        setRuntimeStatus(deployId, env, RUNTIME_STATUS.ERROR);
+        if (!Underpost.env.isInsideContainer()) throw error;
+      }
     },
     /**
      * Run itc-scripts and builds client bundle.
@@ -167,6 +173,8 @@ class UnderpostStartUp {
      * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
      * @param {boolean} options.pullBundle - When true, download pre-built client bundle from Cloudinary via pull-bundle (must be pushed first with push-bundle).
      *   This flag is independent of skipFullBuild: it can be combined with skipFullBuild or used alone.
+     * @param {boolean} options.privateTestRepo - When true, clone `engine-test-<id>` (the private test source repo
+     *   published by `node bin/build <deployId> --update-private`) instead of the production `engine-<id>` repo.
      * @memberof UnderpostStartUp
      */
     async build(
@@ -175,7 +183,11 @@ class UnderpostStartUp {
       options = { underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false, pullBundle: false },
     ) {
       const buildBasePath = `/home/dd`;
-      const repoName = `engine-${deployId.split('-')[1]}`;
+      // `--private-test-repo` clones the isolated test source repo published by
+      // `node bin/build <deployId> --update-private`, instead of the production one.
+      const repoName = options?.privateTestRepo
+        ? `engine-test-${deployId.split('-')[1]}`
+        : `engine-${deployId.split('-')[1]}`;
       if (!options.skipPullBase) {
         shellExec(`cd ${buildBasePath} && underpost clone ${process.env.GITHUB_USERNAME}/${repoName}`);
         shellExec(`mkdir -p ${buildBasePath}/engine`);