underpost 3.2.14 → 3.2.22

package/scripts/test-monitor.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+#
+# test-monitor.sh — end-to-end deploy + two-phase monitor smoke test.
+#
+# Two deployment shapes are supported (see
+# src/client/public/nexodev/docs/references/Deploy-Monitor-PRD.md and
+# 'Deploy custom instance to K8S.md'):
+#
+#   --mode runtime   `underpost start` deploy (e.g. dd-test). Monitored with the
+#                    HTTP gate: /_internal/ready probes + port-forward status.
+#   --mode instance  Custom instances from conf.instances.json (e.g. cyberia
+#                    mmo-server / mmo-client). Monitored with the kubernetes gate
+#                    (TCP readinessProbe) + exec status transport.
+#
+# Every variable in the DEFAULTS block below is overridable with a flag of the
+# same name (--env, --deploy-id, …). Run with --help for the full list.
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENGINE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "$ENGINE_DIR"
+
+# ─────────────────────────── DEFAULTS (all overridable) ───────────────────────────
+MODE=runtime                                  # runtime | instance
+ENV=development                               # development | production
+DEPLOY_ID=dd-test                             # deploy id (instance mode: parent of conf.instances.json)
+INSTANCE_IDS=                                 # instance mode: csv of ids (default: all in conf.instances.json)
+IMAGE=underpost/wp:v3.2.14                    # runtime mode image (instance mode reads image from conf)
+VERSIONS=green                                # csv of blue/green versions
+REPLICAS=1                                    # replicas per deployment
+NAMESPACE=default                             # k8s namespace
+CLUSTER=                                      # kind | kubeadm | k3s | "" (auto/none)
+TIMEOUT_RESPONSE=300000ms                     # HTTPProxy per-route response timeout
+TEMPLATE_REPO=underpostnet/pwa-microservices-template-private  # runtime mode link repo
+ENVOY_NAMESPACE=projectcontour                # ingress namespace (instance TLS exposure)
+ENVOY_SERVICE=envoy                           # ingress service (instance TLS exposure)
+HTTPS_PORT=443                                # local https port for instance TLS exposure
+
+USE_CERT=false                                # runtime: pass --cert to the proxy step
+USE_PULL_BUNDLE=false                         # runtime: include --pull-bundle in the start cmd
+USE_TLS=false                                 # generate self-signed certs + expose over HTTPS
+USE_TEST_REPO=false                           # runtime: publish src to engine-test-<id> + pod clones it (--private-test-repo)
+DO_BUILD_TEMPLATE=true                        # run `node bin/build.template --update-private`
+DO_CLUSTER_MANIFESTS=true                     # run `node bin run build-cluster-deployment-manifests`
+DO_EXPOSE=true                                # expose locally after deploy + monitor
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/test-monitor.sh [flags]
+
+Modes:
+  --mode <runtime|instance>     Deployment shape to test (default: runtime)
+
+Common (every default is overridable):
+  --env <development|production>
+  --deploy-id <id>
+  --instance-ids <csv>          instance mode only; default = all ids in conf.instances.json
+  --image <image>               runtime mode only
+  --versions <csv>              e.g. green or blue,green
+  --replicas <n>
+  --namespace <ns>
+  --cluster <kind|kubeadm|k3s|none>
+  --timeout-response <dur>      e.g. 300000ms
+  --template-repo <owner/repo>  runtime mode link repo
+  --envoy-namespace <ns>        instance TLS exposure ingress namespace
+  --envoy-service <name>        instance TLS exposure ingress service
+  --https-port <port>           local https port for instance TLS exposure
+
+Toggles (use --x / --no-x):
+  --tls | --no-tls              self-signed certs + HTTPS exposure (default: off)
+  --cert | --no-cert            runtime proxy --cert (default: off)
+  --pull-bundle | --no-pull-bundle   runtime start --pull-bundle (default: off)
+  --test-repo | --no-test-repo  runtime: publish src to engine-test-<id> and have the
+                                pod clone it via --private-test-repo (default: off)
+  --expose | --no-expose        local exposure after monitor (default: on)
+  --build-template | --no-build-template       sync private template (default: on)
+  --cluster-manifests | --no-cluster-manifests  rebuild cluster manifests (default: on)
+
+  -h, --help
+
+Examples:
+  # Runtime deploy (default), no TLS
+  scripts/test-monitor.sh
+
+  # Runtime deploy over HTTPS
+  scripts/test-monitor.sh --tls
+
+  # Runtime deploy from a work-in-progress test source repo (engine-test-<id>)
+  scripts/test-monitor.sh --test-repo
+
+  # Cyberia instances (both), dev on kind, no TLS
+  scripts/test-monitor.sh --mode instance --deploy-id dd-cyberia --cluster kind
+
+  # Only the mmo-server instance, production, over HTTPS
+  scripts/test-monitor.sh --mode instance --deploy-id dd-cyberia \
+    --instance-ids mmo-server --env production --cluster kubeadm --tls
+EOF
+}
+
+# ─────────────────────────── flag parsing ───────────────────────────
+# Supports `--key value` and `--key=value` for value flags, plus --x/--no-x toggles.
+needval() { [[ $# -ge 2 ]] || { echo "Missing value for $1" >&2; exit 1; }; }
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode) needval "$@"; MODE="$2"; shift 2;;            --mode=*) MODE="${1#*=}"; shift;;
+    --env) needval "$@"; ENV="$2"; shift 2;;              --env=*) ENV="${1#*=}"; shift;;
+    --deploy-id) needval "$@"; DEPLOY_ID="$2"; shift 2;;  --deploy-id=*) DEPLOY_ID="${1#*=}"; shift;;
+    --instance-ids) needval "$@"; INSTANCE_IDS="$2"; shift 2;; --instance-ids=*) INSTANCE_IDS="${1#*=}"; shift;;
+    --image) needval "$@"; IMAGE="$2"; shift 2;;          --image=*) IMAGE="${1#*=}"; shift;;
+    --versions) needval "$@"; VERSIONS="$2"; shift 2;;    --versions=*) VERSIONS="${1#*=}"; shift;;
+    --replicas) needval "$@"; REPLICAS="$2"; shift 2;;    --replicas=*) REPLICAS="${1#*=}"; shift;;
+    --namespace) needval "$@"; NAMESPACE="$2"; shift 2;;  --namespace=*) NAMESPACE="${1#*=}"; shift;;
+    --cluster) needval "$@"; CLUSTER="$2"; shift 2;;      --cluster=*) CLUSTER="${1#*=}"; shift;;
+    --timeout-response) needval "$@"; TIMEOUT_RESPONSE="$2"; shift 2;; --timeout-response=*) TIMEOUT_RESPONSE="${1#*=}"; shift;;
+    --template-repo) needval "$@"; TEMPLATE_REPO="$2"; shift 2;; --template-repo=*) TEMPLATE_REPO="${1#*=}"; shift;;
+    --envoy-namespace) needval "$@"; ENVOY_NAMESPACE="$2"; shift 2;; --envoy-namespace=*) ENVOY_NAMESPACE="${1#*=}"; shift;;
+    --envoy-service) needval "$@"; ENVOY_SERVICE="$2"; shift 2;; --envoy-service=*) ENVOY_SERVICE="${1#*=}"; shift;;
+    --https-port) needval "$@"; HTTPS_PORT="$2"; shift 2;; --https-port=*) HTTPS_PORT="${1#*=}"; shift;;
+    --tls) USE_TLS=true; shift;;                          --no-tls) USE_TLS=false; shift;;
+    --cert) USE_CERT=true; shift;;                        --no-cert) USE_CERT=false; shift;;
+    --pull-bundle) USE_PULL_BUNDLE=true; shift;;          --no-pull-bundle) USE_PULL_BUNDLE=false; shift;;
+    --test-repo) USE_TEST_REPO=true; shift;;              --no-test-repo) USE_TEST_REPO=false; shift;;
+    --expose) DO_EXPOSE=true; shift;;                     --no-expose) DO_EXPOSE=false; shift;;
+    --build-template) DO_BUILD_TEMPLATE=true; shift;;     --no-build-template) DO_BUILD_TEMPLATE=false; shift;;
+    --cluster-manifests) DO_CLUSTER_MANIFESTS=true; shift;; --no-cluster-manifests) DO_CLUSTER_MANIFESTS=false; shift;;
+    -h|--help) usage; exit 0;;
+    *) echo "Unknown flag: $1" >&2; usage; exit 1;;
+  esac
+done
+
+# ─────────────────────────── derived flags ───────────────────────────
+CLUSTER_FLAG=""
+case "$CLUSTER" in
+  kind)    CLUSTER_FLAG="--kind";;
+  kubeadm) CLUSTER_FLAG="--kubeadm";;
+  k3s)     CLUSTER_FLAG="--k3s";;
+  ""|none) CLUSTER_FLAG="";;
+  *) echo "Unknown --cluster: $CLUSTER (expected kind|kubeadm|k3s|none)" >&2; exit 1;;
+esac
+DEV_FLAG=""; [ "$ENV" = development ] && DEV_FLAG="--dev"
+INSTANCES_CONF="./engine-private/conf/${DEPLOY_ID}/conf.instances.json"
+SERVER_CONF="./engine-private/conf/${DEPLOY_ID}/conf.server.json"
+
+echo "[test-monitor] mode=$MODE env=$ENV deploy=$DEPLOY_ID cluster=${CLUSTER:-none} tls=$USE_TLS test-repo=$USE_TEST_REPO expose=$DO_EXPOSE"
+
+# ─────────────────────────── shared helpers ───────────────────────────
+
+# setup_tls_secrets <host> [<host> …] — regenerate self-signed certs and create
+# the per-host k8s TLS secret the HTTPProxy references (name == host).
+setup_tls_secrets() {
+  local ssl_base="${ENGINE_DIR}/engine-private/ssl"
+  for host in "$@"; do
+    local cert_dir="${ssl_base}/${host}"
+    mkdir -p "$cert_dir"
+    bash "${SCRIPT_DIR}/ssl.sh" "$cert_dir" "$host"
+    local name_safe="${host//[^a-zA-Z0-9_.-]/_}"
+    kubectl delete secret "$host" -n "$NAMESPACE" --ignore-not-found
+    kubectl create secret tls "$host" \
+      --cert="${cert_dir}/${name_safe}.pem" \
+      --key="${cert_dir}/${name_safe}-key.pem" \
+      -n "$NAMESPACE"
+  done
+}
+
+# hosts_from <conf.json> — unique hosts declared in a conf.server.json or conf.instances.json.
+hosts_from() {
+  node -e "
+    const c = require('$1');
+    const hosts = Array.isArray(c) ? c.map(i => i.host) : Object.keys(c);
+    console.log([...new Set(hosts)].join(' '));
+  "
+}
+
+# ─────────────────────────── pre-steps ───────────────────────────
+[ "$DO_CLUSTER_MANIFESTS" = true ] && node bin run build-cluster-deployment-manifests
+[ "$DO_BUILD_TEMPLATE" = true ] && node bin/build.template --update-private
+
+# ─────────────────────────── runtime mode ───────────────────────────
+run_runtime_mode() {
+  local link_cmd="cd /home/dd,underpost clone ${TEMPLATE_REPO},cd /home/dd/${TEMPLATE_REPO##*/},npm install,npm link"
+  local deploy_cmd proxy_flag="" expose_flags="" start_flags=""
+
+  # Publish the local engine src to underpostnet/engine-test-<id> so the pod
+  # (started with --private-test-repo) clones this work-in-progress source.
+  [ "$USE_TEST_REPO" = true ] && node bin/build "$DEPLOY_ID" --update-private
+
+  [ "$USE_PULL_BUNDLE" = true ] && start_flags="${start_flags} --pull-bundle"
+  [ "$USE_TEST_REPO" = true ] && start_flags="${start_flags} --private-test-repo"
+  deploy_cmd="${link_cmd},underpost start --build --run${start_flags} ${DEPLOY_ID} ${ENV}"
+
+  [ "$USE_CERT" = true ] && proxy_flag="--cert"
+  [ "$USE_TLS" = true ] && proxy_flag="--self-signed"
+
+  node bin deploy "$DEPLOY_ID" "$ENV" $CLUSTER_FLAG --sync --build-manifest \
+    --image "$IMAGE" --timeout-response "$TIMEOUT_RESPONSE" --versions "$VERSIONS" --replicas "$REPLICAS" --cmd "$deploy_cmd"
+  node bin deploy "$DEPLOY_ID" "$ENV" $CLUSTER_FLAG --disable-update-proxy $proxy_flag
+  node bin monitor "$DEPLOY_ID" "$ENV" --ready-deployment --promote \
+    --timeout-response "$TIMEOUT_RESPONSE" --versions "$VERSIONS" --replicas "$REPLICAS"
+
+  node bin run etc-hosts --deploy-id "$DEPLOY_ID"
+
+  if [ "$USE_TLS" = true ]; then
+    setup_tls_secrets $(hosts_from "$SERVER_CONF")
+    expose_flags="--tls"
+  fi
+  [ "$DO_EXPOSE" = true ] && node bin deploy --expose --local-proxy "$DEPLOY_ID" "$ENV" $expose_flags
+}
+
+# ─────────────────────────── instance mode ───────────────────────────
+run_instance_mode() {
+  [ -f "$INSTANCES_CONF" ] || { echo "Missing $INSTANCES_CONF" >&2; exit 1; }
+  if [ -z "$INSTANCE_IDS" ]; then
+    INSTANCE_IDS=$(node -e "console.log(require('$INSTANCES_CONF').map(i=>i.id).join(','))")
+  fi
+  local tls_flag=""; [ "$USE_TLS" = true ] && tls_flag="--tls --test"
+
+  # `run instance` builds/pulls the image, applies the manifest, monitors with the
+  # kubernetes gate (TCP readinessProbe) + exec status, then promotes traffic.
+  IFS=',' read -ra ids <<< "$INSTANCE_IDS"
+  for id in "${ids[@]}"; do
+    [ -n "$id" ] || continue
+    echo "[test-monitor] deploying instance ${DEPLOY_ID},${id}"
+    node bin run instance "${DEPLOY_ID},${id},${REPLICAS}" \
+      $DEV_FLAG $CLUSTER_FLAG --namespace "$NAMESPACE" --etc-hosts $tls_flag \
+      ${IMAGE:+--image-name "$IMAGE"}
+  done
+
+  [ "$DO_EXPOSE" = true ] || return 0
+  if [ "$USE_TLS" = true ]; then
+    # Instances are routed by the Contour ingress; port-forward Envoy so the
+    # HTTPProxy host routing (server/client.cyberiaonline.com) works locally.
+    echo "[test-monitor] exposing HTTPS via ${ENVOY_NAMESPACE}/${ENVOY_SERVICE} on :${HTTPS_PORT}"
+    sudo kubectl port-forward -n "$ENVOY_NAMESPACE" "svc/${ENVOY_SERVICE}" "${HTTPS_PORT}:443" &
+  else
+    # Plain HTTP: port-forward each instance service port directly.
+    for id in "${ids[@]}"; do
+      [ -n "$id" ] || continue
+      node bin deploy --expose "${DEPLOY_ID}-${id}" "$ENV" --namespace "$NAMESPACE" || true
+    done
+  fi
+}
+
+case "$MODE" in
+  runtime)  run_runtime_mode;;
+  instance) run_instance_mode;;
+  *) echo "Unknown --mode: $MODE (expected runtime|instance)" >&2; exit 1;;
+esac
+
+echo "[test-monitor] done (mode=$MODE tls=$USE_TLS)"

