@akash-chowdhury-24/deployhub 2.0.29 → 2.0.31

package/README.md

@@ -651,8 +651,8 @@ All JS frontends share the same install/build flow: `npm ci` → `npm run build`
 
 - **Detect:** `composer.json` with `laravel/framework` or `symfony/framework-bundle`.
 - **Install:** Composer (on CI and server).
-- **CI runtime:** Generated workflows install PHP via `shivammathur/setup-php@v2` with Composer. Default version is **8.4** (meets current Laravel platform requirements). Override with `"phpVersion": "8.3"` at the config root or under `"backend"` in `deployhub.config.json`, then run `deployhub sync-workflows`.
-- **Deploy:** SSH with PHP-FPM or `php artisan` for Laravel.
+- **CI / Docker runtime:** Generated workflows install PHP via `shivammathur/setup-php@v2`, and PHP Dockerfiles use `php:{version}-cli-alpine` (verified tag pattern, e.g. `php:8.4-cli-alpine`). Both share `resolvePhpVersion()` — default **8.4**. Override with `"phpVersion": "8.3"` at the config root or under `"backend"` in `deployhub.config.json`, then regenerate the Dockerfile (delete the existing one so DeployHub can rewrite it) and run `deployhub sync-workflows` for CI.
+- **Deploy (SSH):** Assumes host php-fpm + nginx are already installed and configured for the deploy path. Restarts `php{version}-fpm` when present (from `resolvePhpVersion()`, default **8.4** → `php8.4-fpm`), or generic `php-fpm` on Amazon Linux/RHEL. Runs remote `composer install --no-dev` (and Laravel migrate/config:cache). Config `startCommand` (e.g. `php artisan serve`) is **not** used on SSH — FPM+nginx only.
 
 > ⚠️ **PHP-FPM deployments restart the FPM service for the ENTIRE host on every deploy.** If you run multiple DeployHub-managed environments on the same server, deploying ANY of them will briefly interrupt in-flight requests for ALL of them. For production use with multiple environments, either use separate hosts per environment, or set up per-environment PHP-FPM pools manually (not yet automated by DeployHub).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akash-chowdhury-24/deployhub",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

package/src/artifact/engine.js

@@ -19,7 +19,6 @@ import {
   getEnvSettings,
   resolveDefaultEnvironmentName,
 } from '../core/config.js';
-import { detectDjangoWsgiPackageDir } from '../utils/python-app-target.js';
 
 /**
  * @param {string} cwd
@@ -183,66 +182,117 @@ async function stageFrontendArtifact(cwd, stagingDir, config) {
  * @param {string} stagingDir
  * @param {import('../core/config.js').DeployHubConfig} config
  */
