{"id":50615512,"url":"https://github.com/ghostcompiler/supervisor-manager","last_synced_at":"2026-06-06T08:01:13.257Z","repository":{"id":356102983,"uuid":"1230064597","full_name":"ghostcompiler/supervisor-manager","owner":"ghostcompiler","description":"Plesk extension to manage Supervisor programs with admin, reseller, and customer scoped access.","archived":false,"fork":false,"pushed_at":"2026-05-06T15:38:25.000Z","size":6561,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T17:35:29.694Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ghostcompiler.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-05T16:35:42.000Z","updated_at":"2026-05-06T15:40:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ghostcompiler/supervisor-manager","commit_stats":null,"previous_names":["ghostcompiler/supervisor-manager"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ghostcompiler/supervisor-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghostcompiler%2Fsupervisor-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghostcompiler%2Fsupervisor-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghostcompiler%2Fsupervisor-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghostcompiler%2Fsupervisor-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ghostcompiler","download_url":"https://codeload.github.com/ghostcompiler/supervisor-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghostcompiler%2Fsupervisor-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33973868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-06T08:01:12.623Z","updated_at":"2026-06-06T08:01:13.251Z","avatar_url":"https://github.com/ghostcompiler.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://res.cloudinary.com/djgvfl1tv/image/upload/v1780666791/logo_mqnqn4.png\" alt=\"Cloudflare Pro\" width=\"180\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSupervisor Manager for Plesk\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Manage Supervisor processes from Plesk with admin, reseller, and customer scoped access.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Plesk-Extension-52BBE6?style=for-the-badge\u0026logo=plesk\u0026logoColor=white\" alt=\"Plesk Extension\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Supervisor-Process%20Manager-0F172A?style=for-the-badge\" alt=\"Supervisor Process Manager\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PHP-8.1%2B-777BB4?style=for-the-badge\u0026logo=php\u0026logoColor=white\" alt=\"PHP 8.1+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Live%20Logs-Ready-16A34A?style=for-the-badge\" alt=\"Live Logs\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Built%20By-Ghost%20Compiler-0F172A?style=for-the-badge\" alt=\"Ghost Compiler\"\u003e\n\u003c/p\u003e\n\n---\n\n## Overview\n\nSupervisor Manager is a Plesk extension for creating and managing Supervisor programs directly from the Plesk interface.\n\nIt is built for hosting panels where admins need to run background commands for individual domains while keeping customers locked to their own domain scope. It can manage PHP workers, Node workers, queue consumers, schedulers, websocket servers, custom scripts, and other long-running services.\n\n## Creator\n\n- **Name:** Ghost Compiler\n- **Email:** [hello@ghostcompiler.in](mailto:hello@ghostcompiler.in)\n- **GitHub:** [ghostcompiler/supervisor-manager](https://github.com/ghostcompiler/supervisor-manager)\n- **Profile:** [github.com/ghostcompiler](https://github.com/ghostcompiler)\n\n## Use Cases\n\n- Run queue workers and background consumers.\n- Run Node, PHP, Python, or shell-based worker processes.\n- Manage websocket servers, schedulers, bots, daemons, and custom long-running commands.\n- Let customers restart only the processes assigned to their domains.\n- Give admins a single Plesk page for status, config generation, restart controls, and live logs.\n- Keep Supervisor config files generated consistently under `/etc/supervisor/conf.d`.\n\n## Screenshots\n\nOpen the full GitHub Pages documentation site:\n\n[Supervisor Manager Documentation](https://ghostcompiler.github.io/supervisor-manager/)\n\n\u003ca href=\"docs/screenshots/home_dark.png\"\u003e\n  \u003cimg src=\"docs/screenshots/home_dark.png\" alt=\"Supervisor Manager dashboard dark theme\"\u003e\n\u003c/a\u003e\n\n\u003cdetails\u003e\n\n### 1. Dashboard\n\n![Supervisor Manager dashboard dark theme](docs/screenshots/home_dark.png)\n![Supervisor Manager dashboard light theme](docs/screenshots/home_light.png)\n\n### 2. Add Program\n\n![Add Supervisor program dark theme](docs/screenshots/add_dark.png)\n![Add Supervisor program light theme](docs/screenshots/add_light.png)\n\n### 3. Live Logs\n\n![Live log preview dark theme](docs/screenshots/log_dark.png)\n![Live log preview light theme](docs/screenshots/log_light.png)\n\n\u003c/details\u003e\n\n## Features\n\n- Admin dashboard for all managed Supervisor programs.\n- Customer and reseller scoped access by assigned Plesk domain.\n- Add, edit, delete, start, stop, restart, and regenerate config.\n- Live log preview with pause/resume and 120/300/500 line views.\n- Automatic Supervisor config generation.\n- Project root locking so users cannot escape their domain area.\n- Project root validation for domain-owned applications.\n- Runtime PATH handling for Plesk PHP, Plesk Node.js, and system binaries.\n- Generated config and log paths shown in the UI.\n- One-click Supervisor install on supported Linux distributions.\n\n## Requirements\n\n- Plesk Onyx or Obsidian on Linux.\n- PHP available to Plesk admin runtime.\n- Supervisor installed, or an OS supported by the install button.\n- Required runtime installed for the command you want to run, such as PHP, Node.js, Python, or another CLI binary.\n\nSupported install detection includes:\n\n- Ubuntu / Debian\n- AlmaLinux / Rocky / RHEL / CentOS / Fedora\n\n## Installation\n\nInstall the latest runner-built package directly from GitHub:\n\n```sh\nplesk bin extension --install-url https://github.com/ghostcompiler/supervisor-manager/releases/download/latest/supervisor-manager.zip\n```\n\nThis URL points to the rolling `latest` release asset. The **Package Latest** workflow rebuilds `supervisor-manager.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.\n\nPinned version installs are also available after publishing a versioned release:\n\n```sh\nplesk bin extension --install-url https://github.com/ghostcompiler/supervisor-manager/releases/download/v1.0.3/supervisor-manager-1.0.3.zip\n```\n\nBuild the extension ZIP:\n\n```sh\nmkdir -p build\nCOPYFILE_DISABLE=1 zip -r build/supervisor-manager-1.0.3.zip meta.xml DESCRIPTION.md CHANGES.md README.md htdocs plib sbin -x '*.DS_Store' -x '__MACOSX/*'\n```\n\nInstall through Plesk CLI:\n\n```sh\nplesk bin extension --install build/supervisor-manager-1.0.3.zip\n```\n\nOr install through Plesk UI:\n\n1. Open **Plesk Admin**.\n2. Go to **Extensions**.\n3. Click **Upload Extension**.\n4. Upload `build/supervisor-manager-1.0.3.zip`.\n5. Open **Supervisor** from the Plesk sidebar.\n\n## Version 1.0.3\n\nVersion 1.0.3 improves Supervisor runtime setup, domain PHP detection, and log handling. It adds service health diagnostics with a repair action, generates domain-scoped Supervisor program names, resolves `php` through the selected Plesk domain PHP handler, and adds copy/clear controls for live logs.\n\nAfter installing:\n\n1. Open **Supervisor** from Plesk.\n2. Use **Repair Supervisor** if the service or socket needs setup.\n3. Regenerate existing program configs so domain PHP paths and scoped names are written.\n4. Restart affected programs from the extension.\n5. Use **Copy Log** or **Clear Log** from the logs page when troubleshooting.\n\n## How It Works\n\nWhen an authorized user saves a program, the extension:\n\n1. Validates the selected domain.\n2. Locks the project root to the selected domain area.\n3. Generates a Supervisor config file.\n4. Writes the config to `/etc/supervisor/conf.d`.\n5. Runs `supervisorctl reread` and `supervisorctl update`.\n6. Shows status, config path, log path, and live logs in Plesk.\n\n## Adding a Program\n\nExample queue worker:\n\n```text\nSupervisor Program Name: queue-worker\nDisplay Name: Queue Worker\nAssigned Domain: example.com\nCommand: php artisan queue:work --sleep=3 --tries=3\nProject Root: /var/www/vhosts/example.com/app\nStart on boot: enabled\nRestart if it exits: enabled\nEnabled: enabled\n```\n\nExample Node worker:\n\n```text\nSupervisor Program Name: realtime-worker\nDisplay Name: Realtime Worker\nAssigned Domain: example.com\nCommand: npm run worker\nProject Root: /var/www/vhosts/example.com/realtime-app\n```\n\nExample custom script:\n\n```text\nSupervisor Program Name: importer\nDisplay Name: Product Importer\nAssigned Domain: example.com\nCommand: /usr/bin/python3 worker.py\nProject Root: /var/www/vhosts/example.com/importer\n```\n\nSet **Project Root** to the application folder where the command should run. For Laravel commands, this is usually the folder containing `artisan`. For Node.js commands, this is usually the folder containing `package.json`.\n\n## Generated Files\n\nSupervisor configs:\n\n```sh\n/etc/supervisor/conf.d/plesk-*.conf\n```\n\nRHEL-style fallback path:\n\n```sh\n/etc/supervisord.d/plesk-*.conf\n```\n\nProgram logs:\n\n```sh\n/var/log/supervisor/plesk/*.log\n```\n\nExtension data:\n\n```sh\n/usr/local/psa/var/modules/supervisor-manager/data/programs.json\n```\n\nPrivileged helper:\n\n```sh\n/usr/local/psa/admin/sbin/modules/supervisor-manager/supervisor-manager\n```\n\n## Security Model\n\n- Admins can create, edit, delete, and regenerate all programs.\n- Customers and resellers can only see programs assigned to domains they can access.\n- Customer and reseller access is controlled by Plesk service plan permissions.\n- If Plesk delays exposing custom access/manage permission values after a plan change, a non-zero **Maximum Supervisor programs** limit is treated as a guarded activation fallback for domains the user already owns or can access.\n- Project roots are locked to the selected domain area.\n- Users cannot use `../` style path escapes to reach another domain.\n- Server-level writes are performed through the Plesk `sbin` helper.\n- The `sbin` helper revalidates config paths, log paths, process users, and allowed project roots before touching server files.\n- Managed commands run as the selected domain system user. Only grant **Manage Supervisor programs** to users who are trusted to run commands for that subscription.\n\n## Service Plan Access\n\nSupervisor Manager adds permissions to Plesk service plans and subscriptions. Keep them disabled by default, then enable only what each reseller or customer should be allowed to do.\n\nAvailable permissions:\n\n- **Supervisor Manager access**: allows the user to open the extension and view assigned programs.\n- **Manage Supervisor programs**: allows creating, editing, deleting, and regenerating configs for enabled domains.\n- **Control Supervisor programs**: allows start, stop, and restart actions.\n- **View Supervisor logs**: allows opening the live log preview.\n\nAvailable limit:\n\n- **Maximum Supervisor programs**: caps how many programs can be created per subscription. Use `0` to prevent customer-created programs, a positive number for a fixed cap, or `-1` for unlimited.\n\nAvoid unlimited process counts for shared-hosting customers unless they are trusted. Background programs can consume CPU, RAM, and ports just like commands run over SSH.\n\nAccess is checked in three layers:\n\n1. The logged-in user must have access to the Plesk domain.\n2. The domain subscription must have the matching Supervisor Manager permission enabled.\n3. The posted program must belong to that exact domain ID, not a parent domain or a similar subdomain.\n\nAfter changing an existing service plan, sync the affected subscriptions in Plesk. Customized or locked subscriptions may keep their old permission values until they are synced or adjusted directly.\n\nThe extension always registers its Plesk sidebar and domain buttons so service plan changes can appear without waiting for a new domain event. Security is still enforced in the controller after the button is clicked.\n\nDomain buttons are normalized to `site_id`, because Plesk context parameters can include `dom_id` for the subscription/webspace and `site_id` for the exact domain. Supervisor Manager uses the exact domain ID for filtering and actions.\n\n## Live Logs\n\nThe log page opens in a new tab and provides:\n\n- Auto refresh every 2.5 seconds.\n- Pause and resume.\n- Last update timestamp.\n- 120, 300, and 500 line views.\n- Direct reading from `/var/log/supervisor/plesk/*.log`.\n\n## Useful Commands\n\nCheck Supervisor:\n\n```sh\nsupervisorctl status\n```\n\nReread generated configs:\n\n```sh\nsupervisorctl reread\nsupervisorctl update\n```\n\nCheck generated files:\n\n```sh\nls -lah /etc/supervisor/conf.d/\nls -lah /var/log/supervisor/plesk/\n```\n\nInstall Supervisor on Ubuntu manually:\n\n```sh\nsudo DEBIAN_FRONTEND=noninteractive apt-get update\nsudo DEBIAN_FRONTEND=noninteractive apt-get install -y supervisor\nsudo systemctl enable --now supervisor\n```\n\nCheck a runtime binary:\n\n```sh\nwhich php\nwhich node\nwhich python3\n```\n\n## Troubleshooting\n\n### Config is saved but process is BACKOFF\n\nOpen **Logs**. The most common causes are:\n\n- Wrong project root.\n- Missing command runtime, such as PHP, Node.js, or Python.\n- Missing application file, such as `artisan`, `package.json`, or the script passed to the command.\n- Port already in use.\n- Command exits immediately.\n\n### Command cannot find an application file\n\nSet **Project Root** to the folder where the command normally runs over SSH.\n\n```sh\ncd /var/www/vhosts/example.com/app\nls -lah\n```\n\nFor example:\n\n- Laravel commands usually run from the folder containing `artisan`.\n- Node.js commands usually run from the folder containing `package.json`.\n- Python or shell workers usually run from the folder containing the script file.\n\n### Runtime command not found\n\nInstall the missing runtime or use the full binary path in the command. Examples:\n\n```sh\nwhich php\nwhich node\nwhich python3\n```\n\n### Port already in use\n\nIf the managed application binds to a port and the port is already busy, stop the duplicate process or change the application port.\n\n### Save or delete does not show a status message\n\nThe extension returns to the manager page and shows a success or error message at the top. If the browser is still on the form page, refresh once and check the manager page again.\n\n## Development\n\nValidate PHP syntax:\n\n```sh\nfind . -name '*.php' -o -name '*.phtml' | sort | xargs -n1 php -l\n```\n\nPackage:\n\n```sh\nmkdir -p build\nCOPYFILE_DISABLE=1 zip -r build/supervisor-manager-1.0.3.zip meta.xml DESCRIPTION.md CHANGES.md README.md htdocs plib sbin -x '*.DS_Store' -x '__MACOSX/*'\n```\n\n## Release Automation\n\nGitHub Actions handles packaging and release assets:\n\n- `CI` runs on every push and pull request.\n- `CI` validates PHP syntax, validates `meta.xml`, builds the ZIP, tests the ZIP, and uploads it as a workflow artifact.\n- `Package Latest` runs on every push to `main` and can be started manually.\n- `Package Latest` moves the rolling `latest` tag to the current commit and uploads `supervisor-manager.zip` to that release.\n- `Release` runs when a tag like `v1.0.3` is pushed, or when started manually.\n- `Release` requires the tag version to match `meta.xml`.\n- `Release` uploads versioned assets like `supervisor-manager-1.0.3.zip` for pinned installs.\n\nRefresh the rolling latest installer from the current `main` branch:\n\n```sh\ngit push origin main\n```\n\nThen install the newest runner-built package:\n\n```sh\nplesk bin extension --install-url https://github.com/ghostcompiler/supervisor-manager/releases/download/latest/supervisor-manager.zip\n```\n\nCreate a release:\n\n```sh\ngit tag v1.0.3\ngit push origin v1.0.3\n```\n\nAfter the release workflow finishes, the pinned install command works:\n\n```sh\nplesk bin extension --install-url https://github.com/ghostcompiler/supervisor-manager/releases/download/v1.0.3/supervisor-manager-1.0.3.zip\n```\n\nInstall locally on Plesk:\n\n```sh\nplesk bin extension --install build/supervisor-manager-1.0.3.zip\n```\n\n## License\n\nPrivate project. Update this section before publishing publicly.\n\n\u003cp align=\"center\"\u003e\n  Proudly developed by \u003ca href=\"https://github.com/ghostcompiler\"\u003eGhost Compiler\u003c/a\u003e.\n\u003c/p\u003e\n\n\n## Development Environment\n\nBuilt using **ServBay**\n\n\u003cp align=\"left\"\u003e\n  \u003cimg src=\"https://res.cloudinary.com/djgvfl1tv/image/upload/v1780667063/servbay_edc7jz.png\" alt=\"ServBay\" width=\"120\"\u003e\n\u003c/p\u003e\n\n- Mac M4 Tested\n- macOS Apple Silicon\n- Powered by ServBay\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghostcompiler%2Fsupervisor-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fghostcompiler%2Fsupervisor-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghostcompiler%2Fsupervisor-manager/lists"}