package/src/cli/deploy.js

@@ -18,6 +18,7 @@ import {
 } from '../server/conf.js';
 import { loggerFactory } from '../server/logger.js';
 import { shellExec } from '../server/process.js';
+import { INTERNAL_READY_PATH, INTERNAL_HEALTH_PATH } from '../server/runtime-status.js';
 import fs from 'fs-extra';
 import dotenv from 'dotenv';
 import os from 'node:os';
@@ -113,6 +114,64 @@ class UnderpostDeploy {
       )
       .join('')}`;
     },
+    /**
+     * Builds Kubernetes probes that gate on the in-pod internal status endpoint.
+     *
+     * HTTP mode (default) aligns Kubernetes pod readiness with actual Underpost
+     * runtime readiness:
+     *   - readinessProbe → GET /_internal/ready  (200 only when running-deployment)
+     *   - livenessProbe  → GET /_internal/health (deadlock / hung-process detection)
+     *   - startupProbe   → GET /_internal/ready  (long window for hot-built/slow boots)
+     *
+     * Migration: pass `useHttp: false` to emit the legacy TCP socket probes
+     * (port-bound only) for deployments not yet serving the internal endpoint.
+     *
+     * @param {object} opts
+     * @param {number} opts.port - In-pod internal status port (deployment base PORT).
+     * @param {boolean} [opts.useHttp=true] - Emit HTTP probes; false → legacy TCP.
+     * @param {boolean} [opts.liveness=true] - Include a livenessProbe.
+     * @param {boolean} [opts.startup=true] - Include a startupProbe.
+     * @returns {{readinessProbe: object, livenessProbe?: object, startupProbe?: object}}
+     * @memberof UnderpostDeploy
+     */
+    runtimeProbesFactory({ port, useHttp = true, liveness = true, startup = true } = {}) {
+      if (!port) return {};
+      if (!useHttp) {
+        const tcp = { tcpSocket: { port }, initialDelaySeconds: 5, periodSeconds: 10, failureThreshold: 6 };
+        const probes = { readinessProbe: tcp };
+        if (liveness) probes.livenessProbe = { ...tcp, initialDelaySeconds: 30 };
+        return probes;
+      }
+      const probes = {
+        readinessProbe: {
+          httpGet: { path: INTERNAL_READY_PATH, port },
+          initialDelaySeconds: 5,
+          periodSeconds: 5,
+          timeoutSeconds: 3,
+          failureThreshold: 3,
+        },
+      };
+      if (liveness)
+        probes.livenessProbe = {
+          httpGet: { path: INTERNAL_HEALTH_PATH, port },
+          initialDelaySeconds: 30,
+          periodSeconds: 15,
+          timeoutSeconds: 3,
+          failureThreshold: 3,
+        };
+      if (startup)
+        // A startupProbe suspends readiness/liveness until it first succeeds, so
+        // its window bounds in-container hot builds and slow boots. 180 × 10s =
+        // 30 min before the pod is considered failed to start.
+        probes.startupProbe = {
+          httpGet: { path: INTERNAL_READY_PATH, port },
+          initialDelaySeconds: 10,
+          periodSeconds: 10,
+          timeoutSeconds: 3,
+          failureThreshold: 180,
+        };
+      return probes;
+    },
     /**
      * Creates a YAML deployment configuration for a deployment.
      * @param {string} deployId - Deployment ID for which the deployment is being created.
@@ -127,6 +186,11 @@ class UnderpostDeploy {
      * @param {boolean} skipFullBuild - Whether to skip the full client bundle build during deployment.
      * @param {boolean} pullBundle - Whether to pull the pre-built client bundle from Cloudinary before starting. Use together with skipFullBuild to skip the local build entirely.
      * @param {string} [imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`). When omitted, defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
