Node Manager (PM2) for Plesk

Name: Node Manager Pm2
Author: ghostcompiler

Manage Node.js applications with PM2 from Plesk, with admin, reseller, and customer scoped access.

Overview

Node Manager (PM2) is a Plesk extension for managing Node.js applications with PM2 without SSH.

It is built for hosting panels where admins need a clean process manager for SSR apps, API servers, queues, websocket servers, and other long-running Node.js services while keeping customers scoped to their own subscriptions.

Creator

Name: Ghost Compiler
Email: hello@ghostcompiler.in
GitHub: ghostcompiler/node-manager-pm2
Profile: github.com/ghostcompiler
Logo: assets.ghostcompiler.in/logo.png

Documentation

Full GitHub Pages documentation is available at:

ghostcompiler.github.io/node-manager-pm2

The page is maintained in docs/index.html and uses the screenshots stored in docs/screenshots. It covers installation, access control, process management, runtime setup, file editing, logs, deployment, ecosystem config, metrics, backups, settings, and troubleshooting.

Screenshots

Screenshot set:

Dashboard: dark, light
Process list: dark, light
Create process: dark, light
File picker: dark, light
File editor drawer: dark, light
Runtime setup: dark, light
Logs drawer: dark, light
Environment variables: dark, light
Deployment: dark, light
Ecosystem editor: dark, light
Metrics: dark, light
Backups: dark, light
Settings: dark, light
Action menu: dark, light

Features

PM2 process list with start, stop, restart, reload, delete, and scaling controls.
Domain-scoped dashboard for admin, reseller, and customer users.
Runtime detection for Node.js, npm, PM2, Git, and PM2 home.
Admin PM2 install/update action for detected Plesk Node.js runtimes.
Live stdout/stderr log viewer with download and clear actions.
Environment variable manager with secret storage support.
Git deployment actions with optional npm install and zero-downtime reload.
PM2 ecosystem config editor.
CPU and memory metrics history with graph and pagination.
Backup and restore for extension-managed PM2 metadata.
Plesk service-plan permissions and process limits.

Complete Option Reference

The extension is domain scoped. All relative paths are resolved from the selected domain application root, and customer/reseller actions depend on Plesk service-plan permissions.

Top Actions

Info: Opens the extension information page with version, runtime, storage, permissions, and operational paths.
Refresh: Reloads domains, process state, runtime status, metrics, and visible tab data.
New Process: Opens the create-process page for the selected domain.

Domain Context

Domain: Selects the domain or subdomain workspace.
Subscription user: Shows the system user that owns the selected domain.
Application root: Shows the absolute document/application root used for relative process paths.
Permissions: Shows the current user's effective Node Manager permission level.

Processes Tab

Process row: Opens the process detail drawer.
Start: Starts a stopped PM2 process.
Stop: Stops a running process.
Restart: Restarts the process with PM2.
Reload: Performs a PM2 reload where supported.
Scale: Updates the process instance count.
Delete: Removes the PM2 process and extension metadata after confirmation.

Create Process Page

Name: PM2 application name.
Script path: JavaScript entry file. Browse opens the domain-scoped file picker, and selecting a file fills this field.
Working directory: Process working directory. Browse opens directories inside the selected domain root.
Environment: PM2 environment name, such as production.
Instances: Number of PM2 instances to run.
Max restarts: Optional restart limit passed to PM2.
Restart delay, ms: Optional delay before PM2 restarts the process.
Git repository: Optional deployment repository URL.
Git branch: Deployment branch used by the Deploy tab.
Autorestart if the process exits: Enables or disables PM2 autorestart.
Create and Start: Creates the config and starts the process.

File Picker And Editor

Document root: Returns to the selected domain root.
Up: Moves one directory up, but never outside the selected domain root.
Open: Opens a directory inside the picker.
Select: Selects a file or directory for the active form field.
Edit: Opens editable files in a Plesk drawer with the CodeEditor component.
Save: Writes the edited file content.
Close: Closes the drawer, with confirmation when changes are unsaved.

Runtime Tab

