Plesk Extension

Supervisor Manager

Create, repair, monitor, and troubleshoot Supervisor programs from Plesk with domain-scoped access, correct Plesk PHP resolution, and live log controls.

Install Latest View Screenshots Releases
AccessAdmin, reseller, customer
RuntimePlesk PHP and Node PATH
LogsLive, copy, clear
Configs/etc/supervisor/conf.d

Built for hosted application workers.

Supervisor Manager keeps process control close to Plesk domains, so background commands can be managed without handing every user a server shell.

1

Domain scoped

Programs are assigned to exact Plesk domain IDs. Customers and resellers only see programs they are allowed to access.

2

Correct PHP

Generated configs resolve php through the selected domain PHP handler, such as Plesk PHP 8.4.

3

Service repair

Admin diagnostics detect broken Supervisor sockets and provide a repair action for supported Linux systems.

4

Safe generation

Project roots, config paths, log paths, process users, and allowed roots are validated in the privileged helper.

5

Live logs

Open logs in a focused page, pause refresh, change line count, copy output, or truncate the managed log file.

6

Clean uninstall

Uninstall hooks remove generated Supervisor configs, managed logs, and extension data created by the extension.

Designed for the messy middle of hosting.

Background workers usually live between application code, domain permissions, Plesk PHP handlers, Supervisor service state, and server logs. Supervisor Manager brings those moving parts into one Plesk workflow so admins can fix runtime problems without hunting across five screens.

RepairDetect and repair common Supervisor socket and service setup problems.
RegenerateRewrite configs after PHP handler, project root, command, or domain changes.
ObserveTail logs live, copy the exact failure, clear noise, then restart with fresh output.

What gets generated?

Each program receives a managed config with a scoped program name, application directory, domain PHP-aware PATH, process user, restart policy, and a dedicated log file.

[program:example.com-queue-worker]
command=/usr/bin/env php artisan queue:work
directory=/var/www/vhosts/example.com/app
environment=PATH="/opt/plesk/php/8.4/bin:..."
user=example-user
stdout_logfile=/var/log/supervisor/plesk/example.com-queue-worker.log

Light and dark theme screenshots.

Pick a screen, then drag the handle to compare the Plesk light and dark appearances.

Supervisor Manager dashboard dark theme Supervisor Manager dashboard light theme

Install or update.

Use the rolling latest package for most servers, or pin a versioned release when you need repeatable deployments.

Latest package

Install the newest GitHub Actions-built package directly through Plesk.

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

Pinned release

Use a fixed release asset when you want a known version.

plesk bin extension --install-url https://github.com/ghostcompiler/supervisor-manager/releases/download/v1.0.3/supervisor-manager-1.0.3.zip

Manual upload

Download the zip, then open Plesk Admin, go to Extensions, choose Upload Extension, and select the package.

supervisor-manager-1.0.3.zip

Requirements

  • Plesk Onyx or Obsidian on Linux.
  • Supervisor package installed, or a supported OS for automatic setup.
  • Runtime installed for the command: PHP, Node.js, Python, or another CLI.
  • Trusted users for command management permissions.

How to use it.

The normal workflow is create, generate, start, and watch logs. Existing programs can be regenerated after runtime or PHP-handler changes.

Enable access

  1. Open the Plesk service plan or subscription.
  2. Enable Supervisor Manager access and specific manage/control/log permissions.
  3. Set Maximum Supervisor programs to a positive number or unlimited for trusted users.

Add a program

  1. Choose a domain from Supervisor Manager or from the domain card.
  2. Use a long-running command such as php artisan queue:work.
  3. Set Project Root to the folder containing artisan, package.json, or your script.

Operate safely

  1. Generate config after saving edits.
  2. Use Start, Stop, and Restart from the dashboard.
  3. Open Logs to pause, copy, or clear managed log output.

Deployment patterns.

Use these recipes as starting points for common Laravel, Inertia, Next.js, and Node deployments. Commands run as the selected domain system user and are locked to that domain’s allowed project roots.