+     * @param {object} lifecycle - Kubernetes lifecycle hooks configuration for the deployment container.
+     * @param {object} readinessProbe - Kubernetes readiness probe configuration for the deployment container.
+     * @param {object} livenessProbe - Kubernetes liveness probe configuration for the deployment container.
+     * @param {object} startupProbe - Kubernetes startup probe configuration for the deployment container.
+     * @param {number} containerPort - Container port to expose for the deployment.
      * @returns {string} - YAML deployment configuration for the specified deployment.
      * @memberof UnderpostDeploy
      */
@@ -152,7 +216,12 @@ class UnderpostDeploy {
       lifecycle,
       readinessProbe,
       livenessProbe,
+      startupProbe,
       containerPort,
+      // Explicit, secret-free internal status port injected as an env var so the
+      // in-pod endpoint binds exactly what the probes and the monitor target,
+      // independent of the ambient `PORT` baked into the image/secret.
+      internalStatusPort,
     }) {
       if (!cmd)
         cmd =
@@ -204,12 +273,19 @@ spec:
             - secretRef:
                 name: underpost-config
 ${
-  containerPort
-    ? `          ports:
-            - containerPort: ${containerPort}
+  internalStatusPort
+    ? `          env:
+            - name: UNDERPOST_INTERNAL_PORT
+              value: "${internalStatusPort}"
 `
     : ''
 }${
+        containerPort
+          ? `          ports:
+            - containerPort: ${containerPort}
+`
+          : ''
+      }${
         resources
           ? `          resources:
             requests:
@@ -241,6 +317,15 @@ ${JSON.stringify(livenessProbe, null, 2)
   .split('\n')
   .map((l) => '            ' + l)
   .join('\n')}
+`
+          : ''
+      }${
+        startupProbe
+          ? `          startupProbe:
+${JSON.stringify(startupProbe, null, 2)
+  .split('\n')
+  .map((l) => '            ' + l)
+  .join('\n')}
 `
           : ''
       }${
@@ -282,18 +367,22 @@ spec:
      * @param {object} options - Options for the manifest build process.
      * @param {string} options.replicas - Number of replicas for each deployment.
      * @param {string} options.image - Docker image for the deployment.
-     * @param {string} options.namespace - Kubernetes namespace for the deployment.
+     * @param {string} options.namespace - Kubernetes namespace for the deployment (defaults to "default").
      * @param {string} [options.versions] - Comma-separated list of versions to deploy.
      * @param {string} [options.cmd] - Custom initialization command for deploymentYamlPartsFactory (comma-separated commands).
-     * @param {string} [options.timeoutResponse] - Timeout response setting for the deployment.
-     * @param {string} [options.timeoutIdle] - Timeout idle setting for the deployment.
-     * @param {string} [options.retryCount] - Retry count setting for the deployment.
-     * @param {string} [options.retryPerTryTimeout] - Retry per-try timeout setting for the deployment.
-     * @param {boolean} [options.disableDeploymentProxy] - Whether to disable deployment proxy.
-     * @param {string} [options.traffic] - Traffic status for the deployment.
-     * @param {boolean} [options.skipFullBuild] - Whether to skip the full client bundle build; forwarded to deploymentYamlPartsFactory to generate a pull-bundle startup command.
+     * @param {string} [options.timeoutResponse] - HTTPProxy per-route response timeout (e.g. "300000ms", "infinity").
+     * @param {string} [options.timeoutIdle] - HTTPProxy per-route idle timeout (e.g. "10s", "infinity").
+     * @param {string} [options.retryCount] - HTTPProxy per-route retry count (e.g. 3).
+     * @param {string} [options.retryPerTryTimeout] - HTTPProxy per-route per-try timeout (e.g. "150ms").
+     * @param {boolean} [options.disableDeploymentProxy] - Whether to disable deployment proxy route generation.
+     * @param {string} [options.traffic] - Comma-separated active traffic colour(s) used to select which versions receive traffic (e.g. "blue", "green").
+     * @param {boolean} [options.cert] - Whether to include cert-manager Certificate resources in secret.yaml (production only).
+     * @param {boolean} [options.selfSigned] - Whether to include TLS block in HTTPProxy using a pre-created self-signed secret. Enables HTTPS for development without cert-manager.
+     * @param {boolean} [options.skipFullBuild] - Whether to skip the full client bundle build; forwarded to deploymentYamlPartsFactory.
      * @param {boolean} [options.pullBundle] - Whether to pull the pre-built client bundle from Cloudinary; forwarded to deploymentYamlPartsFactory. Use together with skipFullBuild.
-     * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); forwarded to deploymentYamlPartsFactory. When omitted, the builder defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
+     * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); forwarded to deploymentYamlPartsFactory. Defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
+     * @param {boolean} [options.disableRuntimeProbes] - Omit internal-status HTTP probes from generated manifests. When true no readiness/liveness/startup probes are emitted.
+     * @param {boolean} [options.tcpProbes] - Emit legacy TCP socket probes instead of HTTP internal-status probes (migration path).
      * @returns {Promise<void>} - Promise that resolves when the manifest is built.
      * @memberof UnderpostDeploy
      */
@@ -318,6 +407,17 @@ spec:
 
         logger.info('port range', { deployId, fromPort, toPort });
 
+        // The internal status endpoint binds `fromPort - 1`: app instances bind
+        // the router range starting at `fromPort`, so this slot is always free
+        // inside the pod. It is injected into the pod env (UNDERPOST_INTERNAL_PORT)
+        // and used for both the probes and the monitor's port-forward target so
+        // all three agree regardless of the image's ambient PORT.
+        // Opt out with `--disable-runtime-probes` to keep legacy probe-less pods.
+        const internalPort = fromPort - 1;
+        const probes = options.disableRuntimeProbes
+          ? {}
+          : Underpost.deploy.runtimeProbesFactory({ port: internalPort, useHttp: !options.tcpProbes });
+
         let deploymentYamlParts = '';
         for (const deploymentVersion of deploymentVersions) {
           deploymentYamlParts += `---
@@ -333,6 +433,10 @@ ${Underpost.deploy
     skipFullBuild: options.skipFullBuild,
     pullBundle: options.pullBundle,
     imagePullPolicy: options.imagePullPolicy,
+    internalStatusPort: options.disableRuntimeProbes ? undefined : internalPort,
+    readinessProbe: probes.readinessProbe,
+    livenessProbe: probes.livenessProbe,
+    startupProbe: probes.startupProbe,
   })
   .replace('{{ports}}', buildKindPorts(fromPort, toPort))}
 `;
@@ -375,7 +479,7 @@ ${Underpost.deploy
           : [];
 
         for (const host of Object.keys(confServer)) {
-          if (env === 'production')
+          if (env === 'production' && options.cert === true)
             secretYaml += Underpost.deploy.buildCertManagerCertificate({ host, namespace: options.namespace });
 
           const pathPortAssignment = pathPortAssignmentData[host];
@@ -578,6 +682,7 @@ spec:
      * @memberof UnderpostDeploy
      */
     baseProxyYamlFactory({ host, env, options }) {
+      const includeTls = env !== 'development' || options.selfSigned === true;
       return `
 ---
 apiVersion: projectcontour.io/v1