Use detected paths: Applies detected Node.js, npm, PM2, Git, and PM2 home values to settings.
Install or update PM2: Installs or updates PM2 using the detected runtime. The button is disabled while the action is running.
Runtime table: Shows Node.js, npm, PM2, and Git status, detected version, and resolved path.
PM2 home: Shows the PM2 home directory used for managed processes.

Settings Tab

Node binary path: Absolute path to node.
npm binary path: Absolute path to npm.
PM2 binary path: Absolute path to pm2.
Git binary path: Absolute path to git.
PM2 home: Directory used by PM2 for process state.
Extra PATH: Additional PATH entries for PM2 commands.
Polling interval: Process and metrics refresh interval.
Max log bytes: Maximum bytes read from stdout/stderr in the log drawer.
Metrics retention days: How long sampled CPU and memory metrics are kept.
Deployment timeout: Maximum deployment command runtime.
Save Settings: Persists settings for the extension.

Backups Tab

Create Backup: Exports extension-managed metadata and settings.
Restore: Imports a previous backup.
Delete: Removes a backup archive.
Backup list: Shows backup name, creation time, size, and available actions.

Process Detail Drawer

Logs: View stdout or stderr, refresh, clear by truncating the log file, and download logs.
Env: Add, edit, save, mark secret, or delete environment variables.
Deploy: Pull from Git, optionally run npm install, choose production dependencies, and reload after deployment.
Ecosystem: Edit the PM2 ecosystem configuration, save it, or save and start the process.
Metrics: View CPU and memory chart data plus the latest five metric samples by default.

Requirements

Plesk Obsidian 18.0.34 or newer on Linux.
Physical hosting enabled for domains that will run Node.js apps.
Plesk Node.js extension or another Node.js/npm runtime available on the server.
SQLite PDO extension available to the Plesk PHP runtime.
Git installed for deployment features.
PM2 installed globally or installed from the extension runtime page by an administrator.

Installation

Install the latest runner-built package directly from GitHub:

plesk bin extension --install-url https://github.com/ghostcompiler/node-manager-pm2/releases/download/latest/node-manager-pm2.zip

This URL points to the rolling latest release asset. The Package Latest workflow rebuilds node-manager-pm2.zip from the current main branch on every push and whenever it is started manually, so the install command stays stable and does not depend on a hardcoded version number.

Pinned version installs are also available after publishing a versioned release:

plesk bin extension --install-url https://github.com/ghostcompiler/node-manager-pm2/releases/download/v1.0.0/node-manager-pm2-1.0.0.zip

Build the extension ZIP locally:

./packaging/build.sh

Install the locally built archive through Plesk CLI:

plesk bin extension --install node-manager-pm2-1.0.0.zip

Or install through Plesk UI:

Open Plesk Admin.
Go to Extensions.
Click Upload Extension.
Upload node-manager-pm2-1.0.0.zip.
Open Node Manager (PM2) from the Plesk sidebar or a domain page.

Testing

Run the same local checks used by the CI runner:

npm ci --ignore-scripts --legacy-peer-deps
npm run build
find plib htdocs -type f \( -name '*.php' -o -name '*.phtml' \) -print0 | xargs -0 -n1 php -l
xmllint --noout meta.xml
node -e "JSON.parse(require('fs').readFileSync('packaging/manifest.json', 'utf8'))"
sh -n packaging/build.sh
sh -n sbin/pm2-helper
./packaging/build.sh
zip -T node-manager-pm2-1.0.0.zip

GitHub Actions runners are included:

CI runs on every branch push, pull request, and manual dispatch. It validates PHP, JavaScript, documentation screenshots, metadata, shell scripts, builds the extension, tests the ZIP, and uploads package artifacts.
Package Latest runs on main and manual dispatch. It builds and publishes the stable node-manager-pm2.zip asset to the rolling latest GitHub release.
Release runs on v<version> tags and manual dispatch. It verifies the tag matches meta.xml, builds node-manager-pm2-<version>.zip, and publishes the versioned release.
Pages runs when documentation changes on main and manual dispatch. It validates docs/index.html screenshot references and deploys the docs/ folder to GitHub Pages.

