underpost 3.2.22 → 3.2.28

package/src/cli/fs.js

@@ -95,6 +95,17 @@ class UnderpostFileStorage {
     ) {
       const { storage, storageConf } = Underpost.fs.getStorageConf(options);
 
+      // ── Single-file handling: when path is a file (not a directory), use parent dir
+      //    as the git working directory and process just that one file. ──────────────
+      let isSingleFile = false;
+      let parentDir = path;
+      let singleFileName = '';
+      if (fs.existsSync(path) && !fs.statSync(path).isDirectory()) {
+        isSingleFile = true;
+        parentDir = dir.dirname(path);
+        singleFileName = path.split('/').pop();
+      }
+
       // In recursive remove mode, delete every tracked storage key under the requested path,
       // even when local files/directories are already missing.
       if (options.rm === true) {
@@ -137,10 +148,15 @@ class UnderpostFileStorage {
         return;
       }
 
-      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(path);
+      // 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);
+
+      // When processing a single file, only consider it for deletion
       for (const relativePath of deleteFiles) {
-        const _path = path + '/' + relativePath;
-        if (_path in storage) {
+        const _path = isSingleFile ? (relativePath === singleFileName ? path : null) : path + '/' + relativePath;
+        if (_path && _path in storage) {
           await Underpost.fs.delete(_path);
           delete storage[_path];
         }
@@ -157,17 +173,25 @@ class UnderpostFileStorage {
         // 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 });
-          shellExec(`cd ${path} && git add . && git commit -m "Base pull state"`, {
+          Underpost.repo.initLocalRepo({ path: gitContextPath });
+          shellExec(`cd ${gitContextPath} && git add . && git commit -m "Base pull state"`, {
             silentOnError: true,
           });
         }
       } else {
-        const files =
-          options.git === true ? Underpost.repo.getChangedFiles(path) : await fs.readdir(path, { recursive: true });
+        let files;
+        if (isSingleFile) {
+          // Single file: treat the file itself as the sole item to process
+          files = [singleFileName];
+        } else {
+          files =
+            options.git === true
+              ? Underpost.repo.getChangedFiles(gitContextPath)
+              : await fs.readdir(path, { recursive: true });
+        }
         for (const relativePath of files) {
-          const _path = path + '/' + relativePath;
-          if (fs.statSync(_path).isDirectory()) {
+          const _path = isSingleFile ? path : path + '/' + relativePath;
+          if (fs.existsSync(_path) && fs.statSync(_path).isDirectory()) {
             if (options.pull === true && !fs.existsSync(_path)) fs.mkdirSync(_path, { recursive: true });
             continue;
           } else if (!(_path in storage) || options.force === true) {
@@ -178,8 +202,8 @@ class UnderpostFileStorage {
       }
       Underpost.fs.writeStorageConf(storage, storageConf);
       if (options.git === true) {
-        shellExec(`cd ${path} && git add .`);
-        shellExec(`underpost cmt ${path} feat`, {
+        shellExec(`cd ${gitContextPath} && git add .`);
+        shellExec(`underpost cmt ${gitContextPath} feat`, {
           silentOnError: true,
           silent: true,
           disableLog: true,

package/src/cli/index.js

@@ -738,6 +738,37 @@ program
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 
+program
+  .command('docker-compose')
+  .argument('[target]', 'Optional service name for --logs, --shell, --restart, or --build.')
+  .option('--install', 'Install Docker Engine and the Compose v2 plugin on RHEL/Rocky hosts.')
+  .option(
+    '--reset',
+    'Comprehensive teardown (equivalent to cluster --reset): removes all stack containers, the network, named volumes (destroys data), orphans, and generated artifacts.',
+  )
+  .option('--force', 'Force reinstall (--install), remove volumes (--down), or also drop the env-file (--reset).')
+  .option(
+    '--deploy-id <deploy-id>',
+    "Deployment to run as the app container (default: dd-default). 'dd-default' self-bootstraps a fresh engine; any other id runs the standard 'underpost start' command (mirrors src/cli/deploy.js).",
+  )
+  .option('--env <env>', 'Deployment environment for non-default deploy ids (default: development).')
+  .option('--generate', 'Render dynamic supporting files (nginx router config, env-file, app-command override).')
+  .option('--up', 'Start the full stack detached (regenerates config first).')
+  .option('--down', 'Stop and remove containers (and orphans).')
+  .option('--volumes', 'With --down, also remove named volumes (destroys persisted data).')
+  .option('--restart', 'Restart services (optionally a single [target]).')
+  .option('--build', 'With --up rebuild images; alone, rebuilds images with --no-cache.')
+  .option('--pull', 'Pull upstream images for all services.')
+  .option('--logs', 'Follow logs for all services (optionally a single [target]).')
+  .option('--status', 'Show a formatted status table of services.')
+  .option('--shell', 'Open an interactive shell in [target] (default: app).')
+  .option('--exec <subcommand>', 'General-purpose passthrough docker compose subcommand.')
+  .option('--compose-file <path>', 'Path to the compose file (default: docker-compose.yml).')
+  .option('--env-file <path>', 'Path to the compose env-file (default: docker/compose.env).')
+  .option('--nginx-conf <path>', 'Path to the generated nginx config (default: docker/nginx/default.conf).')
+  .description('General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack).')
+  .action(Underpost.dockerCompose.callback);
+
 program
   .command('lxd')
   .argument(
@@ -856,6 +887,42 @@ program
   .option('--remove-machines <system-ids>', 'Removes baremetal machines by comma-separated system IDs, or use "all"')
   .option('--clear-discovered', 'Clears all discovered baremetal machines from the database.')
   .option('--commission', 'Init workflow for commissioning a physical machine.')
+  .option(
+    '--install-disk [device]',
+    'Explicit target install disk for Rocky deployment (e.g. /dev/nvme0n1). Omit or leave empty to auto-detect the internal disk.',
+  )
+  .option(
+    '--no-auto-install',
+    'Disables the ephemeral runtime AUTO_INSTALL fallback (controller must trigger install).',
+  )
+  .option('--no-remote-install', 'Skips the controller-side remote install orchestration over SSH.')
+  .option(
+    '--worker',
+    'Post-install infra role: join the deployed node as a Kubernetes worker (requires --control <ip>). Without this flag the node is set up as a control-plane.',
+  )
+  .option('--control <ip>', 'Control-plane IP the worker node joins (used with --worker for kubeadm infra setup).')
+  .option(
+    '--ssh-key-dir <dir>',
+    'Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~.',
+  )
+  .option(
+    '--deploy-id <deploy-id>',
+    'Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command.',
+  )
+  .option(
+    '--user <user>',
+    'SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user.',
+  )
+  .option(
+    '--engine-repo <url>',
+    'Custom engine repo cloned + normalized to /home/dd/engine on the node (default: <GITHUB_USERNAME>/engine).',
+  )
+  .option('--engine-branch <branch>', 'Branch of the engine repo to clone on the node.')
+  .option(
+    '--engine-private-repo <url>',
+    'Custom private repo cloned + normalized to /home/dd/engine/engine-private on the node (default: <GITHUB_USERNAME>/engine-<id>-private).',
+  )
+  .option('--engine-private-branch <branch>', 'Branch of the engine-private repo to clone on the node.')
   .option(
     '--bootstrap-http-server-run',
     'Runs a temporary bootstrap HTTP server for generic purposes such as serving iPXE scripts or ISO images during commissioning.',
@@ -896,6 +963,14 @@ program
   )
   .option('--dev', 'Sets the development context environment for baremetal operations.')
   .option('--ls', 'Lists available boot resources and machines.')
+  .option(
+    '--resume-infra-setup',
+    'Skip commissioning, OS install, and all bootstrapping; resume only the SSH-based infra setup (kubeadm join/init) on a node that already has the OS installed and is reachable via SSH.',
+  )
+  .option(
+    '--resume-join',
+    'Skip everything except the kubeadm join command. Assumes engine, Node.js, CRI-O, kubelet, and kubeadm are already installed. Only retrieves a fresh join token from the control-plane and runs kubeadm join.',
+  )
   .description(
     'Manages baremetal server operations, including installation, database setup, commissioning, and user management.',
   )

package/src/cli/kickstart.js

@@ -43,46 +43,168 @@ class UnderpostKickStart {
 
     /**
      * @method kickstartPreVariables
-     * @description Generates the variable assignments block for the %pre script.
-     * @param {object} options
-     * @param {string} [options.rootPassword]
-     * @param {string} [options.authorizedKeys]
-     * @param {string} [options.adminUsername]
+     * @description Generates the shell variable-assignment block injected at the top of the
+     * kickstart `%pre` script. These variables drive both the ephemeral commissioning runtime
+     * and the unattended disk installer in `scripts/rocky-kickstart.sh`. Passwords are emitted
+     * base64-encoded (`*_B64`) and decoded by an in-script `ks_b64d` helper; all other values
+     * are single-quote escaped so arbitrary content survives the shell/heredoc layers.
+     * @param {object} options - Variable values to bake into the `%pre` block.
+     * @param {string} [options.rootPassword=''] - root console password (base64-encoded).
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user (defaults to MAAS_ADMIN_USERNAME).
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.timezone=''] - IANA timezone configured in the deployed OS (e.g. America/Santiago).
+     * @param {string} [options.keyboardLayout=''] - Console/X11 keyboard layout for the deployed OS (e.g. es).
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server for this host (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk (e.g. /dev/nvme0n1); empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the ephemeral runtime self-installs after a fallback timeout if no remote trigger arrives.
      * @memberof UnderpostKickStart
-     * @returns {string}
+     * @returns {string} Newline-joined bash variable assignments.
      */
-    kickstartPreVariables: ({ rootPassword = '', authorizedKeys = '', adminUsername = '' }) => {
+    kickstartPreVariables: ({
+      rootPassword = '',
+      authorizedKeys = '',
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
+      timezone = '',
+      keyboardLayout = '',
+      chronyConfPath = '/etc/chrony.conf',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
+    }) => {
       const sanitizedKeys = (authorizedKeys || '').trim();
+      // Passwords are passed base64-encoded so arbitrary characters (quotes,
+      // spaces, $, etc.) survive every shell/heredoc layer intact. base64 output
+      // never contains single quotes. Decoding tries `base64` then falls back to
+      // python3 so a minimal Anaconda environment can never yield empty passwords.
+      const b64 = (v) => Buffer.from(String(v || ''), 'utf8').toString('base64');
+      const sq = (v) => `'${String(v || '').replace(/'/g, "'\\''")}'`;
       return [
-        `ROOT_PASS='${rootPassword || ''}'`,
-        `AUTHORIZED_KEYS='${sanitizedKeys}'`,
-        `ADMIN_USER='${adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas'}'`,
+        `ks_b64d() { printf %s "$1" | base64 -d 2>/dev/null || printf %s "$1" | python3 -c 'import sys,base64;sys.stdout.buffer.write(base64.b64decode(sys.stdin.read().strip()))' 2>/dev/null; }`,
+        `ROOT_PASS_B64='${b64(rootPassword)}'`,
+        `ADMIN_PASS_B64='${b64(adminPassword || rootPassword)}'`,
+        `DEPLOY_PASS_B64='${b64(deployPassword)}'`,
+        `ROOT_PASS="$(ks_b64d "$ROOT_PASS_B64")"`,
+        `ADMIN_PASS="$(ks_b64d "$ADMIN_PASS_B64")"`,
+        `DEPLOY_PASS="$(ks_b64d "$DEPLOY_PASS_B64")"`,
+        `AUTHORIZED_KEYS=${sq(sanitizedKeys)}`,
+        `ADMIN_USER=${sq(adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas')}`,
+        `DEPLOY_USER=${sq(deployUsername)}`,
+        `NET_IP=${sq(netIp)}`,
+        `NET_PREFIX='${parseInt(netPrefix, 10) || 24}'`,
+        `NET_GATEWAY=${sq(netGateway)}`,
+        `NET_DNS=${sq(netDns)}`,
+        `TIMEZONE=${sq(timezone)}`,
+        `KEYBOARD_LAYOUT=${sq(keyboardLayout)}`,
+        `CHRONY_CONF_PATH=${sq(chronyConfPath || '/etc/chrony.conf')}`,
+        `BOOTSTRAP_URL=${sq(bootstrapUrl)}`,
+        `WORKFLOW_ID=${sq(workflowId)}`,
+        `SYSTEM_ID=${sq(systemId)}`,
+        `TARGET_HOSTNAME=${sq(targetHostname)}`,
+        `SSH_PORT='${sshPort || 22}'`,
+        `INSTALL_DISK_HINT=${sq(installDiskHint)}`,
+        `AUTO_INSTALL='${autoInstall ? '1' : '0'}'`,
       ].join('\n');
     },
 
     /**
      * @method kickstartFactory
      * @description Generates a complete kickstart configuration by combining the header,
-     * variable assignments, and the rocky-kickstart.sh script body.
-     * @param {object} options
-     * @param {string} [options.lang='en_US.UTF-8']
-     * @param {string} [options.keyboard='us']
-     * @param {string} [options.timezone='America/New_York']
-     * @param {string} [options.rootPassword]
-     * @param {string} [options.authorizedKeys]
+     * the `%pre` variable-assignment block, and the `scripts/rocky-kickstart.sh` body.
+     * @param {object} options - Kickstart generation options.
+     * @param {string} [options.lang='en_US.UTF-8'] - System language for the ephemeral runtime.
+     * @param {string} [options.keyboard='us'] - Keyboard layout for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.timezone='America/New_York'] - Timezone for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.rootPassword=process.env.MAAS_ADMIN_PASS] - root console password.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user created in the deployed OS.
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk; empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the runtime self-installs after a fallback timeout.
      * @memberof UnderpostKickStart
-     * @returns {string}
+     * @returns {string} The full kickstart (ks.cfg) source.
      */
     kickstartFactory: ({
       lang = 'en_US.UTF-8',
       keyboard = 'us',
       timezone = 'America/New_York',
+      chronyConfPath = '/etc/chrony.conf',
       rootPassword = process.env.MAAS_ADMIN_PASS,
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
       authorizedKeys = '',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
     }) => {
-      const adminUsername = process.env.MAAS_ADMIN_USERNAME || 'maas';
+      const resolvedAdminUsername = adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas';
       const header = UnderpostKickStart.API.kickstartHeader({ lang, keyboard, timezone, rootPassword });
-      const variables = UnderpostKickStart.API.kickstartPreVariables({ rootPassword, authorizedKeys, adminUsername });
+      const variables = UnderpostKickStart.API.kickstartPreVariables({
+        rootPassword,
+        authorizedKeys,
+        adminUsername: resolvedAdminUsername,
+        adminPassword,
+        deployUsername,
+        deployPassword,
+        netIp,
+        netPrefix,
+        netGateway,
+        netDns,
+        timezone,
+        keyboardLayout: keyboard,
+        chronyConfPath,
+        bootstrapUrl,
+        workflowId,
+        systemId,
+        targetHostname,
+        sshPort,
+        installDiskHint,
+        autoInstall,
+      });
 
       const scriptPath = path.resolve(__dirname, '../../scripts/rocky-kickstart.sh');
       const scriptBody = fs.readFileSync(scriptPath, 'utf8');

package/src/cli/repository.js

@@ -22,7 +22,7 @@ import {
   buildReplicaId,
   writeEnv,
 } from '../server/conf.js';
-import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../server/client-build.js';
+import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../client-builder/client-build.js';
 import { DefaultConf } from '../../conf.js';
 import Underpost from '../index.js';
 
@@ -1483,18 +1483,63 @@ Prevent build private config repo.`,
     },
 
     /**
-     * Runtime-type → in-pod site-root directory resolver.
-     * Maps each known runtime to the filesystem path where its repository lives inside the container.
-     * @param {string} runtime - The runtime identifier (e.g. 'wp').
-     * @param {string} host - The virtual-host name.
-     * @returns {string|null} Absolute path inside the pod, or null if the runtime has no known mapping.
+     * Resolves the in-pod site-root directory where a conf route's repository lives.
+     *
+     * General-purpose resolution, independent of any single runtime:
+     *   1. An explicit `directory` (the conf-declared document root) always wins.
+     *   2. Otherwise the runtime's base directory is used (e.g. `wp` → `/opt/lampp/htdocs/wp/<host>`).
+     *   3. A subdirectory route (e.g. `/wp`) appends `<subDir>` to the resolved root.
+     *
+     * This mirrors {@link WpService.createApp}'s `vhostDir`/`wpDir` layout so backups target the
+     * exact directory provisioning created, including subdirectory installs and custom directories.
+     *
+     * @param {object} opts
+     * @param {string} opts.runtime - The runtime identifier (e.g. 'wp').
+     * @param {string} opts.host - The virtual-host name.
+     * @param {string} [opts.routePath='/'] - The conf route path the repository is mounted under.
+     * @param {string} [opts.directory] - Explicit document root from conf; overrides the runtime base.
+     * @returns {string|null} Absolute path inside the pod, or null when neither a directory nor a
+     *   known runtime base resolves.
      * @memberof UnderpostRepository
      */
-    runtimeSiteRoot(runtime, host) {
-      const runtimePaths = {
+    runtimeSiteRoot({ runtime, host, routePath = '/', directory } = {}) {
+      const runtimeBase = {
         wp: `/opt/lampp/htdocs/wp/${host}`,
       };
-      return runtimePaths[runtime] || null;
+      const vhostDir = directory || runtimeBase[runtime];
+      if (!vhostDir) return null;
+      const subDir = routePath && routePath !== '/' ? routePath.replace(/^\/+/, '').replace(/\/+$/, '') : '';
+      return subDir ? `${vhostDir}/${subDir}` : vhostDir;
+    },
+
+    /**
+     * Probes a running pod for the first candidate directory that is a git repository
+     * (i.e. contains a `.git` entry). Used to locate a site root before backing it up so a
+     * missing/unprovisioned directory is detected up-front instead of producing an opaque
+     * shell `exit 1` from a failed `cd`.
+     *
+     * @param {object}   opts
+     * @param {string}   opts.podName   - Target pod name.
+     * @param {string}   opts.namespace - Kubernetes namespace.
+     * @param {string[]} opts.candidates - Absolute paths to probe, most-specific first.
+     * @returns {string|null} The first candidate that is a git repo, or null if none match.
+     * @memberof UnderpostRepository
+     */
+    podRepoDir({ podName, namespace, candidates }) {
+      const probe = candidates.map((dir) => `if [ -d '${dir}/.git' ]; then echo '${dir}'; exit 0; fi`).join('; ');
+      let out = '';
+      try {
+        out = Underpost.kubectl.exec({ podName, namespace, command: `${probe}; echo ''` }) || '';
+      } catch (err) {
+        logger.warn(`podRepoDir: probe failed in pod ${podName}`, err.message);
+        return null;
+      }
+      return (
+        out
+          .split('\n')
+          .map((line) => line.trim())
+          .find(Boolean) || null
+      );
     },
 
     /**
@@ -1543,12 +1588,28 @@ Prevent build private config repo.`,
           const entry = confServer[host][routePath];
           if (!entry.repository) continue;
 
-          const siteRoot = Underpost.repo.runtimeSiteRoot(entry.runtime, host);
-          if (!siteRoot) {
+          const siteRootArgs = { runtime: entry.runtime, host, directory: entry.directory };
+          const repoRoot = Underpost.repo.runtimeSiteRoot({ ...siteRootArgs, routePath });
+          if (!repoRoot) {
             logger.warn(`backupPodRepositories: no site-root mapping for runtime '${entry.runtime}' (${host})`);
             continue;
           }
 
+          // Probe the pod for the actual git repo so an unprovisioned/missing site root is
+          // detected and skipped cleanly instead of failing the in-pod `cd` with exit 1.
+          // Fall back to the vhost dir (root route) to cover conf/path drift.
+          const vhostRoot = Underpost.repo.runtimeSiteRoot({ ...siteRootArgs, routePath: '/' });
+          const candidates = [...new Set([repoRoot, vhostRoot].filter(Boolean))];
+          const siteRoot = Underpost.repo.podRepoDir({ podName, namespace, candidates });
+          if (!siteRoot) {
+            logger.warn(
+              `backupPodRepositories: no git repository found in pod ${podName} for ${host} (checked ${candidates.join(
+                ', ',
+              )}) — site may not be provisioned yet; skipping`,
+            );
+            continue;
+          }
+
           const repoName = entry.repository.split('/').pop().split('.')[0];
 
           // Build the backup script — secrets are injected as env vars in the exec,