@@ -588,11 +693,11 @@ metadata:
 spec:
   virtualhost:
     fqdn: ${host}${
-      env === 'development'
-        ? ''
-        : `
+      includeTls
+        ? `
     tls:
       secretName: ${host}`
+        : ''
     }
   routes:`;
     },
@@ -608,8 +713,9 @@ spec:
      * @param {boolean} options.buildManifest - Whether to build the deployment manifest.
      * @param {boolean} options.infoUtil - Whether to display utility information.
      * @param {boolean} options.expose - Whether to expose the deployment.
-     * @param {boolean} options.cert - Whether to create certificates for the deployment.
-     * @param {string} options.certHosts - Comma-separated list of hosts for which to create certificates.
+     * @param {boolean} options.cert - Whether to create cert-manager Certificate resources for the deployment.
+     * @param {string} options.certHosts - Comma-separated list of hosts for which to create cert-manager certificates.
+     * @param {boolean} options.selfSigned - Use a pre-created self-signed TLS secret instead of cert-manager. The secret must already exist in the namespace with the same name as the host. Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer.
      * @param {string} options.versions - Comma-separated list of versions to deploy.
      * @param {string} options.image - Docker image for the deployment.
      * @param {string} options.traffic - Traffic status for the deployment.
@@ -621,22 +727,27 @@ spec:
      * @param {boolean} options.disableUpdateVolume - Whether to disable volume updates.
      * @param {boolean} options.status - Whether to display deployment status.
      * @param {boolean} options.disableUpdateUnderpostConfig - Whether to disable Underpost config updates.