First Run

Open the affected service plan or subscription.
Enable Node Manager (PM2) access.
Enable the needed action permissions: control, logs, and manage.
Set Maximum PM2 applications to a non-zero value for subscriptions that can create processes.
Sync existing subscriptions if Plesk marks them as customized or out of sync.
Open Node Manager (PM2) as admin, reseller, or customer.
Review the Runtime tab and install PM2 if needed.

Example SSR Process

For a subdomain such as assets.example.com where the app root is:

/var/www/vhosts/example.com/assets.example.com

Use:

Name: assets-ssr
Script path: server.js
Working directory: .
Environment: production
Instances: 1
Autorestart: enabled

The extension resolves relative paths from the selected domain application root, so server.js becomes:

/var/www/vhosts/example.com/assets.example.com/server.js

Troubleshooting Logs

When the UI reports a 500 error, check:

tail -n 200 /var/log/plesk/panel.log
tail -n 200 /var/log/sw-cp-server/error_log
tail -n 200 /usr/local/psa/var/modules/node-manager-pm2/logs/node-manager-pm2.log

On some Plesk builds, the panel log is stored at:

tail -n 200 /usr/local/psa/admin/logs/panel.log

Security Model

Admins can view and manage all enabled domains.
Resellers and customers only see domains where Node Manager access is enabled.
Customer and reseller access is controlled by Plesk service plan permissions.
Process script and working-directory paths are locked inside the selected domain application root.
PM2 commands run under the selected domain system user when Plesk pm_ApiCli::callDomain() is available.
The extension stores PM2 metadata and secrets in SQLite under the Plesk module var directory.

Development Notes

PHP classes live in plib/library/NodeManagerPm2.
Authenticated UI and JSON APIs are served by plib/controllers/IndexController.php.
The Plesk React UI Library bundle lives in frontend/ and is built to htdocs/dist/node-manager-pm2-ui.js.
The public deployment webhook lives at htdocs/public/webhook.php.
Persistent state is stored in SQLite under the module var directory.
Package configuration lives in packaging/manifest.json and packaging/build.sh.

See docs/INSTALL.md, docs/SECURITY.md, docs/API.md, and docs/ARCHITECTURE.md for operational details.

Development Environment

Built using ServBay

Mac M4 Tested
macOS Apple Silicon
Powered by ServBay

Files main

Repository Files

Loading file structure...

plib/library/NodeManagerPm2/RuntimeService.php

<?php
class Modules_NodeManagerPm2_RuntimeService
{
    private $runner;

    public function __construct()
    {
        $this->runner = new Modules_NodeManagerPm2_CommandRunner();
    }

    public function versions($domain)
    {
        $items = [
            'node' => $this->runtimeItem($domain, 'nodeBinary', 'node', ['--version']),
            'npm' => $this->runtimeItem($domain, 'npmBinary', 'npm', ['--version']),
            'pm2' => $this->pm2RuntimeItem($domain),
            'git' => $this->runtimeItem($domain, 'gitBinary', 'git', ['--version']),
        ];

        return [
            'items' => $items,
            'ready' => $items['node']['available'] && $items['npm']['available'] && $items['pm2']['available'],
            'nodeReady' => $items['node']['available'] && $items['npm']['available'],
            'pm2Ready' => $items['pm2']['available'],
            'pm2Home' => $domain->getHomePath() . '/.pm2',
            'detectedPaths' => self::detectedPathEntries(),
            'settings' => Modules_NodeManagerPm2_Config::all(),
        ];
    }