Laravel queue worker

Best for jobs, notifications, imports, mail, and slow background work.

PHP

Program fields

Supervisor Program Name: queue-worker
Command: php artisan queue:work --sleep=3 --tries=3 --timeout=120
Project Root: /var/www/vhosts/example.com/app
Start on boot: enabled
Restart if it exits: enabled

Generated config shape

[program:example.com-queue-worker]
command=/usr/bin/env php artisan queue:work --sleep=3 --tries=3 --timeout=120
directory=/var/www/vhosts/example.com/app
environment=PATH="/opt/plesk/php/8.4/bin:..."
user=example-user
autorestart=true
  • Set the Plesk domain PHP version first, then regenerate config.
  • Use the folder containing artisan, not public.
  • Use Logs to catch missing extensions, database errors, or permission errors.

Laravel Inertia SSR

Keeps Inertia server-side rendering alive as a supervised process.

SSR

Program fields

Supervisor Program Name: inertia-ssr
Command: php artisan inertia:start-ssr
Project Root: /var/www/vhosts/example.com/app
Start on boot: enabled
Restart if it exits: enabled

Before starting

cd /var/www/vhosts/example.com/app
npm install
npm run build
php artisan config:cache
  • Supervisor Manager adds Plesk Node paths to PATH when Node is installed.
  • If Logs show Node missing, install/enable Node.js in Plesk and regenerate config.
  • Make sure your Laravel SSR settings use the expected host and port.

Next.js production server

Runs a built Next.js app behind Plesk, nginx, or a proxy rule.

Node

Program fields

Supervisor Program Name: next-web
Command: npm run start -- --hostname 127.0.0.1 --port 3000
Project Root: /var/www/vhosts/example.com/next-app
Start on boot: enabled
Restart if it exits: enabled

Package script

{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}
  • Build the app before starting the Supervisor program.
  • Bind to 127.0.0.1 unless the app intentionally needs public network access.
  • Use Plesk proxy rules or nginx config to route traffic to the selected port.

Laravel scheduler loop

Useful when cron is not enough or you want Supervisor to keep a scheduler loop alive.

Cron-like

Program fields

Supervisor Program Name: scheduler
Command: php artisan schedule:work
Project Root: /var/www/vhosts/example.com/app
Start on boot: enabled
Restart if it exits: enabled

Alternative

# Use Plesk Scheduled Tasks for classic every-minute cron:
php /var/www/vhosts/example.com/app/artisan schedule:run
  • Use only one scheduler approach per app unless you intentionally need both.
  • Prefer Plesk Scheduled Tasks for simple cron-style scheduling.
  • Use Supervisor for long-running scheduler workers that must restart automatically.

Node queue or websocket worker

For websocket servers, queue consumers, bots, and long-running Node processes.

Worker

Program fields

Supervisor Program Name: realtime-worker
Command: npm run worker
Project Root: /var/www/vhosts/example.com/realtime-app
Start on boot: enabled
Restart if it exits: enabled

Direct script

Command: node server.js
  • Keep the command in the folder containing package.json.
  • Install dependencies as the domain user when possible.
  • Check Logs for missing environment variables and port conflicts.

Custom Python or shell worker

Runs imports, crawlers, webhooks, or custom daemons from the domain space.

Custom

Program fields

Supervisor Program Name: importer
Command: /usr/bin/python3 worker.py
Project Root: /var/www/vhosts/example.com/importer
Start on boot: enabled
Restart if it exits: enabled

Shell script

Command: /bin/bash worker.sh
  • Use absolute paths for runtimes that are outside Plesk-managed PHP or Node.
  • Write logs to stdout or stderr so Supervisor can capture them.
  • Avoid commands that exit immediately; Supervisor will keep restarting them.
When should you regenerate config? Regenerate after changing the command, project root, domain PHP version, Node version, or after upgrading the extension. Regeneration rewrites the managed config and keeps the displayed command aligned with the actual Supervisor program.