-     * @param {string} [options.namespace] - Kubernetes namespace for the deployment.
-     * @param {string} [options.timeoutResponse] - Timeout response setting for the deployment.
-     * @param {string} [options.timeoutIdle] - Timeout idle setting for the deployment.
-     * @param {string} [options.retryCount] - Retry count setting for the deployment.
-     * @param {string} [options.retryPerTryTimeout] - Retry per-try timeout setting for the deployment.
-     * @param {string} [options.kindType] - Type of Kubernetes resource to retrieve information for.
-     * @param {number} [options.port] - Port number for exposing the deployment.
-     * @param {string} [options.cmd] - Custom initialization command for deploymentYamlPartsFactory (comma-separated commands).
-     * @param {number} [options.exposePort] - Local:remote port override when --expose is active (overrides auto-detected service port).
+     * @param {string} [options.namespace] - Kubernetes namespace for the deployment (defaults to "default").
+     * @param {string} [options.timeoutResponse] - HTTPProxy per-route response timeout (e.g. "300000ms", "infinity").
+     * @param {string} [options.timeoutIdle] - HTTPProxy per-route idle timeout (e.g. "10s", "infinity").
+     * @param {string} [options.retryCount] - HTTPProxy per-route retry count (e.g. 3).
+     * @param {string} [options.retryPerTryTimeout] - HTTPProxy per-route per-try timeout (e.g. "150ms").
+     * @param {string} [options.kindType] - Kubernetes resource kind to target when using --expose (defaults to "svc").
+     * @param {number} [options.port] - Port number override for exposing the deployment.
+     * @param {string} [options.cmd] - Custom initialization command (comma-separated) for deploymentYamlPartsFactory.
+     * @param {number} [options.exposePort] - Remote port override when --expose is active (overrides auto-detected service port). Used as both local and remote port unless exposeLocalPort is also set.
+     * @param {number} [options.exposeLocalPort] - Local port override for --expose (e.g. 80); remote port is still auto-detected. Enables /etc/hosts access without a port in the browser URL.
+     * @param {boolean} [options.localProxy] - When true (with --expose), forward all service TCP ports locally and start the Node.js path-routing proxy for full path-based routing (e.g. /wp alongside /).
+     * @param {boolean} [options.tls] - When true (with --expose --local-proxy), start the proxy on port 443 with TLS using self-signed certificates resolved from the local SSL store.
      * @param {boolean} [options.k3s] - Whether to use k3s cluster context.
      * @param {boolean} [options.kubeadm] - Whether to use kubeadm cluster context.
      * @param {boolean} [options.kind] - Whether to use kind cluster context.
      * @param {boolean} [options.gitClean] - Whether to run git clean on volume mount paths before copying.
      * @param {boolean} [options.skipFullBuild] - Whether to skip the full client bundle build; passed through to buildManifest/deploymentYamlPartsFactory.
      * @param {boolean} [options.pullBundle] - Whether to pull the pre-built client bundle from Cloudinary; passed through to buildManifest/deploymentYamlPartsFactory. Use together with skipFullBuild.