    public function installOrUpdatePm2()
    {
        $npmItem = $this->detectBinary('npm', Modules_NodeManagerPm2_Config::get('npmBinary', 'npm'));
        if (!$npmItem['path']) {
            throw new Modules_NodeManagerPm2_Exception('npm was not found. Install Plesk Node.js support or configure the npm binary path first.');
        }

        $npm = $npmItem['path'];
        $env = [
            'PATH' => dirname($npm) . ':' . implode(':', self::detectedPathEntries()),
            'NPM_CONFIG_UPDATE_NOTIFIER' => 'false',
            'NPM_CONFIG_FUND' => 'false',
        ];

        try {
            Modules_NodeManagerPm2_Logger::info('Running PM2 install helper.', [
                'npm' => $npm,
                'path' => $env['PATH'],
            ]);
            $result = $this->runner->runSbin('pm2-helper', ['install', $npm], $env, '');
            $result->assertOk('Unable to install or update PM2');
        } catch (Modules_NodeManagerPm2_Exception $e) {
            Modules_NodeManagerPm2_Logger::error('PM2 install helper failed.', ['exception' => $e]);
            throw new Modules_NodeManagerPm2_Exception('PM2 installation failed: ' . $e->getMessage());
        } catch (Exception $e) {
            Modules_NodeManagerPm2_Logger::error('PM2 install helper failed unexpectedly.', ['exception' => $e]);
            throw new Modules_NodeManagerPm2_Exception('PM2 installation failed: ' . $e->getMessage());
        }

        $pm2 = $this->detectBinary('pm2', Modules_NodeManagerPm2_Config::get('pm2Binary', 'pm2'));
        $node = $this->detectBinary('node', Modules_NodeManagerPm2_Config::get('nodeBinary', 'node'));
        if ($pm2['path']) {
            Modules_NodeManagerPm2_Config::set('pm2Binary', $pm2['path']);
        }
        Modules_NodeManagerPm2_Config::set('npmBinary', $npm);
        if ($node['path']) {
            Modules_NodeManagerPm2_Config::set('nodeBinary', $node['path']);
        }
        if (!$pm2['path']) {
            Modules_NodeManagerPm2_Logger::error('PM2 install completed but pm2 binary was not detected.', [
                'stdout' => $result->stdout,
                'stderr' => $result->stderr,
                'detectedPaths' => self::detectedPathEntries(),
            ]);
            throw new Modules_NodeManagerPm2_Exception('PM2 install command completed, but the pm2 binary was not detected in the Plesk Node.js paths. Output: ' . trim($result->stdout . ' ' . $result->stderr));
        }

        Modules_NodeManagerPm2_Logger::info('PM2 install completed.', [
            'npm' => $npm,
            'pm2' => $pm2['path'],
            'stdout' => $result->stdout,
            'stderr' => $result->stderr,
        ]);

        return trim($result->stdout . "\n" . $result->stderr);
    }

    public static function pm2Invocation()
    {
        $pm2 = self::detectExecutable('pm2', Modules_NodeManagerPm2_Config::get('pm2Binary', 'pm2'));
        $node = self::detectExecutable('node', Modules_NodeManagerPm2_Config::get('nodeBinary', 'node'));

        if ($node['path'] && $pm2['path']) {
            return [
                'command' => $node['path'],
                'argsPrefix' => [$pm2['path']],
                'pm2' => $pm2['path'],
                'node' => $node['path'],
                'mode' => 'node-launcher',
            ];
        }

        return [
            'command' => Modules_NodeManagerPm2_Config::get('pm2Binary', 'pm2'),
            'argsPrefix' => [],
            'pm2' => $pm2['path'],
            'node' => $node['path'],
            'mode' => 'direct',
        ];
    }

    public function applyDetectedPaths()
    {
        foreach ([
            'nodeBinary' => 'node',
            'npmBinary' => 'npm',
            'pm2Binary' => 'pm2',
            'gitBinary' => 'git',
        ] as $setting => $binary) {
            $detected = $this->detectBinary($binary, Modules_NodeManagerPm2_Config::get($setting, $binary));
            if ($detected['path']) {
                Modules_NodeManagerPm2_Config::set($setting, $detected['path']);
            }
        }

        $paths = array_unique(array_merge(
            explode(':', Modules_NodeManagerPm2_Config::get('extraPath', '')),
            self::detectedPathEntries()
        ));
        $paths = array_values(array_filter($paths, function ($path) {
            return $path !== '' && is_dir($path);
        }));
        Modules_NodeManagerPm2_Config::set('extraPath', implode(':', $paths));

        return Modules_NodeManagerPm2_Config::all();
    }