+/** Dirs/files that must never be packed into a backend artifact. */
+const BACKEND_STAGE_EXCLUDE = new Set([
+  'node_modules',
+  '.git',
+  '.github',
+  'artifact',
+  '.deployhub',
+  '.deployhub-storage',
+  '.deployhub-restore',
+  '.deployhub-doctor-test',
+  'coverage',
+  '.venv',
+  'venv',
+  '__pycache__',
+  'vendor',
+  '.idea',
+  '.vscode',
+  '.nyc_output',
+]);
+
+/**
+ * Copy the backend project tree into staging, skipping install caches and VCS.
+ * Allowlists previously omitted root entrypoints (server.js, main.go, index.php)
+ * which made SSH `npm start` / binary start fail even though CI built fine.
+ *
+ * @param {string} cwd
+ * @param {string} stagingDir
+ * @param {Set<string>} extraExclude
+ */
+async function copyBackendSourceTree(cwd, stagingDir, extraExclude = new Set()) {
+  const exclude = new Set([...BACKEND_STAGE_EXCLUDE, ...extraExclude]);
+  let entries = [];
+  try {
+    entries = await fs.readdir(cwd, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const ent of entries) {
+    if (exclude.has(ent.name)) continue;
+    if (ent.name.startsWith('.env') && ent.name !== '.env.example') continue;
+    const src = path.join(cwd, ent.name);
+    const dest = path.join(stagingDir, ent.name);
+    if (ent.isDirectory()) {
+      await fs.copy(src, dest, {
+        filter: (p) => {
+          const base = path.basename(p);
+          if (exclude.has(base)) return false;
+          if (base === '__pycache__' || base === 'node_modules' || base === '.git') {
+            return false;
+          }
+          return true;
+        },
+      });
+    } else {
+      await fs.copy(src, dest);
+    }
+  }
+}
+
+/**
+ * @param {string} stagingDir
+ */
+async function removeStagingDir(stagingDir) {
+  let lastErr;
+  for (let attempt = 0; attempt < 6; attempt++) {
+    try {
+      await fs.remove(stagingDir);
+      return;
+    } catch (err) {
+      lastErr = err;
+      await new Promise((r) => setTimeout(r, 50 * (attempt + 1)));
+    }
+  }
+  const message = lastErr instanceof Error ? lastErr.message : String(lastErr);
+  createLogger('artifact').warn(
+    `Could not remove staging dir after zip (artifact is still valid): ${message}`
+  );
+}
+
 async function stageBackendArtifact(cwd, stagingDir, config) {
   const settings = resolveBuildSettings(config);
   const framework = settings.framework;
 
-  await copyDirectoryIfExists(cwd, stagingDir, 'src');
-
-  for (const file of ['Dockerfile', 'docker-compose.yml', '.env.example']) {
-    await copyIfExists(cwd, stagingDir, file);
+  /** @type {Set<string>} */
+  const extraExclude = new Set();
+  // Compiled output is re-added selectively below (jars / publish / bin).
+  if (framework === 'spring' || framework === 'java') extraExclude.add('target');
+  if (framework === 'dotnet') {
+    extraExclude.add('bin');
+    extraExclude.add('obj');
   }
 
+  await copyBackendSourceTree(cwd, stagingDir, extraExclude);
+
   await copyKubernetesManifestsIfPresent(cwd, stagingDir);
 
-  await copyDirectoryIfExists(cwd, stagingDir, 'config');
-  await copyDirectoryIfExists(cwd, stagingDir, 'migrations');
-
-  if (['express', 'nestjs', 'fastify', 'koa', 'nextjs'].includes(framework)) {
-    await copyIfExists(cwd, stagingDir, 'package.json');
-    await copyIfExists(cwd, stagingDir, 'package-lock.json');
-  } else if (['fastapi', 'django', 'flask', 'python'].includes(framework)) {
-    // Source-only packages: root entrypoints + manifests (no dist/).
-    await copyIfExists(cwd, stagingDir, 'requirements.txt');
-    await copyIfExists(cwd, stagingDir, 'pyproject.toml');
-    await copyIfExists(cwd, stagingDir, 'Pipfile');
-    await copyIfExists(cwd, stagingDir, 'Pipfile.lock');
-    await copyIfExists(cwd, stagingDir, 'setup.py');
-    await copyIfExists(cwd, stagingDir, 'manage.py');
-    await copyIfExists(cwd, stagingDir, 'main.py');
-    await copyIfExists(cwd, stagingDir, 'app.py');
-    await copyIfExists(cwd, stagingDir, 'wsgi.py');
-    await copyIfExists(cwd, stagingDir, 'asgi.py');
-    await copyDirectoryIfExists(cwd, stagingDir, 'app');
-    await copyDirectoryIfExists(cwd, stagingDir, 'apps');
-    // Django project package often sits next to manage.py (e.g. config/, mysite/).
-    // `config/` is already copied above for all backends; also copy the detected
-    // package that owns wsgi.py when it is not config/app/apps.
-    if (framework === 'django') {
-      await copyDirectoryIfExists(cwd, stagingDir, 'templates');
-      await copyDirectoryIfExists(cwd, stagingDir, 'static');
-      const wsgiPkg = detectDjangoWsgiPackageDir(cwd);
-      if (
-        wsgiPkg &&
-        !['app', 'apps', 'config', 'templates', 'static', 'src'].includes(wsgiPkg)
-      ) {
-        await copyDirectoryIfExists(cwd, stagingDir, wsgiPkg);
+  if (['laravel', 'symfony', 'php'].includes(framework)) {
+    // storage/logs is written by php-fpm (www-data). Packing live logs is useless
+    // and unpacking them on the next deploy is a common permission-denied unzip.
+    const logsDir = path.join(stagingDir, 'storage', 'logs');
+    if (await fs.pathExists(logsDir)) {
+      const logFiles = await fs.readdir(logsDir);
+      for (const f of logFiles) {
+        if (f === '.gitignore') continue;
+        await fs.remove(path.join(logsDir, f));
       }
     }
-  } else if (['laravel', 'symfony', 'php'].includes(framework)) {
-    await copyIfExists(cwd, stagingDir, 'composer.json');
-    await copyIfExists(cwd, stagingDir, 'composer.lock');
-    await copyIfExists(cwd, stagingDir, 'artisan');
-    await copyDirectoryIfExists(cwd, stagingDir, 'app');
-    await copyDirectoryIfExists(cwd, stagingDir, 'bootstrap');
-    await copyDirectoryIfExists(cwd, stagingDir, 'public');
-    await copyDirectoryIfExists(cwd, stagingDir, 'routes');
-    await copyDirectoryIfExists(cwd, stagingDir, 'database');
-    await copyDirectoryIfExists(cwd, stagingDir, 'resources');
-    await copyDirectoryIfExists(cwd, stagingDir, 'storage');
-    await copyDirectoryIfExists(cwd, stagingDir, 'bin');
-  } else if (framework === 'spring' || framework === 'java') {
-    await copyIfExists(cwd, stagingDir, 'pom.xml');
+  }
+
+  if (framework === 'spring' || framework === 'java') {
     const targetDir = path.join(cwd, 'target');
     if (await fs.pathExists(targetDir)) {
       await fs.ensureDir(path.join(stagingDir, 'target'));
@@ -251,37 +301,20 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
         await fs.copy(path.join(targetDir, jar), path.join(stagingDir, 'target', jar));
       }
     }
-  } else if (framework === 'go') {
-    await copyIfExists(cwd, stagingDir, 'go.mod');
-    await copyIfExists(cwd, stagingDir, 'go.sum');
-    await copyDirectoryIfExists(cwd, stagingDir, 'bin');
   } else if (framework === 'dotnet') {
-    const files = await fs.readdir(cwd);
-    for (const f of files.filter((name) => name.endsWith('.csproj'))) {
-      await copyIfExists(cwd, stagingDir, f);
-    }
     await copyDirectoryIfExists(cwd, stagingDir, settings.buildOutput || 'publish');
-  } else if (framework === 'rails' || framework === 'ruby') {
-    await copyIfExists(cwd, stagingDir, 'Gemfile');
-    await copyIfExists(cwd, stagingDir, 'Gemfile.lock');
-    await copyIfExists(cwd, stagingDir, 'config.ru');
-    await copyIfExists(cwd, stagingDir, 'Rakefile');
-    await copyDirectoryIfExists(cwd, stagingDir, 'app');
-    await copyDirectoryIfExists(cwd, stagingDir, 'bin');
-    await copyDirectoryIfExists(cwd, stagingDir, 'lib');
-    await copyDirectoryIfExists(cwd, stagingDir, 'db');
-    await copyDirectoryIfExists(cwd, stagingDir, 'public');
-  } else {
-    await copyIfExists(cwd, stagingDir, 'package.json');
-    await copyIfExists(cwd, stagingDir, 'requirements.txt');
   }
 
-  // Only copy a named build-output dir when it actually exists (compiled langs).
-  // Skip '.' / 'src' — source is already staged above; never invent an empty dist/.
+  // Named build-output dir (nestjs dist/, etc.) when it exists and was not excluded.
   if (settings.buildOutput && settings.buildOutput !== '.' && settings.buildOutput !== 'src') {
     const built = path.join(cwd, settings.buildOutput);
-    if (await fs.pathExists(built) && !['target', 'bin', 'publish'].includes(settings.buildOutput)) {
-      await fs.copy(built, path.join(stagingDir, settings.buildOutput));
+    const staged = path.join(stagingDir, settings.buildOutput);
+    if (
+      (await fs.pathExists(built)) &&
+      !(await fs.pathExists(staged)) &&
+      !['target', 'bin', 'publish'].includes(settings.buildOutput)
+    ) {
+      await fs.copy(built, staged);
     }
   }
 }
@@ -417,18 +450,13 @@ ${getArtifactReadmeFooter()}`;
   const checksums = await generateChecksums(stagingDir);
   const checksumContent = formatChecksums(checksums);
   await fs.writeFile(path.join(artifactDir, 'checksums.txt'), checksumContent);
-  await fs.writeFile(path.join(stagingDir, 'checksums.txt'), checksumContent);
   await fs.writeJson(
-    path.join(stagingDir, 'deployment.json'),
+    path.join(artifactDir, 'deployment.json'),
     { targets: deployedTargets, deployedAt: timestamp },
     { spaces: 2 }
   );
-  await fs.writeFile(
-    path.join(stagingDir, 'release-notes.md'),
-    await getReleaseNotes(cwd)
-  );
 
-  await fs.remove(stagingDir);
+  await removeStagingDir(stagingDir);
   log.success(`Artifact created at ${artifactDir}`);
 
   return { artifactDir, zipPath };

package/src/commands/doctor.js

@@ -30,6 +30,16 @@ import {
 import { formatPasswordlessSudoGuidance } from '../utils/nginx.js';
 import { checkImagePullability } from '../utils/docker-image-deploy.js';
 import { namespaceExists } from '../utils/kubernetes-namespace.js';
+import { resolvePhpVersion } from '../utils/php-version.js';
+import {
+  buildPhpFpmUnitListCommand,
+  formatPhpFpmMissingError,
+  formatPhpFpmVersionMismatchError,
+  parsePhpFpmUnitList,
+  parsePhpMajorMinor,
+  pickPhpFpmUnitName,
+  preferredPhpFpmUnitName,
+} from '../utils/php-fpm.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -634,7 +644,6 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
 
     checks.push(
       await runCheck('pip', async () => {
-        // Deploy runs `pip install -r requirements.txt`; accept pip3 or pip.
         const result = await provider.runRemoteCheck(
           'command -v pip3 >/dev/null 2>&1 || command -v pip >/dev/null 2>&1'
         );
@@ -651,24 +660,11 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
       })
     );
 
-    checks.push(
-      await runCheck('gunicorn', async () => {
-        const result = await provider.runRemoteCheck('which gunicorn || gunicorn --version');
-        if (result.pass) {
-          return { name: 'gunicorn', pass: true, message: 'gunicorn available' };
-        }
-        return {
-          name: 'gunicorn',
-          pass: false,
-          message: 'not found — run: pip install gunicorn',
-        };
-      })
-    );
-
+    // FastAPI SSH starts uvicorn, not gunicorn. Requiring gunicorn here is a false failure.
     if (framework === 'fastapi') {
       checks.push(
         await runCheck('uvicorn', async () => {
-          const result = await provider.runRemoteCheck('which uvicorn || uvicorn --version');
+          const result = await provider.runRemoteCheck('command -v uvicorn >/dev/null 2>&1 || uvicorn --version');
           if (result.pass) {
             return { name: 'uvicorn', pass: true, message: 'uvicorn available' };
           }
@@ -679,29 +675,146 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
           };
         })
       );
+    } else {
+      checks.push(
+        await runCheck('gunicorn', async () => {
+          const result = await provider.runRemoteCheck('command -v gunicorn >/dev/null 2>&1 || gunicorn --version');
+          if (result.pass) {
+            return { name: 'gunicorn', pass: true, message: 'gunicorn available' };
+          }
+          return {
+            name: 'gunicorn',
+            pass: false,
+            message: 'not found — run: pip install gunicorn',
+          };
+        })
+      );
     }
   }
 
   if (PHP_FRAMEWORKS.has(framework)) {
+    const phpVersion = resolvePhpVersion(config);
+    const preferredUnit = preferredPhpFpmUnitName(phpVersion);
+
+    checks.push(
+      await runCheck('PHP CLI', async () => {
+        const result = await provider.runRemoteCheck('command -v php >/dev/null 2>&1 && php -v');
+        if (!result.pass) {
+          return {
+            name: 'PHP CLI',
+            pass: false,
+            message:
+              `php not found on PATH — install PHP ${phpVersion} CLI on the server ` +
+              `(needed for composer / artisan during SSH deploy)`,
+          };
+        }
+        const remoteMm = parsePhpMajorMinor(result.message);
+        if (remoteMm && remoteMm !== phpVersion) {
+          return {
+            name: 'PHP CLI',
+            pass: false,
+            message:
+              `php on server reports ${remoteMm} (from php -v), but this project expects ${phpVersion} ` +
+              `(phpVersion / backend.phpVersion / default). Install matching PHP or update deployhub.config.json.`,
+          };
+        }
+        return {
+          name: 'PHP CLI',
+          pass: true,
+          message: remoteMm
+            ? `php ${remoteMm} found on PATH (matches project)`
+            : `php found on PATH (${result.message.split('\n')[0] || 'ok'})`,
+        };
+      })
+    );
+
+    checks.push(
+      await runCheck('Composer', async () => {
+        const result = await provider.runRemoteCheck('command -v composer');
+        if (result.pass) {
+          return { name: 'Composer', pass: true, message: 'composer found on PATH' };
+        }
+        return {
+          name: 'Composer',
+          pass: false,
+          message:
+            'composer not found on PATH — install Composer on the server ' +
+            '(SSH deploy runs `composer install --no-dev` after extract)',
+        };
+      })
+    );
+
     checks.push(
       await runCheck('php-fpm', async () => {
-        const result = await provider.runRemoteCheck(
-          'systemctl is-active php8.2-fpm || systemctl is-active php-fpm'
+        const listed = await provider.runRemoteCheck(buildPhpFpmUnitListCommand());
+        const units = parsePhpFpmUnitList(listed.message || '');
+        const pick = pickPhpFpmUnitName(units, phpVersion);
+
+        if (!pick) {
+          return {
+            name: 'php-fpm',
+            pass: false,
+            message: formatPhpFpmMissingError(phpVersion, units),
+          };
+        }
+
+        if (pick.match === 'other-version') {
+          return {
+            name: 'php-fpm',
+            pass: false,
+            message: formatPhpFpmVersionMismatchError(phpVersion, pick.unit),
+          };
+        }
+
+        const active = await provider.runRemoteCheck(
+          `sudo -n systemctl is-active ${pick.unit}`
         );
-        if (result.pass && result.message.includes('active')) {
-          return { name: 'php-fpm', pass: true, message: 'php-fpm running' };
+        if (active.pass && String(active.message).includes('active')) {
+          const note =
+            pick.match === 'generic'
+              ? ` (generic php-fpm; preferred ${preferredUnit} not installed — OK on Amazon Linux/RHEL)`
+              : '';
+          return {
+            name: 'php-fpm',
+            pass: true,
+            message: `${pick.unit} running${note}`,
+          };
         }
-        return { name: 'php-fpm', pass: false, message: 'php-fpm not running' };
+
+        return {
+          name: 'php-fpm',
+          pass: false,
+          message:
+            `${pick.unit} is installed but not active (systemctl is-active: ${active.message}). ` +
+            `Start it with: sudo systemctl enable --now ${pick.unit}`,
+        };
       })
     );
 
     checks.push(
       await runCheck('nginx', async () => {
-        const result = await provider.runRemoteCheck('systemctl is-active nginx');
+        const installed = await provider.runRemoteCheck(
+          'command -v nginx >/dev/null 2>&1 && echo yes'
+        );
+        if (!installed.pass || !String(installed.message).includes('yes')) {
+          return {
+            name: 'nginx',
+            pass: false,
+            message:
+              'nginx not found on PATH — install it (Amazon Linux: sudo dnf install -y nginx; Ubuntu: sudo apt install nginx), then: sudo systemctl enable --now nginx',
+          };
+        }
+        const result = await provider.runRemoteCheck('sudo -n systemctl is-active nginx');
         if (result.pass && result.message.includes('active')) {
           return { name: 'nginx', pass: true, message: 'nginx running' };
         }
-        return { name: 'nginx', pass: false, message: 'nginx not running' };
+        return {
+          name: 'nginx',
+          pass: false,
+          message:
+            `nginx is installed but not active (systemctl is-active: ${result.message}). ` +
+            'Start it with: sudo systemctl enable --now nginx',
+        };
       })
     );
   }
@@ -727,6 +840,53 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
     );
   }
 
+  if (framework === 'dotnet') {
+    checks.push(
+      await runCheck('.NET runtime', async () => {
+        const result = await provider.runRemoteCheck('dotnet --version');
+        if (result.pass) {
+          return { name: '.NET runtime', pass: true, message: `dotnet ${result.message.split('\n')[0] || 'found'}` };
+        }
+        return {
+          name: '.NET runtime',
+          pass: false,
+          message:
+            'dotnet not found on PATH — install the ASP.NET Core runtime on the server ' +
+            '(SSH deploy runs `dotnet <dll>` after extract)',
+        };
+      })
+    );
+  }
+
+  if (framework === 'rails' || framework === 'ruby') {
+    checks.push(
+      await runCheck('Ruby', async () => {
+        const result = await provider.runRemoteCheck('command -v ruby >/dev/null 2>&1 && ruby -v');
+        if (result.pass) {
+          return { name: 'Ruby', pass: true, message: result.message.split('\n')[0] || 'ruby found' };
+        }
+        return {
+          name: 'Ruby',
+          pass: false,
+          message: 'ruby not found on PATH — install Ruby 3.2+ on the server (SSH deploy runs bundle install)',
+        };
+      })
+    );
+    checks.push(
+      await runCheck('Bundler', async () => {
+        const result = await provider.runRemoteCheck('command -v bundle');
+        if (result.pass) {
+          return { name: 'Bundler', pass: true, message: 'bundle found on PATH' };
+        }
+        return {
+          name: 'Bundler',
+          pass: false,
+          message: 'bundle not found on PATH — run: gem install bundler',
+        };
+      })
+    );
+  }
+
   return checks;
 }
 

package/src/deployment/deployment-env.js

@@ -55,7 +55,7 @@ export const SSH_BACKEND_ENV_VARS = [
   {
     key: 'SSH_APP_NAME',
     comment: [
-      'Process name used by PM2 when restarting your Node.js backend.',
+      'Env-scoped process identity: PM2 app name (Node), DEPLOYHUB_APP / PID markers (Python, Java, Go, .NET, Rails), and related resource names. Not the php-fpm systemd unit.',
     ],
     example: 'my-api',
     when: 'backend',

package/src/deployment/init-helpers.js

@@ -143,7 +143,9 @@ export async function validateSshKeyForDoctor(keyPath, sshKey) {
   }
 
   const mode = stat.mode & 0o777;
-  if (mode !== 0o400 && mode !== 0o600) {
+  // Windows NTFS does not carry Unix 400/600; OpenSSH uses ACLs instead.
+  // A 666 stat here is not "world-readable" the way it is on Linux.
+  if (process.platform !== 'win32' && mode !== 0o400 && mode !== 0o600) {
     return {
       ok: false,
       message: `SSH key permissions are ${mode.toString(8)} (should be 400 or 600) — run: chmod 600 ${resolved}`,

package/src/deployment/providers/ssh.js

@@ -13,6 +13,15 @@ import {
 import { resolvePm2AppName } from '../../utils/pm2-app-name.js';
 import { shellQuote, formatRemoteCommandFailure } from '../../utils/shell-quote.js';
 import { extractGunicornTarget } from '../../utils/python-app-target.js';
+import { resolvePhpVersion } from '../../utils/php-version.js';
+import {
+  buildPhpFpmUnitListCommand,
+  formatPhpFpmMissingError,
+  formatPhpFpmVersionMismatchError,
+  parsePhpFpmUnitList,
+  pickPhpFpmUnitName,
+  preferredPhpFpmUnitName,
+} from '../../utils/php-fpm.js';
 
 /** @type {Set<string>} */
 const NODE_FRAMEWORKS = new Set(['express', 'nestjs', 'fastify', 'koa', 'nextjs', 'node']);
@@ -389,13 +398,24 @@ export function createSshProvider(config, envName, env = process.env) {
     if (PHP_FRAMEWORKS.has(framework)) {
       // PHP uses a host-wide `systemctl restart php*-fpm` (see README PHP warning).
       // Per-env isolation is Nginx site name + deploy path — not automated FPM pools.
+      // startCommand (e.g. php artisan serve) is intentionally unused on SSH — FPM+nginx only.
+      const phpVersion = resolvePhpVersion(config);
+      const preferredUnit = preferredPhpFpmUnitName(phpVersion);
+      log.info(
+        `PHP backend detected — using php-fpm+nginx (prefer ${preferredUnit}, else php-fpm); ` +
+          `startCommand is not used for this method`
+      );
+
       await exec(ssh, `cd ${dir} && composer install --no-dev`);
       if (framework === 'laravel') {
         await exec(ssh, `cd ${dir} && php artisan migrate --force`);
         await exec(ssh, `cd ${dir} && php artisan config:cache`);
       }
-      await exec(ssh, 'sudo systemctl restart php8.2-fpm');
-      await exec(ssh, 'sudo systemctl reload nginx');
+
+      const fpmUnit = await resolveRemotePhpFpmUnit(ssh, phpVersion);
+      log.info(`Restarting PHP-FPM service: ${fpmUnit}`);
+      await exec(ssh, `sudo systemctl restart ${sh(fpmUnit)}`);
+      await reloadNginx(ssh);
       return;
     }
 
@@ -421,8 +441,13 @@ export function createSshProvider(config, envName, env = process.env) {
 
     if (framework === 'dotnet') {
       await stopScopedBackendProcess(ssh, targetPath);
-      const dll = startCommand?.replace('dotnet ', '') || 'App.dll';
-      await startScopedNohup(ssh, targetPath, `dotnet ${dll}`);
+      // Discover the published DLL at runtime — csproj name is not always App.dll
+      // (same class of bug as the Docker CMD ["dotnet","App.dll"] hardcode).
+      await startScopedNohup(
+        ssh,
+        targetPath,
+        `sh -c 'dll=$(ls -1 *.dll 2>/dev/null | head -n1); test -n "$dll" || { echo "No .dll found in $(pwd) for .NET start" >&2; exit 1; }; exec dotnet "$dll"'`
+      );
       return;
     }
 
@@ -441,6 +466,38 @@ export function createSshProvider(config, envName, env = process.env) {
     await exec(ssh, 'pm2 save');
   }
 
+  /**
+   * Resolve the php-fpm systemd unit on the remote host.
+   * Prefers php{version}-fpm (Debian/Ubuntu), then php-fpm (RHEL/Amazon Linux).
+   * Throws if nothing usable is installed — never restarts a guessed missing unit.
+   *
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} phpVersion
+   * @returns {Promise<string>}
+   */
+  async function resolveRemotePhpFpmUnit(ssh, phpVersion) {
+    const listCmd = buildPhpFpmUnitListCommand();
+    const listed = await ssh.execCommand(listCmd);
+    const units = parsePhpFpmUnitList(listed.stdout || '');
+    const pick = pickPhpFpmUnitName(units, phpVersion);
+
+    if (pick?.match === 'exact' || pick?.match === 'generic') {
+      if (pick.match === 'generic') {
+        log.info(
+          `Preferred ${preferredPhpFpmUnitName(phpVersion)} not installed; ` +
+            `using generic php-fpm (typical on Amazon Linux/RHEL)`
+        );
+      }
+      return pick.unit;
+    }
+
+    if (pick?.match === 'other-version') {
+      throw new Error(formatPhpFpmVersionMismatchError(phpVersion, pick.unit));
+    }
+
+    throw new Error(formatPhpFpmMissingError(phpVersion, units));
+  }
+
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} remotePath
@@ -524,13 +581,35 @@ export function createSshProvider(config, envName, env = process.env) {
     log.success('Nginx config tested and reloaded');
   }
 
+  /**
+   * Make an existing remote directory writable by the SSH user so the next
+   * unzip/rsync is not blocked by www-data ownership from php-fpm or nginx.
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} targetPath
+   */
+  async function ensureWritableDeployDir(ssh, targetPath) {
+    const targetQ = sh(targetPath);
+    const userQ = sh(user);
+    await exec(ssh, `mkdir -p ${targetQ}`);
+    await exec(
+      ssh,
+      `if [ -d ${targetQ} ]; then ` +
+        `chmod -R u+w ${targetQ} 2>/dev/null || true; ` +
+        `if [ ! -w ${targetQ} ]; then ` +
+          `sudo chown -R ${userQ}:${userQ} ${targetQ} 2>/dev/null || true; ` +
+          `chmod -R u+w ${targetQ} 2>/dev/null || true; ` +
+        `fi; ` +
+      `fi`
+    );
+  }
+
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} remoteZip
    * @param {string} targetPath
    */
   async function extractToPath(ssh, remoteZip, targetPath) {
-    await exec(ssh, `mkdir -p ${sh(targetPath)}`);
+    await ensureWritableDeployDir(ssh, targetPath);
     await exec(ssh, `unzip -o ${sh(remoteZip)} -d ${sh(targetPath)}`);
   }
 
@@ -554,13 +633,13 @@ export function createSshProvider(config, envName, env = process.env) {
         await exec(ssh, `mkdir -p ${sh(remoteStaging)}`);
         await exec(ssh, `unzip -o ${sh(remoteZip)} -d ${sh(remoteStaging)}`);
 
-        await exec(ssh, `mkdir -p ${sh(frontendDeployPath)}`);
+        await ensureWritableDeployDir(ssh, frontendDeployPath);
         await exec(
           ssh,
           `rsync -a ${sh(remoteStaging)}/ ${sh(frontendDeployPath)}/ --exclude backend || cp -r ${sh(remoteStaging)}/* ${sh(frontendDeployPath)}/`
         );
 
-        await exec(ssh, `mkdir -p ${sh(backendDeployPath)}`);
+        await ensureWritableDeployDir(ssh, backendDeployPath);
         await exec(
           ssh,
           `rsync -a ${sh(remoteStaging)}/backend/ ${sh(backendDeployPath)}/ || cp -r ${sh(remoteStaging)}/backend/* ${sh(backendDeployPath)}/`

package/src/detectors/frontend.detector.js

@@ -67,7 +67,7 @@ const FRAMEWORKS = {
       language: 'node',
       buildCommand: 'npm run build',
       startCommand: null,
-      buildOutput: 'public',
+      buildOutput: 'dist',
       testCommand: 'npm test',
       port: 80,
     },

package/src/utils/docker-image.js

@@ -174,7 +174,7 @@ WORKDIR /app
 COPY ${dir}/ .
 EXPOSE ${port}
 ENV ASPNETCORE_URLS=http://+:${port}
-CMD ["dotnet", "App.dll"]
+CMD ["sh", "-c", "dll=$(ls *.dll 2>/dev/null | head -n1); exec dotnet \\"$dll\\""]
 `;
 }
 
@@ -191,7 +191,7 @@ export function isFrontendStaticFramework(framework) {
  * @param {string} framework
  */
 export function isNodeBackendFramework(framework) {
-  return ['express', 'nestjs', 'fastify', 'koa', 'nextjs'].includes(framework || '');
+  return ['express', 'nestjs', 'fastify', 'koa', 'nextjs', 'node'].includes(framework || '');
 }
 
 /**
@@ -201,7 +201,7 @@ export function isNodeBackendFramework(framework) {
  */
 export function isInterpretedBackendFramework(framework) {
   return [
-    ...['express', 'nestjs', 'fastify', 'koa', 'nextjs'],
+    ...['express', 'nestjs', 'fastify', 'koa', 'nextjs', 'node'],
     'fastapi',
     'django',
     'flask',

package/src/utils/dockerfile.js

@@ -2,6 +2,8 @@
  * Dockerfile generation based on detected framework / project settings.
  */
 
+import { resolvePhpVersion } from './php-version.js';
+
 const GENERATED_HEADER =
   '# Generated by DeployHub — review exposed port and start command before deploying.\n';
 
@@ -18,10 +20,11 @@ export function sanitizeDockerProjectName(projectName) {
 
 /**
  * @param {import('../core/config.js').DeployHubConfig} config
- * @returns {{ framework: string, buildCommand: string|null, buildOutput: string, startCommand: string|null, port: number, projectType: string }}
+ * @returns {{ framework: string, buildCommand: string|null, buildOutput: string, startCommand: string|null, port: number, projectType: string, phpVersion: string }}
  */
 export function resolveDockerSettings(config) {
   const projectType = config.projectType || 'frontend';
+  const phpVersion = resolvePhpVersion(config);
 
   if (projectType === 'both' && config.backend) {
     const framework = config.backend.framework || 'express';
@@ -33,6 +36,7 @@ export function resolveDockerSettings(config) {
       startCommand: config.backend.startCommand ?? null,
       port: config.backend.port || defaultPort(framework, projectType),
       projectType,
+      phpVersion,
     };
   }
 
@@ -45,6 +49,7 @@ export function resolveDockerSettings(config) {
     startCommand: config.startCommand ?? null,
     port: config.port || defaultPort(framework, projectType),
     projectType,
+    phpVersion,
   };
 }
 
@@ -71,6 +76,8 @@ function defaultBuildOutput(framework, projectType) {
  * @param {string} projectType
  */
 function defaultPort(framework, projectType) {
+  // Next.js is a Node server, not nginx static — even when projectType is frontend.
+  if (framework === 'nextjs') return 3000;
   if (
     projectType === 'frontend' ||
     ['react', 'vue', 'angular', 'svelte', 'astro', 'vanilla'].includes(framework)
@@ -239,9 +246,21 @@ export function generateDockerfile(config) {
  * @param {{ buildCommand: string|null, buildOutput: string, port: number }} settings
  */
 function generateFrontendStaticDockerfile(settings) {
-  const buildCmd = settings.buildCommand || 'npm run build';
+  const buildCmd = settings.buildCommand;
   const output = settings.buildOutput || 'dist';
 
+  // Vanilla / prebuilt static trees have no compile step. Do not invent
+  // `npm run build` — that fails when package.json has no build script.
+  if (!buildCmd || String(buildCmd).trim() === '') {
+    const src = output === '.' ? '.' : output;
+    return `${GENERATED_HEADER}
+FROM nginx:alpine
+COPY ${src} /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`;
+  }
+
   return `${GENERATED_HEADER}
 FROM node:20-alpine AS build
 WORKDIR /app
@@ -276,6 +295,7 @@ FROM node:20-alpine AS build
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
+RUN mkdir -p public
 RUN ${buildCmd}
 
 FROM node:20-alpine AS runner
@@ -448,19 +468,19 @@ function generatePythonDockerfile(settings) {
   return `${GENERATED_HEADER}
 FROM python:3.11-slim
 WORKDIR /app
-COPY requirements.txt* ./
-RUN if [ -f requirements.txt ]; then pip install --no-cache-dir -r requirements.txt; fi
 COPY . .
+RUN if [ -f requirements.txt ]; then pip install --no-cache-dir -r requirements.txt; fi
 EXPOSE ${port}
 CMD ${JSON.stringify(startParts)}
 `;
 }
 
 /**
- * @param {{ port: number }} settings
+ * @param {{ port: number, phpVersion?: string }} settings
  */
 function generateLaravelDockerfile(settings) {
   const port = settings.port || 80;
+  const phpVersion = settings.phpVersion || resolvePhpVersion();
   // Single-process HTTP for container/K8s fitness. SSH deploys still use host
   // php-fpm + nginx; this image must listen on EXPOSE (FPM alone listens on 9000).
   const cmd = JSON.stringify([
@@ -474,13 +494,15 @@ function generateLaravelDockerfile(settings) {
   // Vendor stage copies only composer.json/lock for layer caching. Laravel's
   // post-autoload-dump runs `php artisan package:discover`, which needs the
   // full app — so install with --no-scripts here, then dump-autoload after COPY.
+  // --ignore-platform-reqs stays: composer:2 may ship a different PHP than the
+  // runtime image (phpVersion is applied only to the final stage below).
   return `${GENERATED_HEADER}
 FROM composer:2 AS vendor
 WORKDIR /app
-COPY composer.json composer.lock* ./
+COPY composer.json ./
 RUN composer install --no-dev --optimize-autoloader --no-interaction --ignore-platform-reqs --no-scripts
 
-FROM php:8.2-cli-alpine
+FROM php:${phpVersion}-cli-alpine
 WORKDIR /var/www/html
 COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
 RUN apk add --no-cache icu-libs libzip \\
@@ -497,10 +519,11 @@ CMD ${cmd}
 }
 
 /**
- * @param {{ port: number }} settings
+ * @param {{ port: number, phpVersion?: string }} settings
  */
 function generateSymfonyDockerfile(settings) {
   const port = settings.port || 80;
+  const phpVersion = settings.phpVersion || resolvePhpVersion();
   // Built-in server binds HTTP to EXPOSE — suitable for a single-container pod.
   // Prefer a production reverse-proxy image if you outgrow this starter template.
   const cmd = JSON.stringify(['php', '-S', `0.0.0.0:${port}`, '-t', 'public']);
@@ -510,10 +533,10 @@ function generateSymfonyDockerfile(settings) {
   return `${GENERATED_HEADER}
 FROM composer:2 AS vendor
 WORKDIR /app
-COPY composer.json composer.lock* ./
+COPY composer.json ./
 RUN composer install --no-dev --optimize-autoloader --no-interaction --ignore-platform-reqs --no-scripts
 
-FROM php:8.2-cli-alpine
+FROM php:${phpVersion}-cli-alpine
 WORKDIR /var/www/html
 COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
 RUN apk add --no-cache icu-libs libzip \\
@@ -531,10 +554,11 @@ CMD ${cmd}
 /**
  * Plain PHP (no Laravel/Symfony): single-process built-in server.
  * Docroot prefers public/ at runtime when present; optional composer install.
- * @param {{ port: number }} settings
+ * @param {{ port: number, phpVersion?: string }} settings
  */
 function generatePhpDockerfile(settings) {
   const port = settings.port || 80;
+  const phpVersion = settings.phpVersion || resolvePhpVersion();
   const cmd = JSON.stringify([
     'sh',
     '-c',
@@ -542,7 +566,7 @@ function generatePhpDockerfile(settings) {
   ]);
 
   return `${GENERATED_HEADER}
-FROM php:8.2-cli-alpine
+FROM php:${phpVersion}-cli-alpine
 WORKDIR /var/www/html
 COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
 RUN apk add --no-cache icu-libs libzip \\
@@ -590,7 +614,7 @@ function generateGoDockerfile(settings) {
   return `${GENERATED_HEADER}
 FROM golang:1.22-alpine AS build
 WORKDIR /app
-COPY go.mod go.sum* ./
+COPY go.mod ./
 RUN go mod download
 COPY . .
 RUN mkdir -p /app/bin && ${buildCmd}
@@ -612,6 +636,11 @@ function generateDotnetDockerfile(settings) {
   const buildCmd = settings.buildCommand || 'dotnet publish -c Release -o publish';
   const port = settings.port || 5000;
   const output = settings.buildOutput || 'publish';
+  const startParts = [
+    'sh',
+    '-c',
+    'dll=$(ls *.dll 2>/dev/null | head -n1); exec dotnet "$dll"',
+  ];
 
   return `${GENERATED_HEADER}
 FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
@@ -626,7 +655,7 @@ WORKDIR /app
 COPY --from=build /src/${output} .
 EXPOSE ${port}
 ENV ASPNETCORE_URLS=http://+:${port}
-CMD ["dotnet", "App.dll"]
+CMD ${JSON.stringify(startParts)}
 `;
 }
 
@@ -644,7 +673,7 @@ function generateRailsDockerfile(settings) {
 FROM ruby:3.2-slim AS build
 WORKDIR /app
 RUN apt-get update -qq && apt-get install -y build-essential libpq-dev && rm -rf /var/lib/apt/lists/*
-COPY Gemfile Gemfile.lock* ./
+COPY Gemfile ./
 RUN bundle config set --local without 'development test' && bundle install
 COPY . .
 RUN bundle exec rake assets:precompile || true
@@ -673,7 +702,7 @@ function generateRubyDockerfile(settings) {
 FROM ruby:3.2-slim
 WORKDIR /app
 RUN apt-get update -qq && apt-get install -y build-essential && rm -rf /var/lib/apt/lists/*
-COPY Gemfile Gemfile.lock* ./
+COPY Gemfile ./
 RUN bundle config set --local without 'development test' && bundle install
 COPY . .
 EXPOSE ${port}

package/src/utils/github-actions.js

@@ -22,9 +22,9 @@ import {
   getEnabledEnvironmentNames,
   isEnvEnabled,
 } from '../core/environments.js';
+import { resolvePhpVersion } from './php-version.js';
 
-/** Default PHP for CI when config does not set `phpVersion` / `backend.phpVersion`. */
-export const DEFAULT_PHP_VERSION = '8.4';
+export { DEFAULT_PHP_VERSION, resolvePhpVersion } from './php-version.js';
 
 /** @typedef {'aws'|'azure'|'gcp'|'gdrive'|'dropbox'|'local'|'ftp'|'ssh'} ProviderEnvKey */
 
@@ -271,27 +271,6 @@ function getGithubGitConfigStep() {
           fi`;
 }
 
-/**
- * Resolve PHP version for CI setup-php.
- * Order: `backend.phpVersion` → top-level `phpVersion` → {@link DEFAULT_PHP_VERSION} (`8.4`).
- * Set either config key in deployhub.config.json to pin a different runtime
- * (e.g. `"phpVersion": "8.3"` or `"backend": { "phpVersion": "8.3" }`).
- *
- * @param {import('../core/config.js').DeployHubConfig} [config]
- * @returns {string}
- */
-export function resolvePhpVersion(config) {
-  const fromBackend = config?.backend?.phpVersion;
-  if (typeof fromBackend === 'string' && fromBackend.trim()) {
-    return fromBackend.trim();
-  }
-  const fromRoot = config?.phpVersion;
-  if (typeof fromRoot === 'string' && fromRoot.trim()) {
-    return fromRoot.trim();
-  }
-  return DEFAULT_PHP_VERSION;
-}
-
 /**
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {boolean}
@@ -884,12 +863,10 @@ ${rollbackRun}
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {string}
  */
-function getInstallDepsCommand(config) {
-  if (!config) return 'npm install';
-
+function getBackendInstallDepsCommand(config) {
   const framework =
-    config.backend?.framework || config.framework || 'express';
-  const language = config.backend?.language || config.language;
+    config?.backend?.framework || config?.framework || 'express';
+  const language = config?.backend?.language || config?.language;
 
   if (language === 'python' || ['fastapi', 'django', 'flask', 'python'].includes(framework)) {
     return 'pip install -r requirements.txt';
@@ -912,6 +889,25 @@ function getInstallDepsCommand(config) {
   return 'npm install';
 }
 
+/**
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @returns {string}
+ */
+function getInstallDepsCommand(config) {
+  if (!config) return 'npm install';
+
+  const projectType = config.projectType || 'frontend';
+  if (projectType === 'frontend') return 'npm install';
+
+  const backendCmd = getBackendInstallDepsCommand(config);
+  // Fullstack: frontend is always Node in this CLI. Backend install alone
+  // (composer/pip/…) leaves the SPA without node_modules and `npm run build` dies.
+  if (projectType === 'both' && backendCmd !== 'npm install') {
+    return `npm install && ${backendCmd}`;
+  }
+  return backendCmd;
+}
+
 /**
  * Write deployhub.yml and deployhub-rollback.yml from the same secret/env helpers.
  *

package/src/utils/php-fpm.js

@@ -0,0 +1,135 @@
+/**
+ * PHP-FPM systemd unit naming for SSH deploys / doctor.
+ * Debian/Ubuntu: php8.4-fpm; Amazon Linux/RHEL: often plain php-fpm.
+ */
+
+import { resolvePhpVersion } from './php-version.js';
+
+/**
+ * @param {string} phpVersion — e.g. "8.4"
+ * @returns {string} — e.g. "php8.4-fpm"
+ */
+export function preferredPhpFpmUnitName(phpVersion) {
+  const v = String(phpVersion || '').trim();
+  return `php${v}-fpm`;
+}
+
+/**
+ * Shell command that lists installed php-fpm unit basenames (one per line).
+ * Uses unit-files so inactive-but-installed units still appear.
+ * @returns {string}
+ */
+export function buildPhpFpmUnitListCommand() {
+  // sudo -n: unprivileged SSH users cannot talk to systemd's private bus
+  // (Failed to connect to bus) inside containers and some hardened hosts.
+  return (
+    `sudo -n systemctl list-unit-files --type=service --no-legend ` +
+    `'php*-fpm.service' 'php-fpm.service' 2>/dev/null ` +
+    `| awk '{print $1}' | sed 's/\\.service$//' | sort -u`
+  );
+}
+
+/**
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+export function parsePhpFpmUnitList(stdout) {
+  if (!stdout || typeof stdout !== 'string') return [];
+  /** @type {Set<string>} */
+  const units = new Set();
+  for (const line of stdout.split(/\r?\n/)) {
+    const raw = line.trim();
+    if (!raw) continue;
+    // list-unit-files: "php8.4-fpm.service  enabled" — first column only
+    const first = raw.split(/\s+/)[0] || '';
+    const name = first.replace(/\.service$/i, '');
+    if (!name) continue;
+    if (name === 'php-fpm' || /^php[\d.]+-fpm$/i.test(name)) {
+      units.add(name === 'php-fpm' ? 'php-fpm' : name);
+    }
+  }
+  return [...units];
+}
+
+
+/**
+ * @typedef {{ unit: string, match: 'exact'|'generic'|'other-version' }} PhpFpmUnitPick
+ */
+
+/**
+ * Prefer versioned unit (Debian/Ubuntu), then generic php-fpm (RHEL/AL),
+ * else surface another versioned unit as a mismatch (do not silently use it
+ * for restart — caller decides whether to error).
+ *
+ * @param {string[]} availableUnits
+ * @param {string} phpVersion
+ * @returns {PhpFpmUnitPick | null}
+ */
+export function pickPhpFpmUnitName(availableUnits, phpVersion) {
+  const preferred = preferredPhpFpmUnitName(phpVersion);
+  const normalized = availableUnits.map((u) => u.trim()).filter(Boolean);
+  if (normalized.includes(preferred)) {
+    return { unit: preferred, match: 'exact' };
+  }
+  if (normalized.includes('php-fpm')) {
+    return { unit: 'php-fpm', match: 'generic' };
+  }
+  const other = normalized.find((u) => /^php[\d.]+-fpm$/i.test(u));
+  if (other) {
+    return { unit: other, match: 'other-version' };
+  }
+  return null;
+}
+
+/**
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @returns {string}
+ */
+export function resolvePreferredPhpFpmUnit(config) {
+  return preferredPhpFpmUnitName(resolvePhpVersion(config));
+}
+
+/**
+ * @param {string} phpVersion
+ * @param {string[]} [foundUnits]
+ * @returns {string}
+ */
+export function formatPhpFpmMissingError(phpVersion, foundUnits = []) {
+  const preferred = preferredPhpFpmUnitName(phpVersion);
+  const found =
+    foundUnits.length > 0 ? ` Found unit(s): ${foundUnits.join(', ')}.` : '';
+  return (
+    `No usable php-fpm systemd service for PHP ${phpVersion} ` +
+    `(looked for ${preferred} then php-fpm).${found} ` +
+    `Install PHP-FPM matching the project (Ubuntu/Debian: sudo apt install ${preferred}; ` +
+    `Amazon Linux/RHEL: often sudo yum install php-fpm) or set phpVersion / backend.phpVersion ` +
+    `in deployhub.config.json to match the server, then re-run.`
+  );
+}
+
+/**
+ * @param {string} phpVersion
+ * @param {string} foundUnit
+ * @returns {string}
+ */
+export function formatPhpFpmVersionMismatchError(phpVersion, foundUnit) {
+  const preferred = preferredPhpFpmUnitName(phpVersion);
+  return (
+    `Server has ${foundUnit} active/installed, but this project expects PHP ${phpVersion} ` +
+    `(service ${preferred}, or generic php-fpm on RHEL/Amazon Linux). ` +
+    `Install ${preferred} / matching PHP ${phpVersion}, or set phpVersion in deployhub.config.json ` +
+    `to match the server before deploy.`
+  );
+}
+
+/**
+ * Parse `php -v` / `PHP 8.4.1 (cli)...` style output to major.minor.
+ * @param {string} phpVOutput
+ * @returns {string|null} e.g. "8.4"
+ */
+export function parsePhpMajorMinor(phpVOutput) {
+  if (!phpVOutput || typeof phpVOutput !== 'string') return null;
+  const m = phpVOutput.match(/\bPHP\s+(\d+)\.(\d+)/i);
+  if (!m) return null;
+  return `${m[1]}.${m[2]}`;
+}

package/src/utils/php-version.js

@@ -0,0 +1,28 @@
+/**
+ * Shared PHP runtime version for CI (setup-php) and Docker base images.
+ * Keep Dockerfile FROM tags and GitHub Actions php-version in lockstep.
+ */
+
+/** Default PHP for CI / Docker when config does not set phpVersion. */
+export const DEFAULT_PHP_VERSION = '8.4';
+
+/**
+ * Resolve PHP version for setup-php and `php:{version}-cli-alpine` images.
+ * Order: `backend.phpVersion` → top-level `phpVersion` → {@link DEFAULT_PHP_VERSION} (`8.4`).
+ * Set either config key in deployhub.config.json to pin a different runtime
+ * (e.g. `"phpVersion": "8.3"` or `"backend": { "phpVersion": "8.3" }`).
+ *
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @returns {string}
+ */
+export function resolvePhpVersion(config) {
+  const fromBackend = config?.backend?.phpVersion;
+  if (typeof fromBackend === 'string' && fromBackend.trim()) {
+    return fromBackend.trim();
+  }
+  const fromRoot = config?.phpVersion;
+  if (typeof fromRoot === 'string' && fromRoot.trim()) {
+    return fromRoot.trim();
+  }
+  return DEFAULT_PHP_VERSION;
+}