-     * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); passed through to buildManifest/deploymentYamlPartsFactory. When omitted, the builder defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
+     * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); passed through to buildManifest/deploymentYamlPartsFactory. Defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
+     * @param {boolean} [options.disableRuntimeProbes] - Omit internal-status HTTP probes from generated manifests. When true no readiness/liveness/startup probes are emitted.
+     * @param {boolean} [options.tcpProbes] - Emit legacy TCP socket probes instead of HTTP internal-status probes.
      * @returns {Promise<void>} - Promise that resolves when the deployment process is complete.
      * @memberof UnderpostDeploy
      */
@@ -671,6 +782,10 @@ spec:
         kindType: '',
         port: 0,
         exposePort: 0,
+        exposeLocalPort: 0,
+        localProxy: false,
+        tls: false,
+        selfSigned: false,
         cmd: '',
         k3s: false,
         kubeadm: false,
@@ -756,20 +871,50 @@ EOF`);
             logger.error(`No ${kindType} found matching '${deployId}', skipping expose`);
             continue;
           }
-          const port = options.exposePort
-            ? parseInt(options.exposePort)
-            : options.port
-              ? parseInt(options.port)
-              : kindType !== 'svc'
-                ? 80
-                : parseInt(svc[`PORT(S)`].split('/TCP')[0]);
-          logger.info(deployId, {
-            svc,
-            port,
-          });
-          shellExec(`sudo kubectl port-forward -n ${namespace} ${kindType}/${svc.NAME} ${port}:${port}`, {
-            async: true,
-          });
+          if (options.localProxy) {
+            const svcPorts = [
+              ...new Set(
+                svc['PORT(S)']
+                  .split(',')
+                  .filter((p) => p.includes('/TCP'))
+                  .map((p) => parseInt(p.split(':')[0])),
+              ),
+            ];
+            for (const svcPort of svcPorts) {
+              shellExec(`sudo kubectl port-forward -n ${namespace} ${kindType}/${svc.NAME} ${svcPort}:${svcPort}`, {
+                async: true,
+              });
+            }
+            const envFile = `./engine-private/conf/${deployId}/.env.${env}`;
+            let basePort = svcPorts[0] - 1;
+            if (fs.existsSync(envFile)) {
+              const portMatch = fs.readFileSync(envFile, 'utf8').match(/^PORT=(\d+)/m);
+              if (portMatch) basePort = parseInt(portMatch[1]);
+            }
+            logger.info(deployId, { svc, svcPorts, basePort });
+            const tlsFlag = options.tls ? ' tls' : '';
+            shellExec(
+              `NODE_ENV=${env} PORT=${basePort} DEV_PROXY_PORT_OFFSET=0 node src/proxy proxy ${deployId} ${env}${tlsFlag}`,
+              { async: true },
+            );
+          } else {
+            const remotePort = options.exposePort
+              ? parseInt(options.exposePort)
+              : options.port
+                ? parseInt(options.port)
+                : kindType !== 'svc'
+                  ? 80
+                  : parseInt(svc[`PORT(S)`].split('/TCP')[0]);
+            const localPort = options.exposeLocalPort ? parseInt(options.exposeLocalPort) : remotePort;
+            logger.info(deployId, {
+              svc,
+              localPort,
+              remotePort,
+            });
+            shellExec(`sudo kubectl port-forward -n ${namespace} ${kindType}/${svc.NAME} ${localPort}:${remotePort}`, {
+              async: true,
+            });
+          }
           continue;
         }
 
@@ -821,7 +966,10 @@ EOF`);
           if (!options.disableUpdateProxy)
             shellExec(`sudo kubectl apply -f ./${manifestsPath}/proxy.yaml -n ${namespace}`);
 