Quick field guide.

These fields are intentionally simple, but they control how Supervisor runs your program.

Supervisor Program Name

Use a short stable name such as queue-worker, inertia-ssr, or next-web. The extension generates a domain-scoped internal Supervisor name so two domains can both use queue-worker.

Command

Enter the command exactly as a developer would run it from the project root. For Plesk PHP domains, php resolves to the selected domain PHP handler after config generation.

Project Root

Use the app root, not necessarily the document root. Laravel usually needs the folder containing artisan. Node apps usually need the folder containing package.json.

Restart Options

Enable start on boot and restart if it exits for real workers. Leave them off while testing commands that may fail repeatedly until dependencies are ready.

Operational checklist.

Use this order when a new worker does not start cleanly.

Verify the domain runtime

  1. Open the domain card in Plesk and confirm the PHP or Node version.
  2. Regenerate the config after runtime changes.
  3. Check the generated config PATH starts with the expected runtime.

Run once over SSH

  1. Switch to the domain system user when possible.
  2. Change into the project root.
  3. Run the exact command and fix missing dependencies first.

Start in Supervisor

  1. Click Generate Config.
  2. Click Start or Restart.
  3. Open Logs, clear old output, restart again, and copy the fresh error if needed.

Compact examples.

For quick copying, these are the minimal field sets for common program types.

Laravel queue worker

Supervisor Program Name: queue-worker
Command: php artisan queue:work --sleep=3 --tries=3
Project Root: /var/www/vhosts/example.com/app

Inertia SSR

Supervisor Program Name: ssr
Command: php artisan inertia:start-ssr
Project Root: /var/www/vhosts/example.com/app

Next.js app

Supervisor Program Name: next-web
Command: npm run start -- --hostname 127.0.0.1 --port 3000
Project Root: /var/www/vhosts/example.com/next-app

Node worker

Supervisor Program Name: realtime-worker
Command: npm run worker
Project Root: /var/www/vhosts/example.com/realtime-app

Python worker

Supervisor Program Name: importer
Command: /usr/bin/python3 worker.py
Project Root: /var/www/vhosts/example.com/importer

Troubleshooting.

Most process issues come from wrong project roots, wrong runtime versions, missing service sockets, or commands that exit immediately.

Supervisor socket missing

When the dashboard shows Supervisor needs setup or unix:///var/run/supervisor.sock no such file, use Repair Supervisor as admin.

systemctl status supervisor
supervisorctl status

Wrong PHP version

Regenerate the config after changing the domain PHP handler. The generated PATH should begin with the selected Plesk PHP directory.

plesk db -N -B -e "select php_handler_id from hosting where dom_id = DOMAIN_ID"
cat /etc/supervisor/conf.d/plesk-*.conf

BACKOFF or FATAL

  • Open Logs and check the first application error.
  • Confirm the command stays running.
  • Confirm the project root contains the application entry file.
  • Check whether a port is already in use.

Laravel artisan not found

Use the Laravel project root, not the public document root.

/var/www/vhosts/example.com/app
# not
/var/www/vhosts/example.com/app/public

Logs are noisy

Use Clear Log to truncate the managed log file, then restart the program and copy the fresh output.

Uninstall cleanup

Generated configs with the Supervisor Manager header, managed logs, and extension data are cleaned on uninstall.

Generated files and commands.

These are the paths and commands most useful during server troubleshooting.

Generated paths

/etc/supervisor/conf.d/plesk-*.conf
/etc/supervisord.d/plesk-*.conf
/var/log/supervisor/plesk/*.log
/usr/local/psa/var/modules/supervisor-manager/data/programs.json

Supervisor commands

supervisorctl status
supervisorctl reread
supervisorctl update
systemctl restart supervisor

Runtime checks

which php
php -v
which node
node -v

Safe process commands

Supervisor is for long-running processes. Commands like php -v or node --version exit immediately and are rejected.