@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/api/object-layer/object-layer.service.js

@@ -15,13 +15,18 @@ import { loggerFactory } from '../../server/ops/logger.js';
 import { ObjectLayerRenderFramesDto } from '../object-layer-render-frames/object-layer-render-frames.model.js';
 import { FileFactory } from '../file/file.service.js';
 import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import sharp from 'sharp';
+import { validateStats } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import { ObjectLayerDto } from './object-layer.model.js';
 import { ObjectLayerEngine } from '../../projects/cyberia/object-layer.js';
 import { shellExec } from '../../server/runtime/process.js';
 import { DataQuery } from '../../server/storage/data-query.js';
 import { AtlasSpriteSheetService } from '../atlas-sprite-sheet/atlas-sprite-sheet.service.js';
+import { AtlasSpriteSheetStore } from '../../projects/cyberia/atlas-sprite-sheet-store.js';
 import { IpfsClient } from '../../projects/cyberia/ipfs-client.js';
-import { createPinRecord, removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
+import { removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
 
 /**
  * Logger instance for this module.
@@ -45,8 +50,8 @@ class ObjectLayerService {
    * - `/metadata/:itemType/:itemId` — Create an object layer from uploaded frames and metadata.
    * - Default — Create an object layer directly from the request body.
    *
-   * The `/metadata` and default routes delegate to {@link ObjectLayerEngine.createObjectLayerDocuments}
-   * for document creation, atlas generation, SHA-256 computation, and IPFS pinning.
+   * The `/metadata` and default routes delegate to {@link ObjectLayerEngine.persistObjectLayerDocuments}
+   * for the document write, atlas generation, SHA-256 computation, and IPFS pinning.
    *
    * @async
    * @function post
@@ -160,22 +165,12 @@ class ObjectLayerService {
           metadataOverride: req.body,
         });
 
-      const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
+      const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
         ObjectLayer,
         ObjectLayerRenderFrames,
         objectLayerRenderFramesData,
         objectLayerData,
-        createOptions: {
-          generateAtlas: true,
-          atlasServiceContext: {
-            req,
-            res,
-            options,
-            AtlasSpriteSheetService,
-            IpfsClient,
-            createPinRecord,
-          },
-        },
+        persistOptions: { options },
       });
 
       return objectLayer;
@@ -191,44 +186,32 @@ class ObjectLayerService {
     bodyData.data.render.cid = '';
     bodyData.data.render.metadataCid = '';
 
-    // If has render frames, generate atlas + CIDs BEFORE creating the ObjectLayer
+    // Stage the atlas CIDs before the write, so the document is never stored without them.
     if (bodyData.objectLayerRenderFramesId) {
       const renderFramesDoc = await ObjectLayerRenderFrames.findById(bodyData.objectLayerRenderFramesId);
       if (renderFramesDoc) {
         try {
-          const stagingOL = {
-            data: bodyData.data,
-            objectLayerRenderFramesId: renderFramesDoc,
-          };
-          const result = await AtlasSpriteSheetService.generate(
-            { objectLayer: stagingOL, auth: req.auth },
-            res,
+          const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+            itemKey: bodyData.data.item.id,
+            objectLayerRenderFrames: renderFramesDoc,
             options,
-            { skipObjectLayerSave: true },
-          );
-          bodyData.data.render.cid = result.atlasCid;
-          bodyData.data.render.metadataCid = result.atlasMetadataCid;
-          bodyData.atlasSpriteSheetId = result.atlasDoc._id;
+          });
+          bodyData.data.render.cid = atlasCid;
+          bodyData.data.render.metadataCid = atlasMetadataCid;
+          bodyData.atlasSpriteSheetId = atlasDoc._id;
         } catch (atlasError) {
           logger.error('Failed to auto-generate atlas for new ObjectLayer:', atlasError);
         }
       }
     }
 
-    // Pin data JSON to IPFS
-    try {
-      const itemId = bodyData.data.item.id;
-      const mfsPath = `/object-layer/${itemId}/${itemId}_data.json`;
-      const ipfsResult = await IpfsClient.addJsonToIpfs(bodyData.data, `${itemId}_data.json`, mfsPath);
-      if (ipfsResult) {
-        bodyData.cid = ipfsResult.cid;
-        await createPinRecord({ cid: ipfsResult.cid, resourceType: 'object-layer-data', mfsPath, options });
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to pin data JSON to IPFS:', ipfsError.message);
-    }
+    const dataCid = await ObjectLayerEngine.pinObjectLayerData({
+      data: bodyData.data,
+      itemId: bodyData.data.item.id,
+      options,
+    });
+    if (dataCid) bodyData.cid = dataCid;
 
-    // Atomic create/replace – ObjectLayer is fully populated with all CIDs
     return await (await ObjectLayer.upsertByItemId(bodyData)).populate('objectLayerRenderFramesId');
   };
 
@@ -257,25 +240,33 @@ class ObjectLayerService {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
     const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
 
-    // GET /search-item-ids?q=<partial> - Fast partial match search on data.item.id
+    // Object layers are addressed by item id, the key the editor navigates by.
+    const keyFilter = (key) => DataQuery.naturalKeyFilter('data.item.id', key);
+
+    // GET /search-item-ids - item identity, by prefix (`q`, for type-ahead) or by exact ids
+    // (`ids`, comma separated). Carries the item's type because that is what addresses its
+    // sprite directory; an id alone cannot be previewed.
     if (req.path.startsWith('/search-item-ids')) {
       const q = (req.query.q || '').trim();
-      if (!q) return { itemIds: [] };
-      // Escape regex special characters for safe partial matching
-      const escaped = q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const results = await ObjectLayer.find(
-        { 'data.item.id': { $regex: escaped, $options: 'i' } },
-        { 'data.item.id': 1, _id: 0 },
-      )
-        .limit(20)
+      const ids = String(req.query.ids || '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+      if (!q && ids.length === 0) return { items: [] };
+      const query = ids.length
+        ? { 'data.item.id': { $in: ids } }
+        : // Escape regex special characters for safe partial matching
+          { 'data.item.id': { $regex: q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), $options: 'i' } };
+      const results = await ObjectLayer.find(query, { 'data.item.id': 1, 'data.item.type': 1, _id: 0 })
+        .limit(ids.length ? ids.length : 20)
         .lean();
-      const itemIds = [...new Set(results.map((r) => r.data.item.id))];
-      return { itemIds };
+      const byId = new Map(results.map((r) => [r.data.item.id, r.data.item.type || '']));
+      return { items: [...byId].map(([id, type]) => ({ id, type })) };
     }
 
     // GET /frame-counts/:id - Get frame counts for each direction using numeric codes
     if (req.path.startsWith('/frame-counts/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getMetadata())
         .populate('objectLayerRenderFramesId');
       if (!objectLayer) {
@@ -318,7 +309,7 @@ class ObjectLayerService {
 
     // GET /render/:id - Get only render data for specific object layer
     if (req.path.startsWith('/render/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getRender())
         .populate('objectLayerRenderFramesId');
       if (!objectLayer) {
@@ -333,7 +324,7 @@ class ObjectLayerService {
 
     // GET /metadata/:id - Get only metadata (no render frames/colors) for specific object layer
     if (req.path.startsWith('/metadata/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getMetadata())
         .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
       if (!objectLayer) {
@@ -385,22 +376,14 @@ class ObjectLayerService {
     }
 
     // GET / - Get paginated list of object layers
-    const id = req.params.id || req.query.id;
-    logger.info(`ObjectLayerService.get - filtering check - id: ${id}`);
-    if (id && id !== 'undefined' && !['render', 'metadata', 'frame-counts'].includes(id)) {
-      try {
-        const objectLayer = await ObjectLayer.findById(id)
-          .select(ObjectLayerDto.select.get())
-          .populate('atlasSpriteSheetId', 'cid')
-          .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
-        if (objectLayer) {
-          logger.info(`ObjectLayerService.get - found record by id: ${id}`);
-          return { data: [objectLayer], total: 1, page: 1, totalPages: 1 };
-        }
-        logger.warn(`ObjectLayerService.get - record NOT found for id: ${id}`);
-      } catch (e) {
-        logger.warn(`Invalid ID format or not found: ${id}`);
-      }
+    const key = req.params.id || req.query.id;
+    if (key && key !== 'undefined' && !['render', 'metadata', 'frame-counts'].includes(key)) {
+      const objectLayer = await ObjectLayer.findOne(keyFilter(key))
+        .select(ObjectLayerDto.select.get())
+        .populate('atlasSpriteSheetId', 'cid')
+        .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
+      if (objectLayer) return { data: [objectLayer], total: 1, page: 1, totalPages: 1 };
+      logger.warn(`ObjectLayerService.get - no object layer for key: ${key}`);
     }
 
     const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
@@ -493,9 +476,14 @@ class ObjectLayerService {
     // Create temporary output file path
     const tempOutputPath = `${framesFolder}/${tmpOutputFileName}`;
 
+    // img2webp takes one frame size, and frames of one direction may differ: the game
+    // stretches each to the entity's cell box, so the preview stretches them to the
+    // largest one — nearest-neighbour, since a scaled frame is still pixel art.
+    const stagedFolder = await ObjectLayerService.stageUniformFrames(framesFolder, pngFiles);
+
     try {
       // Change to the frames directory and execute img2webp command
-      const cmd = `cd "${framesFolder}" && img2webp -d ${frameDuration} -loop 0 *.png -o ${tmpOutputFileName}`;
+      const cmd = `cd "${stagedFolder ?? framesFolder}" && img2webp -d ${frameDuration} -loop 0 *.png -o "${path.resolve(tempOutputPath)}"`;
 
       logger.info(`Executing command: ${cmd}`);
 
@@ -546,9 +534,41 @@ class ObjectLayerService {
       }
 
       throw error;
+    } finally {
+      if (stagedFolder) await fs.remove(stagedFolder);
     }
   };
 
+  /**
+   * Stages copies of the frames resized to one common size when they differ, or returns null
+   * when they already share one and can be encoded in place.
+   * @function stageUniformFrames
+   * @memberof ObjectLayerService
+   * @param {string} framesFolder - Directory holding the direction's PNG frames.
+   * @param {string[]} pngFiles - Frame file names, in animation order.
+   * @returns {Promise<string|null>} Temporary directory with the resized frames, or null.
+   */
+  static stageUniformFrames = async (framesFolder, pngFiles) => {
+    const sizes = await Promise.all(
+      pngFiles.map(async (file) => {
+        const { width, height } = await sharp(`${framesFolder}/${file}`).metadata();
+        return { file, width, height };
+      }),
+    );
+    const width = Math.max(...sizes.map((size) => size.width));
+    const height = Math.max(...sizes.map((size) => size.height));
+    if (sizes.every((size) => size.width === width && size.height === height)) return null;
+
+    const stagedFolder = await fs.mkdtemp(path.join(os.tmpdir(), 'ol-webp-'));
+    for (const { file } of sizes) {
+      await sharp(`${framesFolder}/${file}`)
+        .resize(width, height, { fit: 'fill', kernel: 'nearest' })
+        .toFile(`${stagedFolder}/${file}`);
+    }
+    logger.info(`Staged ${pngFiles.length} frame(s) at ${width}x${height} for webp encoding`);
+    return stagedFolder;
+  };
+
   /**
    * PUT handler for updating object layers, their frame images, and metadata.
    *
@@ -557,8 +577,8 @@ class ObjectLayerService {
    * - `/:id/metadata/:itemType/:itemId` — Update metadata and reprocess all frames.
    * - `/:id` — Standard update from request body.
    *
-   * The `/metadata` route delegates to {@link ObjectLayerEngine.updateObjectLayerDocuments}
-   * for document update, atlas regeneration, SHA-256 computation, and IPFS pinning.
+   * The `/metadata` route delegates to {@link ObjectLayerEngine.persistObjectLayerDocuments}
+   * for the document write, atlas regeneration, SHA-256 computation, and IPFS pinning.
    *
    * @async
    * @function put
@@ -652,7 +672,6 @@ class ObjectLayerService {
 
     // PUT /:id/metadata/:itemType/:itemId - Update object layer metadata and reprocess all frames
     if (req.path.includes('/metadata/')) {
-      const objectLayerId = req.params.id;
       const itemType = req.params.itemType;
       const itemId = req.params.itemId;
 
@@ -683,24 +702,12 @@ class ObjectLayerService {
           metadataOverride: req.body,
         });
 
-      // Update documents using engine method (with atlas generation)
-      const { objectLayer } = await ObjectLayerEngine.updateObjectLayerDocuments({
-        objectLayerId,
+      const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
         ObjectLayer,
         ObjectLayerRenderFrames,
         objectLayerRenderFramesData,
         objectLayerData,
-        updateOptions: {
-          generateAtlas: true,
-          atlasServiceContext: {
-            req,
-            res,
-            options,
-            AtlasSpriteSheetService,
-            IpfsClient,
-            createPinRecord,
-          },
-        },
+        persistOptions: { options },
       });
 
       return objectLayer;
@@ -715,25 +722,19 @@ class ObjectLayerService {
     // Apply body updates to staging data in memory
     const updateData = { ...req.body };
     const stagingData = updateData.data || existingOL.data.toObject();
+    stagingData.stats = validateStats(stagingData.stats);
     if (!stagingData.render) stagingData.render = {};
 
-    // Use existing render frames if available
-    const renderFramesData = existingOL.objectLayerRenderFramesId;
-    if (renderFramesData) {
+    if (existingOL.objectLayerRenderFramesId) {
       try {
-        const stagingOL = {
-          data: stagingData,
-          objectLayerRenderFramesId: renderFramesData,
-        };
-        const result = await AtlasSpriteSheetService.generate(
-          { objectLayer: stagingOL, auth: req.auth },
-          res,
+        const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+          itemKey: stagingData.item.id,
+          objectLayerRenderFrames: existingOL.objectLayerRenderFramesId,
           options,
-          { skipObjectLayerSave: true },
-        );
-        stagingData.render.cid = result.atlasCid;
-        stagingData.render.metadataCid = result.atlasMetadataCid;
-        updateData.atlasSpriteSheetId = result.atlasDoc._id;
+        });
+        stagingData.render.cid = atlasCid;
+        stagingData.render.metadataCid = atlasMetadataCid;
+        updateData.atlasSpriteSheetId = atlasDoc._id;
       } catch (atlasError) {
         logger.error('Failed to auto-update atlas for ObjectLayer:', atlasError);
       }
@@ -742,25 +743,17 @@ class ObjectLayerService {
     updateData.data = stagingData;
     updateData.sha256 = ObjectLayerEngine.computeSha256(stagingData);
 
-    // Pin data JSON to IPFS
-    try {
-      const itemId = stagingData.item.id;
-      const mfsPath = `/object-layer/${itemId}/${itemId}_data.json`;
-      const ipfsResult = await IpfsClient.addJsonToIpfs(stagingData, `${itemId}_data.json`, mfsPath);
-      if (ipfsResult) {
-        updateData.cid = ipfsResult.cid;
-        await createPinRecord({ cid: ipfsResult.cid, resourceType: 'object-layer-data', mfsPath, options });
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to pin data JSON to IPFS:', ipfsError.message);
-    }
+    const dataCid = await ObjectLayerEngine.pinObjectLayerData({
+      data: stagingData,
+      itemId: stagingData.item.id,
+      options,
+    });
+    if (dataCid) updateData.cid = dataCid;
 
-    // Atomic update with all CIDs populated
-    let updatedObjectLayer = await ObjectLayer.findByIdAndUpdate(req.params.id, updateData, {
+    return await ObjectLayer.findByIdAndUpdate(req.params.id, updateData, {
       returnDocument: 'after',
+      runValidators: true,
     }).populate('objectLayerRenderFramesId');
-
-    return updatedObjectLayer;
   };
 
   /**

package/src/cli/app.js

@@ -205,14 +205,25 @@ class UnderpostApp {
       // The resolution loadConf performed, not `ociEnv()`, which forces the overlay on: a
       // skipped overlay and an applied one were indistinguishable in the pod log.
       const resolved = deployEnvContentFactory(deployId, context.env, `${context.args?.['sub-conf'] ?? ''}`.trim());
+      const inContainer = Underpost.state.isInsideContainer();
       logger.info('Deployment environment loaded', {
         deployId,
         instanceId: instanceId || null,
         source: envPath,
-        inContainer: Underpost.state.isInsideContainer(),
+        inContainer,
         ociOverlay: resolved.overlay,
         keys: Object.keys(values).length,
       });
+      // A container that resolves no overlay runs on the host-scoped endpoints of the base file —
+      // a loopback database, a local cache — and fails minutes later at the first connection,
+      // pointing at the endpoint rather than at the conf checkout that is missing the overlay.
+      // Named rather than thrown: a deployment is allowed to have no overlay for an environment.
+      if (inContainer && !instanceId && !resolved.overlay)
+        logger.warn('No OCI env overlay resolved; container is running on host-scoped values', {
+          deployId,
+          env: context.env,
+          expected: deployOciEnvFilePath(deployId, context.env),
+        });
       return { source: envPath, keys: Object.keys(values).length };
     },
 

package/src/cli/client.js

@@ -83,7 +83,7 @@ class UnderpostClient {
           const env = deployEnvFactory(options, process.env.NODE_ENV || 'development');
           process.env.NODE_ENV = env;
           if (options.mergeZip) {
-            mergeClientBuildZip({
+            await mergeClientBuildZip({
               buildPrefix: options.mergeZip,
               logger,
             });
@@ -91,7 +91,7 @@ class UnderpostClient {
           }
 
           if (options.unzip) {
-            unzipClientBuild({
+            await unzipClientBuild({
               buildPrefix: options.unzip,
               logger,
             });

package/src/cli/cluster.js

@@ -31,10 +31,18 @@ import {
 } from '../server/network/underpost-ingress.js';
 import { MONGODB_DEFAULT_REPLICA_COUNT } from '../db/mongo/MongooseDB.js';
 import { MongoBootstrap } from '../db/mongo/MongoBootstrap.js';
+import { MongoExpress } from '../db/mongo/MongoExpress.js';
 import os from 'os';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
 
+/**
+ * @constant CERT_MANAGER_VERSION
+ * @description Pinned cert-manager chart version.
+ * @memberof UnderpostCluster
+ */
+const CERT_MANAGER_VERSION = 'v1.17.0';
+
 const logger = loggerFactory(import.meta);
 
 const GATEWAY_API_RELEASE = 'v1.5.1';
@@ -82,6 +90,7 @@ class UnderpostCluster {
      * @param {object} [options] - Configuration options for cluster initialization.
      * @param {boolean} [options.mongodb=false] - Deploy MongoDB.
      * @param {boolean} [options.mongodb4=false] - Deploy MongoDB 4.4.
+     * @param {boolean} [options.mongoExpress=false] - Deploy the mongo-express web client for inspecting the MongoDB StatefulSet collections.
      * @param {string} [options.serviceHost=''] - Set a custom host/IP for exposed MongoDB and Valkey clients.
      * @param {boolean} [options.mariadb=false] - Deploy MariaDB.
      * @param {boolean} [options.mysql=false] - Deploy MySQL.
@@ -129,6 +138,7 @@ class UnderpostCluster {
       options = {
         mongodb: false,
         mongodb4: false,
+        mongoExpress: false,
         serviceHost: '',
         mariadb: false,
         mysql: false,
@@ -509,6 +519,10 @@ class UnderpostCluster {
           });
       }
 
+      // After both StatefulSet branches, so one invocation can bring up MongoDB and its inspector
+      // and the client reads the auth mode from the set this run just applied.
+      if (options.mongoExpress) await MongoExpress.deploy({ namespace: options.namespace, underpostRoot, options });
+
       // Installing one stack must never break the other. Whichever is already
       // present decides whether this install takes the node's 80/443 for itself
       // or joins the underpost ingress, so it is read before anything is applied.
@@ -663,22 +677,12 @@ EOF
         }
       }
 
-      if (options.certManager) {
-        if (!Underpost.kubectl.get('cert-manager').find((p) => p.STATUS === 'Running')) {
-          shellExec(`helm repo add jetstack https://charts.jetstack.io --force-update`);
-          shellExec(
-            `helm install cert-manager jetstack/cert-manager \
---namespace cert-manager \
---create-namespace \
---version v1.17.0 \
---set crds.enabled=true`,
-          );
-        }
-
-        const letsEncName = 'letsencrypt-prod';
-        shellExec(`sudo kubectl delete ClusterIssuer ${letsEncName} --ignore-not-found`);
-        shellExec(`sudo kubectl apply -f ${underpostRoot}/manifests/${letsEncName}.yaml -n ${options.namespace}`);
-      }
+      if (options.certManager)
+        Underpost.cluster.installCertManager({
+          namespace: options.namespace,
+          env: options.dev ? 'development' : 'production',
+          solver: Underpost.cluster.acmeSolverFactory({ options, presence: Underpost.cluster.ingressStackPresence() }),
+        });
     },
 
     /**
@@ -1093,6 +1097,57 @@ EOF
       return true;
     },
 
+    /**
+     * @method acmeSolverFactory
+     * @description Which ingress stack answers the HTTP-01 challenge.
+     *
+     * Read from the cluster, like {@link UnderpostCluster.ingressStackPresence}: the
+     * `cluster` runner installs the issuer in a separate invocation that carries no stack
+     * flag, so the flags alone would always name the Contour solver. `--contour` is the
+     * only explicit override; a cluster with the Gateway API data plane installed routes
+     * every hostname through it, so an Ingress solver there is unreachable.
+     * @param {object} params
+     * @param {object} [params.options] - Cluster init options.
+     * @param {{contour: boolean, gateway: boolean}} params.presence - Installed stacks.
+     * @returns {'gateway'|'ingress'} Solver kind.
+     * @memberof UnderpostCluster
+     */
+    acmeSolverFactory({ options = {}, presence }) {
+      if (options.contour === true && options.gatewayApi !== true) return 'ingress';
+      return options.gatewayApi === true || presence.gateway ? 'gateway' : 'ingress';
+    },
+
+    /**
+     * @method installCertManager
+     * @description Installs or upgrades cert-manager and applies the Let's Encrypt
+     * ClusterIssuer for the stack in use.
+     *
+     * `upgrade --install` rather than a one-time install: the Gateway API solver is
+     * ignored by a controller that was not started with `enableGatewayAPI`, so a cluster
+     * whose cert-manager predates the Gateway API migration must be re-configured, not
+     * skipped because a pod is Running. The version is pinned, so on a cluster already at
+     * it the upgrade is a no-op.
+     * @param {object} params
+     * @param {string} [params.namespace] - Namespace the deploys' Gateways live in.
+     * @param {string} [params.env] - Environment the routed deploys publish under.
+     * @param {'gateway'|'ingress'} params.solver - Which stack answers the challenge.
+     * @returns {{solver: string, parentRefs: Array<{name: string, namespace: string}>}} What was applied.
+     * @memberof UnderpostCluster
+     */
+    installCertManager({ namespace = 'default', env = 'production', solver }) {
+      const gatewayValues =
+        solver === 'gateway'
+          ? ' --set config.apiVersion=controller.config.cert-manager.io/v1alpha1' +
+            ' --set config.kind=ControllerConfiguration --set config.enableGatewayAPI=true'
+          : '';
+      shellExec(`helm repo add jetstack https://charts.jetstack.io --force-update`);
+      shellExec(
+        `helm upgrade --install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace` +
+          ` --version ${CERT_MANAGER_VERSION} --set crds.enabled=true${gatewayValues} --wait --timeout 5m`,
+      );
+      return Underpost.deploy.applyLetsEncryptIssuer({ solver, namespace, env });
+    },
+
     /**
      * @method ingressStackPresence
      * @description Which ingress data planes are installed right now.
@@ -1351,14 +1406,21 @@ EOF
       }
 
       try {
-        shellExec(`kubectl apply -f - -n ${namespace} <<'EOF'
+        // The manifest carries the whole nginx.conf: echoing it as the command line
+        // buries the lines that follow it — the fallback probes above all — under
+        // a page of routing tables on every sync.
+        logger.info('Applying the underpost ingress manifests', { namespace, node: ingressNode });
+        shellExec(
+          `kubectl apply -f - -n ${namespace} <<'EOF'
 ${underpostIngressManifestsFactory({
   namespace,
   conf,
   nodeName: ingressNode,
 })}
 EOF
-`);
+`,
+          { disableLog: true },
+        );
       } catch (error) {
         if (shouldHotReload)
           execIngress(`sh -c 'cp /tmp/nginx.previous.conf /tmp/nginx.conf && nginx -s reload -c /tmp/nginx.conf'`, {