    public static function detectedPathEntries()
    {
        $paths = ['/usr/local/bin', '/usr/bin', '/bin', '/opt/plesk/node/bin'];
        foreach (glob('/opt/plesk/node/*/bin', GLOB_ONLYDIR) ?: [] as $path) {
            $paths[] = $path;
        }
        foreach (glob('/opt/plesk/nodejs/*/bin', GLOB_ONLYDIR) ?: [] as $path) {
            $paths[] = $path;
        }

        return array_values(array_unique(array_filter($paths, function ($path) {
            return is_dir($path);
        })));
    }

    private function runtimeItem($domain, $setting, $binary, $args)
    {
        $configured = Modules_NodeManagerPm2_Config::get($setting, $binary);
        $detected = $this->detectBinary($binary, $configured);
        $commands = array_values(array_unique(array_filter([$configured, $detected['path'], $binary])));
        $lastError = null;

        foreach ($commands as $command) {
            $result = $this->version($domain, $command, $args);
            if ($result['available']) {
                $result['configured'] = $configured;
                $result['detected'] = $detected['path'];
                $result['path'] = $command;
                $result['setting'] = $setting;
                return $result;
            }
            $lastError = $result['error'];
        }

        return [
            'available' => false,
            'version' => null,
            'error' => $lastError ?: $binary . ' was not found.',
            'configured' => $configured,
            'detected' => $detected['path'],
            'path' => null,
            'setting' => $setting,
        ];
    }

    private function pm2RuntimeItem($domain)
    {
        $configured = Modules_NodeManagerPm2_Config::get('pm2Binary', 'pm2');
        $detected = $this->detectBinary('pm2', $configured);
        $invocation = self::pm2Invocation();
        $lastError = null;

        if ($invocation['command'] && $invocation['pm2']) {
            $result = $this->version($domain, $invocation['command'], array_merge($invocation['argsPrefix'], ['--version']));
            if ($result['available']) {
                $result['configured'] = $configured;
                $result['detected'] = $detected['path'];
                $result['path'] = $invocation['pm2'];
                $result['launcher'] = $invocation['node'];
                $result['setting'] = 'pm2Binary';
                return $result;
            }
            $lastError = $result['error'];
        }

        foreach (array_values(array_unique(array_filter([$configured, $detected['path'], 'pm2']))) as $command) {
            $result = $this->version($domain, $command, ['--version']);
            if ($result['available']) {
                $result['configured'] = $configured;
                $result['detected'] = $detected['path'];
                $result['path'] = $command;
                $result['launcher'] = null;
                $result['setting'] = 'pm2Binary';
                return $result;
            }
            $lastError = $result['error'];
        }

        return [
            'available' => false,
            'version' => null,
            'error' => $lastError ?: 'pm2 was not found.',
            'configured' => $configured,
            'detected' => $detected['path'],
            'path' => null,
            'launcher' => $invocation['node'],
            'setting' => 'pm2Binary',
        ];
    }

    private function detectBinary($binary, $configured)
    {
        return self::detectExecutable($binary, $configured);
    }

    private static function detectExecutable($binary, $configured)
    {
        $candidates = [];
        if ($configured !== null && $configured !== '' && $configured[0] === '/') {
            $candidates[] = $configured;
        }

        foreach (self::detectedPathEntries() as $path) {
            $candidates[] = rtrim($path, '/') . '/' . $binary;
        }

        foreach ($candidates as $candidate) {
            if (is_file($candidate) && is_executable($candidate)) {
                return ['path' => $candidate];
            }
        }

        return ['path' => null];
    }

    private function version($domain, $command, $args)
    {
        try {
            $result = $this->runner->runDomain($domain, $domain->getHomePath(), $command, $args, [], '', 20);
            if ($result->code !== 0) {
                return ['available' => false, 'version' => null, 'error' => trim($result->stderr . ' ' . $result->stdout)];
            }
            return ['available' => true, 'version' => trim($result->stdout), 'error' => null];
        } catch (Exception $e) {
            return ['available' => false, 'version' => null, 'error' => $e->getMessage()];
        }
    }
}