underpost 3.2.30 → 3.2.70

package/package.json

@@ -2,7 +2,7 @@
     "type": "module",
     "main": "src/index.js",
     "name": "underpost",
-    "version": "3.2.30",
+    "version": "3.2.70",
     "description": "Underpost Platform — end-to-end CI/CD and application-delivery toolchain CLI. Covers bare metal, Kubernetes, K3s, kubeadm, LXD, container/image orchestration, secrets, databases, cron jobs, monitoring, SSH, runners, PWA + Workbox delivery, and release orchestration. Extensible via downstream CLIs.",
     "scripts": {
         "start": "node --max-old-space-size=8192 src/server",
@@ -71,14 +71,14 @@
     },
     "homepage": "https://github.com/underpostnet/pwa-microservices-template#readme",
     "dependencies": {
-        "@fortawesome/fontawesome-free": "^7.2.0",
+        "@fortawesome/fontawesome-free": "^7.3.0",
         "@fullcalendar/rrule": "^6.1.21",
         "@grpc/grpc-js": "^1.14.4",
         "@grpc/proto-loader": "^0.8.1",
         "@neodrag/vanilla": "^2.3.1",
-        "adm-zip": "^0.5.17",
-        "ag-grid-community": "^35.3.1",
-        "axios": "^1.18.0",
+        "adm-zip": "^0.5.18",
+        "ag-grid-community": "^36.0.0",
+        "axios": "^1.18.1",
         "bumpp": "^11.1.0",
         "chai": "^6.2.2",
         "clipboardy": "^5.3.1",
@@ -100,11 +100,11 @@
         "express-slow-down": "^3.1.0",
         "fast-json-stable-stringify": "^2.1.0",
         "favicons": "^7.3.0",
-        "fs-extra": "^11.3.5",
+        "fs-extra": "^11.3.6",
         "fullcalendar": "^6.1.21",
         "helmet": "^8.2.0",
         "html-minifier-terser": "^7.2.0",
-        "http-proxy-middleware": "^4.1.1",
+        "http-proxy-middleware": "^4.2.0",
         "ignore-walk": "^9.0.0",
         "iovalkey": "^0.3.3",
         "json-colorizer": "^3.0.1",
@@ -112,9 +112,9 @@
         "mariadb": "^3.5.3",
         "marked": "^18.0.5",
         "mocha": "^11.7.6",
-        "mongoose": "^9.7.1",
+        "mongoose": "^9.7.3",
         "morgan": "^1.11.0",
-        "nodemailer": "^9.0.0",
+        "nodemailer": "^9.0.3",
         "nodemon": "^3.0.1",
         "peer": "^1.0.2",
         "peerjs": "^1.5.5",
@@ -128,7 +128,7 @@
         "split-file": "^2.3.0",
         "swagger-autogen": "^2.23.7",
         "swagger-ui-express": "^5.0.0",
-        "typedoc": "^0.28.19",
+        "typedoc": "^0.28.20",
         "typescript": "^6.0.3",
         "validator": "^13.15.35",
         "vanilla-jsoneditor": "^3.12.0",

package/scripts/disk-clean.sh

@@ -7,20 +7,20 @@ set -euo pipefail
 
 VACUUM_SIZE="200M"          # journalctl vacuum target
 LARGE_LOG_SIZE="+100M"      # threshold for truncation (find syntax)
-TMP_AGE_DAYS=3              # remove files older than this from /tmp and /var/tmp
-CACHE_AGE_DAYS=30           # remove caches older than this from /var/cache
+TMP_AGE_DAYS=1              # remove files older than this from /tmp and /var/tmp
+CACHE_AGE_DAYS=5           # remove caches older than this from /var/cache
 KEEP_KERNELS=2              # keep this many latest kernels
 REMOVE_OPT=0                # ALWAYS allow removing /opt entries (user requested)
 
 timestamp() { date +"%F %T"; }
 log() {
-  echo "$(timestamp) $*"
+    echo "$(timestamp) $*"
 }
 
 # must be root
 if [ "$EUID" -ne 0 ]; then
-  echo "This script must be run as root. Exiting."
-  exit 1
+    echo "This script must be run as root. Exiting."
+    exit 1
 fi
 
 log "=== Starting Rocky Linux 9 automated cleanup (batch mode) ==="
@@ -46,8 +46,8 @@ journalctl --vacuum-size="$VACUUM_SIZE"
 # 3) Truncate very large logs in /var/log (safer than delete)
 log "Truncating logs in /var/log larger than ${LARGE_LOG_SIZE} (keeps zero-sized file so services don't break)..."
 find /var/log -type f -size "$LARGE_LOG_SIZE" -print0 2>/dev/null | while IFS= read -r -d '' f; do
-  echo "Truncating $f"
-  : > "$f" || echo "Failed to truncate $f"
+    echo "Truncating $f"
+    : > "$f" || echo "Failed to truncate $f"
 done
 
 # 4) Clean /tmp and /var/tmp older than TMP_AGE_DAYS
@@ -62,87 +62,110 @@ find /var/cache -mindepth 1 -mtime +"$CACHE_AGE_DAYS" -print0 2>/dev/null | xarg
 # 6) Clean user caches (~/.cache) and Downloads older than CACHE_AGE_DAYS
 log "Cleaning user caches and old downloads (home dirs)..."
 for homedir in /home/* /root; do
-  [ -d "$homedir" ] || continue
-  usercache="$homedir/.cache"
-  userdownloads="$homedir/Downloads"
-  usertrash="$homedir/.local/share/Trash"
-
-  if [ -d "$usercache" ]; then
-    log "Removing contents of $usercache"
-    rm -rf "${usercache:?}/"* 2>/dev/null
-  fi
-  if [ -d "$userdownloads" ]; then
-    log "Removing files older than ${CACHE_AGE_DAYS} days from $userdownloads"
-    find "$userdownloads" -type f -mtime +"$CACHE_AGE_DAYS" -print0 2>/dev/null | xargs -0r rm -f -- 2>/dev/null
-  fi
-  if [ -d "$usertrash" ]; then
-    log "Emptying trash in $usertrash"
-    rm -rf "${usertrash:?}/"* 2>/dev/null
-  fi
+    [ -d "$homedir" ] || continue
+    usercache="$homedir/.cache"
+    userdownloads="$homedir/Downloads"
+    usertrash="$homedir/.local/share/Trash"
+    
+    if [ -d "$usercache" ]; then
+        log "Removing contents of $usercache"
+        rm -rf "${usercache:?}/"* 2>/dev/null
+    fi
+    if [ -d "$userdownloads" ]; then
+        log "Removing files older than ${CACHE_AGE_DAYS} days from $userdownloads"
+        find "$userdownloads" -type f -mtime +"$CACHE_AGE_DAYS" -print0 2>/dev/null | xargs -0r rm -f -- 2>/dev/null
+    fi
+    if [ -d "$usertrash" ]; then
+        log "Emptying trash in $usertrash"
+        rm -rf "${usertrash:?}/"* 2>/dev/null
+    fi
 done
 
-# 7) Docker / Podman cleanup (if present)
+# 7) Docker / Podman cleanup (if present) — this is what actually reclaims the
+#    overlay storage behind those duplicated `overlay` df lines.
 if command -v docker >/dev/null 2>&1; then
-  log "Docker detected: pruning images/containers/volumes (aggressive)..."
-  docker system df
-  docker system prune -a --volumes -f
+    log "Docker detected: pruning images/containers/volumes/build cache (aggressive)..."
+    docker system df || true
+    docker system prune -a --volumes -f || true
+    docker builder prune -a -f || true
 fi
 
 if command -v podman >/dev/null 2>&1; then
-  log "Podman detected: pruning images/containers (aggressive)..."
-  podman system df
-  podman system prune -a -f
+    log "Podman detected: pruning images/containers/volumes (aggressive)..."
+    podman system df || true
+    podman system prune -a --volumes -f || true
 fi
 
+if command -v buildah >/dev/null 2>&1; then
+    log "Buildah detected: removing leftover working containers..."
+    buildah rm --all || true
+fi
+
+# 7b) Unmount leaked container overlay 'merged' mounts. Pruning frees the data
+#     but leaves these mountpoints attached, so they keep flooding `df -h` with
+#     identical `overlay ... /merged` rows. Only unmount overlays not backing a
+#     still-existing container, so running workloads are never disturbed.
+log "Unmounting orphaned container overlay mounts..."
+if command -v podman >/dev/null 2>&1; then
+    podman umount --all >/dev/null 2>&1 || true
+fi
+active_merged="$(podman ps -aq 2>/dev/null | xargs -r -I{} podman inspect --format '{{.GraphDriver.Data.MergedDir}}' {} 2>/dev/null || true)"
+findmnt -rn -o TARGET 2>/dev/null | grep -E '/var/lib/(containers/storage|docker)/overlay.*/merged' | sort -r | while IFS= read -r m; do
+    if ! printf '%s\n' "$active_merged" | grep -qxF "$m"; then
+        echo "Unmounting orphaned overlay: $m"
+        umount -l "$m" 2>/dev/null || true
+    fi
+done
+
 # 8) Flatpak unused runtimes/apps (if present)
 if command -v flatpak >/dev/null 2>&1; then
-  log "Flatpak detected: trying to uninstall unused runtimes/apps..."
-  flatpak uninstall --unused -y || flatpak uninstall --unused
-  flatpak repair
+    log "Flatpak detected: trying to uninstall unused runtimes/apps..."
+    flatpak uninstall --unused -y || flatpak uninstall --unused
+    flatpak repair
 fi
 
 # 9) Python Pip cleanup
 if command -v pip3 >/dev/null 2>&1 || command -v pip >/dev/null 2>&1; then
-  log "Python Pip detected: cleaning cache..."
-  if command -v pip3 >/dev/null 2>&1; then
-    pip3 cache purge
-  elif command -v pip >/dev/null 2>&1; then
-    pip cache purge
-  fi
+    log "Python Pip detected: cleaning cache..."
+    if command -v pip3 >/dev/null 2>&1; then
+        pip3 cache purge
+        elif command -v pip >/dev/null 2>&1; then
+        pip cache purge
+    fi
 fi
 
 # 10) Conda cleanup
 if command -v conda >/dev/null 2>&1; then
-  log "Conda detected: cleaning all..."
-  conda clean --all -y
+    log "Conda detected: cleaning all..."
+    conda clean --all -y
 fi
 
 # 11) Remove old kernels but keep the last KEEP_KERNELS (safe)
 log "Removing old kernels, keeping the last $KEEP_KERNELS kernels..."
 OLD_KERNELS=$(dnf repoquery --installonly --latest-limit=-$KEEP_KERNELS -q 2>/dev/null)
 if [ -n "$OLD_KERNELS" ]; then
-  log "Old kernels to remove: $OLD_KERNELS"
-  dnf -y remove $OLD_KERNELS
+    log "Old kernels to remove: $OLD_KERNELS"
+    dnf -y remove $OLD_KERNELS
 else
-  log "No old kernels found by DNF repoquery. Only $KEEP_KERNELS or fewer are currently installed."
+    log "No old kernels found by DNF repoquery. Only $KEEP_KERNELS or fewer are currently installed."
 fi
 
 # 12) /opt review and removal (ON by default now)
 if [ -d /opt ]; then
-  log "/opt usage (top entries):"
-  du -sh /opt/* 2>/dev/null | sort -h | head -n 20
-
-  if [ "$REMOVE_OPT" = "1" ]; then
-    OPT_TARGETS=(/opt/local-path-provisioner)
-    for t in "${OPT_TARGETS[@]}"; do
-      if [ -d "$t" ]; then
-        log "Removing $t as REMOVE_OPT=1"
-        rm -rf "$t"
-      fi
-    done
-  else
-    log "Automatic /opt removals disabled (set REMOVE_OPT=1 to enable)."
-  fi
+    log "/opt usage (top entries):"
+    du -sh /opt/* 2>/dev/null | sort -h | head -n 20
+    
+    if [ "$REMOVE_OPT" = "1" ]; then
+        OPT_TARGETS=(/opt/local-path-provisioner)
+        for t in "${OPT_TARGETS[@]}"; do
+            if [ -d "$t" ]; then
+                log "Removing $t as REMOVE_OPT=1"
+                rm -rf "$t"
+            fi
+        done
+    else
+        log "Automatic /opt removals disabled (set REMOVE_OPT=1 to enable)."
+    fi
 fi
 
 # 13) Find large files > 100MB (report only)
@@ -150,8 +173,10 @@ log "Listing files larger than 100MB (report only):"
 find / -xdev -type f -size +100M -printf '%s\t%p\n' 2>/dev/null | sort -nr | head -n 50 | awk '{printf "%.1fMB\t%s\n",$1/1024/1024,$2}'
 
 # Final disk usage
-log "Disk usage after cleanup:"
+log "Disk usage cleanup:"
 df -h
+log "Top-level usage ( / ):"
+du -xh --max-depth=1 / | sort -rh | head -n 20
 
 log "=== Cleanup finished ==="
 exit 0

package/scripts/test-monitor.sh

@@ -24,7 +24,7 @@ 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.30                    # runtime mode image (instance mode reads image from conf)
+IMAGE=underpost/wp:v3.2.70                    # 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

package/src/cli/cluster.js

@@ -876,6 +876,74 @@ net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-k3s.conf > /dev/null`,
       }
     },
 
+    /**
+     * @method _pruneContainerCaches
+     * @description Reclaims container-runtime disk left behind after a cluster
+     * teardown: stopped containers, unused images, build cache and anonymous
+     * volumes. Best-effort across every runtime present on the host (docker,
+     * podman, and optionally the CRI runtime via crictl). Each block is guarded
+     * by a command-existence check, so it is safe to call when a runtime is
+     * absent. This is what turns a "cluster deleted" into "disk actually freed":
+     * `kind delete` / `kubeadm reset` remove the cluster but leave gigabytes of
+     * images and overlay layers under /var/lib/{docker,containers}.
+     * @param {object} [options]
+     * @param {boolean} [options.all=true] - Remove all unused images, not just dangling ones.
+     * @param {boolean} [options.crictl=false] - Also prune the CRI runtime via crictl.
+     * @param {string} [options.criSocket] - Optional crictl --runtime-endpoint override.
+     * @private
+     */
+    _pruneContainerCaches(options = {}) {
+      const all = options.all !== false;
+      const a = all ? '-a ' : '';
+      logger.info(`  -> Pruning container-runtime caches (all=${all})...`);
+      // Docker (also matches the podman-docker shim when docker is symlinked to podman).
+      shellExec(
+        `if command -v docker >/dev/null 2>&1; then sudo docker system prune ${a}--volumes -f; sudo docker builder prune ${a}-f; fi`,
+        { silentOnError: true },
+      );
+      // Podman native — on this host images/overlays live under /var/lib/containers/storage.
+      shellExec(
+        `if command -v podman >/dev/null 2>&1; then sudo podman system prune ${a}--volumes -f; fi`,
+        { silentOnError: true },
+      );
+      if (options.crictl) {
+        const ep = options.criSocket ? `--runtime-endpoint ${options.criSocket} ` : '';
+        shellExec(
+          `if command -v crictl >/dev/null 2>&1; then sudo env PATH="$PATH:/usr/local/bin:/usr/bin" crictl ${ep}rmi --prune; fi`,
+          { silentOnError: true },
+        );
+      }
+      Underpost.cluster._unmountOrphanContainerOverlays();
+    },
+
+    /**
+     * @method _unmountOrphanContainerOverlays
+     * @description Unmounts leaked container overlay 'merged' mounts under
+     * /var/lib/{containers/storage,docker}/overlay. Pruning images/containers
+     * frees the backing data but leaves these mountpoints attached, so they
+     * keep showing up as identical `overlay ... /merged` rows in `df -h` long
+     * after the containers are gone. Only overlays NOT backing a still-existing
+     * container are unmounted, so running workloads are never disturbed.
+     * Best-effort; safe to call when no runtime is present.
+     * @private
+     */
+    _unmountOrphanContainerOverlays() {
+      logger.info('  -> Unmounting orphaned container overlay mounts...');
+      shellExec(`if command -v podman >/dev/null 2>&1; then sudo podman umount --all >/dev/null 2>&1 || true; fi`, {
+        silentOnError: true,
+      });
+      shellExec(
+        `active="$(sudo podman ps -aq 2>/dev/null | xargs -r -I{} sudo podman inspect --format '{{.GraphDriver.Data.MergedDir}}' {} 2>/dev/null || true)"
+findmnt -rn -o TARGET 2>/dev/null | grep -E '/var/lib/(containers/storage|docker)/overlay.*/merged' | sort -r | while IFS= read -r m; do
+  if ! printf '%s\\n' "$active" | grep -qxF "$m"; then
+    echo "Unmounting orphaned overlay: $m"
+    sudo umount -l "$m" 2>/dev/null || true
+  fi
+done`,
+        { silentOnError: true },
+      );
+    },
+
     /**
      * @method _lazyUmountKubeletMounts
      * @description Lazy-unmounts every mount under /var/lib/kubelet so a
@@ -910,7 +978,7 @@ net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-k3s.conf > /dev/null`,
       if (options.removeVolumeHostPaths) Underpost.cluster._cleanHostPathPvs();
       else logger.info('  -> Skipping (pass --remove-volume-host-paths to enable).');
 
-      logger.info('Phase 3/5: Deleting all Kind clusters...');
+      logger.info('Phase 3/6: Deleting all Kind clusters...');
       shellExec(`clusters=$(kind get clusters)
 if [ -n "$clusters" ]; then
   for c in $clusters; do
@@ -919,11 +987,14 @@ if [ -n "$clusters" ]; then
   done
 fi`);
 
-      logger.info('Phase 4/5: Cleaning kubeconfig and Kind Docker networks...');
+      logger.info('Phase 4/6: Cleaning kubeconfig and Kind Docker networks...');
       shellExec(`rm -rf "$HOME/.kube"`);
       Underpost.cluster.recoverKindDockerNetworks();
 
-      logger.info('Phase 5/5: Re-applying host configuration (Docker, containerd, sysctl).');
+      logger.info('Phase 5/6: Pruning container-runtime caches (kindest/node images, build cache, volumes)...');
+      Underpost.cluster._pruneContainerCaches({ all: true });
+
+      logger.info('Phase 6/6: Re-applying host configuration (Docker, containerd, sysctl).');
       Underpost.cluster.config();
 
       logger.info('=== KIND SAFE RESET COMPLETE ===');
@@ -995,7 +1066,7 @@ fi`);
       shellExec(`if ip link show tunl0 >/dev/null 2>&1; then sudo ip link del tunl0; fi`);
       shellExec(`sudo iptables -F`);
       shellExec(`sudo iptables -t nat -F`);
-      shellExec(`if command -v crictl >/dev/null 2>&1; then sudo crictl rmi --prune; fi`);
+      Underpost.cluster._pruneContainerCaches({ all: true, crictl: true });
 
       logger.info('Phase 7/7: Re-applying host configuration (Docker, containerd, sysctl).');
       Underpost.cluster.config();
@@ -1042,6 +1113,8 @@ fi`);
       shellExec(`if [ -d /etc/rancher/k3s ]; then sudo rm -rf /etc/rancher/k3s; fi`);
       shellExec(`if ip link show flannel.1 >/dev/null 2>&1; then sudo ip link del flannel.1; fi`);
       shellExec(`if ip link show cni0 >/dev/null 2>&1; then sudo ip link del cni0; fi`);
+      // k3s-uninstall.sh removes /var/lib/rancher/k3s; still prune any host docker/podman leftovers.
+      Underpost.cluster._pruneContainerCaches({ all: true });
 
       logger.info('Phase 5/5: Re-applying minimal K3s host config.');
       Underpost.cluster.configMinimalK3s();

package/src/cli/deploy.js

@@ -562,7 +562,7 @@ ${Underpost.deploy
           const yamlPath = `./engine-private/conf/${deployId}/build/${env}/secret.yaml`;
           fs.writeFileSync(yamlPath, secretYaml, 'utf8');
         } else {
-          const deploymentsFiles = ['Dockerfile', 'proxy.yaml', 'deployment.yaml', 'pv-pvc.yaml'];
+          const deploymentsFiles = ['Dockerfile', 'proxy.yaml', 'deployment.yaml', 'pv-pvc.yaml', 'grpc-service.yaml'];
           for (const file of deploymentsFiles) {
             if (fs.existsSync(`./engine-private/conf/${deployId}/build/${env}/${file}`)) {
               fs.copyFileSync(
@@ -1009,10 +1009,17 @@ EOF`);
      */
     configMap(env, namespace = 'default') {
       const cronDeployId = cronDeployIdResolve() || 'dd-cron';
+      const envFilePath = `/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${env}`;
+      // `--from-env-file` turns every KEY=VALUE into a secret key that the Deployment injects via
+      // `envFrom`. Strip shell/runtime-critical keys (notably PATH) first — an injected PATH
+      // overrides the image's own and breaks coreutils/sudo resolution inside the pod.
+      const sanitizedEnvPath = `${envFilePath}.secret`;
+      fs.writeFileSync(sanitizedEnvPath, Underpost.secret.sanitizeSecretEnvFile(fs.readFileSync(envFilePath, 'utf8')));
       shellExec(`kubectl delete secret underpost-config -n ${namespace} --ignore-not-found`);
       shellExec(
-        `kubectl create secret generic underpost-config --from-env-file=/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${env} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
+        `kubectl create secret generic underpost-config --from-env-file=${sanitizedEnvPath} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
       );
+      fs.removeSync(sanitizedEnvPath);
     },
     /**
      * Switches the traffic for a deployment.

package/src/cli/docker-compose.js

@@ -77,14 +77,42 @@ class UnderpostDockerCompose {
     return nodePath.isAbsolute(relPath) ? relPath : nodePath.join(getRootDirectory(), relPath);
   }
 
+  /**
+   * Resolves the canonical directory for a custom docker-compose workflow,
+   * keyed by `--deploy-id` + `--docker-compose-id`:
+   * `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>`.
+   * This directory ships its own `docker-compose.yml`, `compose.env`, and
+   * `nginx.conf` (used as-is, never generated). Returns null when
+   * `--docker-compose-id` is not set (the default, self-generating workflow).
+   * @param {object} options - CLI options.
+   * @returns {string|null} Repo-root-relative canonical dir, or null.
+   * @memberof UnderpostDockerCompose
+   */
+  static composeIdBase(options = {}) {
+    if (!options.dockerComposeId) return null;
+    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
+    return `engine-private/conf/${deployId}/docker-compose/${options.dockerComposeId}`;
+  }
+
   /**
    * Builds the base `docker compose` invocation with explicit file and env-file,
    * so behavior is independent of the caller's working directory.
+   *
+   * Custom workflow (`--docker-compose-id`): the compose file, env-file, and
+   * bind-mounted config (nginx.conf, mongodb/) all live in the canonical dir, so
+   * compose runs with `--project-directory` pinned there and no app-override.
    * @param {object} options - CLI options.
    * @returns {string} The base command string (without a subcommand).
    * @memberof UnderpostDockerCompose
    */
   static baseCmd(options = {}) {
+    const base = UnderpostDockerCompose.composeIdBase(options);
+    if (base) {
+      const projectDir = UnderpostDockerCompose.resolve(base);
+      const composeFile = UnderpostDockerCompose.resolve(options.composeFile || `${base}/docker-compose.yml`);
+      const envFile = UnderpostDockerCompose.resolve(options.envFile || `${base}/compose.env`);
+      return `docker compose --project-directory ${projectDir} --env-file ${envFile} -f ${composeFile}`;
+    }
     const composeFile = UnderpostDockerCompose.resolve(options.composeFile || 'docker-compose.yml');
     const envFile = UnderpostDockerCompose.resolve(options.envFile || 'docker/compose.env');
     const overrideFile = UnderpostDockerCompose.resolve(options.appOverride || 'docker/compose.app.yml');
@@ -163,7 +191,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.2.22
+APP_TAG=v3.2.70
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest
@@ -343,6 +371,20 @@ datasources:
    * @memberof UnderpostDockerCompose
    */
   static generate(options = {}) {
+    // Custom workflow: docker-compose.yml, compose.env, and nginx.conf are
+    // pre-authored in the canonical dir and used as-is — do NOT generate them.
+    // Only (re)write the required MongoDB entrypoint (replica-set bootstrap),
+    // the single generated infra artifact, into <canonical>/mongodb so the
+    // stack stays self-contained under `--project-directory`.
+    const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
+    if (composeIdBase) {
+      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
+      fs.mkdirpSync(nodePath.dirname(mongoEntrypointPath));
+      fs.writeFileSync(mongoEntrypointPath, UnderpostDockerCompose.mongoEntrypointContent(), { mode: 0o755 });
+      logger.info('mongodb entrypoint written (custom workflow)', { path: mongoEntrypointPath });
+      return;
+    }
+
     Nginx.removeRouter();
     for (const { host, routes } of PROXY_HOSTS) Nginx.createApp({ host, routes });
     Nginx.createDefaultServer(DEFAULT_UPSTREAM);
@@ -449,6 +491,20 @@ datasources:
       silentOnError: true,
     });
 
+    // Custom workflow: the compose file, compose.env, and nginx.conf are
+    // hand-authored source — never prune them. Only drop the one generated
+    // artifact (the mongo entrypoint), regenerated on the next --up/--generate.
+    const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
+    if (composeIdBase) {
+      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
+      if (fs.existsSync(mongoEntrypointPath)) {
+        fs.removeSync(mongoEntrypointPath);
+        logger.info('removed generated artifact', { path: mongoEntrypointPath });
+      }
+      logger.info('Docker Compose reset complete. Run `--up` to recreate the stack.');
+      return;
+    }
+
     // Phase 2: prune generated artifacts (regenerated on the next --generate/--up).
     const artifacts = options.force
       ? [...GENERATED_ARTIFACTS, options.envFile || 'docker/compose.env']
@@ -489,6 +545,7 @@ datasources:
      * @param {boolean} [options.shell] - Open an interactive shell in `target` (default: app).
      * @param {string} [options.exec] - General-purpose passthrough docker compose subcommand.
      * @param {string} [options.deployId] - Deployment to run as the app (default: dd-default). `dd-default` self-bootstraps a fresh engine; any other id runs the standard `underpost start` command.
+     * @param {string} [options.dockerComposeId] - Custom-workflow selector. When set, use the canonical stack at `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>/` (docker-compose.yml + compose.env + nginx.conf, used as-is), skipping nginx/env/app-override generation. Used by the Cyberia MMO ecosystem (`--deploy-id dd-cyberia --docker-compose-id cyberia`).
      * @param {string} [options.env] - Deployment environment for non-default deploy ids (default: development).
      * @param {string} [options.composeFile] - Override compose file path.
      * @param {string} [options.envFile] - Override env-file path.

package/src/cli/fs.js

@@ -64,6 +64,31 @@ class UnderpostFileStorage {
     writeStorageConf(storage, storageConf) {
       if (storage) fs.writeFileSync(storageConf, JSON.stringify(storage, null, 4), 'utf8');
     },
+    /**
+     * @method gitTrack
+     * @description Optional, non-fatal Git tracking layer. Any Git error is logged and swallowed
+     * so it can never interrupt or roll back the canonical `storage.*.json` workflow.
+     * @param {string} gitPath - The working directory to stage/commit.
+     * @param {object} [options] - Tracking options.
+     * @param {boolean} [options.init=false] - If true, initialize a local repo before staging.
+     * @param {string} [options.message=''] - Explicit commit message; when omitted, `underpost cmt` is used.
+     * @memberof UnderpostFileStorage
+     */
+    gitTrack(gitPath, options = { init: false, message: '' }) {
+      try {
+        if (options.init === true) Underpost.repo.initLocalRepo({ path: gitPath });
+        shellExec(`cd ${gitPath} && git add .`, { silentOnError: true, silent: true, disableLog: true });
+        if (options.message)
+          shellExec(`cd ${gitPath} && git commit -m "${options.message}"`, {
+            silentOnError: true,
+            silent: true,
+            disableLog: true,
+          });
+        else shellExec(`underpost cmt ${gitPath} feat`, { silentOnError: true, silent: true, disableLog: true });
+      } catch (error) {
+        logger.warn('git tracking skipped (non-fatal)', { gitPath, error: error?.message });
+      }
+    },
     /**
      * @method recursiveCallback
      * @description Recursively processes files and directories based on the provided options.
@@ -125,6 +150,7 @@ class UnderpostFileStorage {
 
         if (hasPathFilter && options.force === true && fs.existsSync(basePath)) fs.removeSync(basePath);
 
+        // Storage is canonical: persist the removal before any (optional) git tracking runs.
         Underpost.fs.writeStorageConf(storage, storageConf);
 
         if (associatedPaths.length === 0)
@@ -136,13 +162,8 @@ class UnderpostFileStorage {
           });
 
         if (options.git === true) {
-          const gitPath = hasPathFilter ? basePath : '.';
-          shellExec(`cd ${gitPath} && git add .`);
-          shellExec(`underpost cmt ${gitPath} feat`, {
-            silentOnError: true,
-            silent: true,
-            disableLog: true,
-          });
+          const gitPath = !hasPathFilter ? '.' : isSingleFile ? parentDir : basePath;
+          Underpost.fs.gitTrack(gitPath);
         }
 
         return;
@@ -151,7 +172,16 @@ class UnderpostFileStorage {
       // For single files, run getDeleteFiles against the parent directory to avoid
       // trying to `cd` into a file.
       const gitContextPath = isSingleFile ? parentDir : path;
-      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(gitContextPath);
+      // Detecting locally-deleted files is a best-effort enhancement backed by git; if the path is
+      // not a repo (or git is unavailable) it must not block the canonical storage workflow.
+      let deleteFiles = [];
+      if (options.pull !== true) {
+        try {
+          deleteFiles = Underpost.repo.getDeleteFiles(gitContextPath);
+        } catch (error) {
+          logger.warn('delete detection skipped (git unavailable)', { path: gitContextPath, error: error?.message });
+        }
+      }
 
       // When processing a single file, only consider it for deletion
       for (const relativePath of deleteFiles) {
@@ -172,12 +202,7 @@ class UnderpostFileStorage {
         if (pullSkipCount > 0) logger.warn(`Pull skipped ${pullSkipCount} files that already exist`);
         // Only run git init/commit when the caller explicitly requests git tracking (--git flag).
         // For bundle pulls into ./build the git step is unwanted and would error on a non-repo path.
-        if (options.git === true) {
-          Underpost.repo.initLocalRepo({ path: gitContextPath });
-          shellExec(`cd ${gitContextPath} && git add . && git commit -m "Base pull state"`, {
-            silentOnError: true,
-          });
-        }
+        if (options.git === true) Underpost.fs.gitTrack(gitContextPath, { init: true, message: 'Base pull state' });
       } else {
         let files;
         if (isSingleFile) {
@@ -200,15 +225,9 @@ class UnderpostFileStorage {
           } else logger.warn('File already exists', _path);
         }
       }
+      // Storage is canonical and always persisted; git is an optional layer on top.
       Underpost.fs.writeStorageConf(storage, storageConf);
-      if (options.git === true) {
-        shellExec(`cd ${gitContextPath} && git add .`);
-        shellExec(`underpost cmt ${gitContextPath} feat`, {
-          silentOnError: true,
-          silent: true,
-          disableLog: true,
-        });
-      }
+      if (options.git === true) Underpost.fs.gitTrack(gitContextPath);
     },
     /**
      * @method callback
@@ -230,10 +249,12 @@ class UnderpostFileStorage {
       path,
       options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false, omitUnzip: false },
     ) {
-      if (options.recursive === true || options.git === true)
+      // rm always routes through recursiveCallback so storage.*.json is updated regardless of
+      // --recursive/--git. The bare `delete` primitive only removes the remote asset and would
+      // otherwise leave the tracked storage key orphaned.
+      if (options.recursive === true || options.git === true || options.rm === true)
         return await Underpost.fs.recursiveCallback(path, options);
       if (options.pull === true) return await Underpost.fs.pull(path, options);
-      if (options.rm === true) return await Underpost.fs.delete(path, options);
       return await Underpost.fs.upload(path, options);
     },
     /**