@akash-chowdhury-24/deployhub 2.0.29 → 2.0.30

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.30",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

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
@@ -683,15 +693,101 @@ async function runBackendProcessChecks(config, envName, deployType = 'ssh') {
   }
 
   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(
+          `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}`,
+        };
       })
     );
 

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;
     }
 
@@ -441,6 +461,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

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,
   };
 }
 
@@ -457,10 +462,11 @@ 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 +480,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* ./
 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 +505,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']);
@@ -513,7 +522,7 @@ WORKDIR /app
 COPY composer.json composer.lock* ./
 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 +540,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 +552,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 \\

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}

package/src/utils/php-fpm.js

@@ -0,0 +1,133 @@
+/**
+ * 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() {
+  return (
+    `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;
+}