-          if (Underpost.deploy.isValidTLSContext({ host: Object.keys(confServer)[0], env, options }))
+          if (
+            Underpost.deploy.isValidTLSContext({ host: Object.keys(confServer)[0], env, options }) &&
+            !options.selfSigned
+          )
             shellExec(`sudo kubectl apply -f ./${manifestsPath}/secret.yaml -n ${namespace}`);
         }
       }
@@ -924,15 +1072,12 @@ EOF`);
       if (options.gitClean && volume.volumeMountPath) {
         Underpost.repo.clean({ paths: [volume.volumeMountPath] });
       }
-      if (options.nodeName) {
-        if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
-        fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
-      } else if (clusterContext === 'kind') {
-        shellExec(`docker exec -i kind-worker bash -c "mkdir -p ${rootVolumeHostPath}"`);
-        // shellExec(`docker cp ${volume.volumeMountPath} kind-worker:${rootVolumeHostPath}`);
-        shellExec(`tar -C ${volume.volumeMountPath} -c . | docker cp - kind-worker:${rootVolumeHostPath}`);
+      if (clusterContext === 'kind') {
+        const kindNode = options.nodeName || 'kind-worker';
+        shellExec(`docker exec -i ${kindNode} bash -c "mkdir -p ${rootVolumeHostPath}"`);
+        shellExec(`tar -C ${volume.volumeMountPath} -c . | docker cp - ${kindNode}:${rootVolumeHostPath}`);
         shellExec(
-          `docker exec -i kind-worker bash -c "chown -R 1000:1000 ${rootVolumeHostPath}; chmod -R 755 ${rootVolumeHostPath}"`,
+          `docker exec -i ${kindNode} bash -c "chown -R 1000:1000 ${rootVolumeHostPath}; chmod -R 755 ${rootVolumeHostPath}"`,
         );
       } else {
         if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
@@ -1082,9 +1227,10 @@ spec:
      * @memberof UnderpostDeploy
      */
     isValidTLSContext: ({ host, env, options }) =>
-      env === 'production' &&
-      options.cert === true &&
-      (!options.certHosts || options.certHosts.split(',').includes(host)),
+      (env === 'production' &&
+        options.cert === true &&
+        (!options.certHosts || options.certHosts.split(',').includes(host))) ||
+      options.selfSigned === true,
 
     /**
      * Predefined resource templates for Kubernetes deployments.