FlashPanel

Supervisor ​

Overview ​

Supervisor is a process control system for Linux. It keeps processes running and automatically restarts them if they stop unexpectedly. You can use it to run queue workers, websockets, laravel-echo-server, and other long-running processes. FlashPanel uses Supervisor to manage these processes and keep them running reliably.

Which tool should I use?

  • Node.js applications: use PM2.
  • Programs that should run as a system service and start with the server: use Service.
  • Commands that run on a schedule (every minute, every day…) rather than continuously: use CronJob.

Supervisor configuration ​

You can set up a Supervisor process via the server's Supervisor menu. Steps:

  1. Select the server, click the Supervisor menu, then click the Create button

  2. In the New Supervisor dialog, fill in the process information:

    • Name: Name of the program, for example queue-worker. Lowercase letters, numbers, dashes and underscores only, up to 32 characters. It is also the name of the config file in /etc/supervisor/conf.d and cannot be changed later (use Clone and Delete to rename)
    • Description (Optional): Brief description of the process
    • Command: Command to run. For example: php artisan queue:work. If you use a relative path like this one, set Directory to the website folder (e.g. /home/flashpanel/example.com), or use the full path: php /home/flashpanel/example.com/artisan queue:work
    • User: System user that runs the command, flashpanel by default
    • Directory (Optional): Directory to run the command from; pick a suggestion. Leave it blank if the command already uses full paths
    • Number Processes: Number of instances of the process to run in parallel
    • Start Seconds: The total number of seconds the program needs to stay running to be considered successfully started

  3. Click Save

The table is read directly from the server every time you open the page: it lists every program in /etc/supervisor/conf.d, including programs you created over SSH, and Refresh reads it again. FlashPanel does not keep a copy of the configuration, so what you see is what is on the server. The Status column shows the state read from Supervisor on the server, refreshed every 30 seconds while the page is open (click Refresh to read it right away; the time of the last read is shown next to the button):

  • Running: All processes are running. With Number Processes above 1, the column also shows how many are running, for example 2/2
  • Starting, Stopping: The process is changing state
  • Retrying: The process exited before Start Seconds and Supervisor is starting it again
  • Stopped: The process was stopped
  • Exited: The process exited after starting successfully
  • Failed to start: Supervisor gave up after several failed attempts. Check Show Log to find out why
  • Not loaded: Supervisor on the server does not have this process, for example when installing the config failed. Edit and save it to install the config again

When a group has several processes in different states, the most serious state is shown. Hover over the status to see the state of each process.

Click the Name, Description, User or Number Processes column header to sort by that column.

Search and filter ​

The bar above the table helps you find processes quickly on a busy server:

  • Type in the Search box to filter by name, description, command, directory or user.
  • Click Status and pick Running, Failed (includes Failed to start and Retrying), Stopped (includes Exited) or Not loaded. Each option shows how many processes it holds, so failing processes stand out right away.
  • Click Owner to show only Server processes or the processes of one website.
  • Click User to filter by the user the process runs as.
  • Click Config and pick Editable or Read-only to separate processes managed by FlashPanel from those with a hand-written config file.
  • Filters combine. The active values are shown on the filter button. Click Clear filters to reset the search box and every filter.

The buttons at the end of the row:

  • Start, Stop, Restart: Control the process. The command runs in the background and is shown in Events; when it finishes, the status is read again from the server. If the process fails to start, the event shows the error from Supervisor. Start is greyed out while all processes are running and Stop is greyed out while none is running. All buttons are greyed out while the process is being installed, deleted or changing state, or when it is Not loaded.
  • Show Log: View the process log output. The log opens in a floating window that you can move, resize or minimize, with the colors written by the program kept. Choose how many Lines to show, turn on Auto refresh to reload every 5 seconds, or click the refresh button to reload once.
  • The ⋮ menu:
    • Edit: Edit the process configuration. The config file is rewritten from the form; the processes restart only when their run settings change (changing the description alone does not restart them). Directives you added to the file by hand, such as environment, are kept
    • Clone: Create a new process from the existing configuration, under a new name
    • Clear Log: Clear the process log file
    • Delete: Remove the Supervisor configuration (click Confirm to finish)

Control several processes at once ​

  1. Tick the checkbox at the start of each row you want to control, or the checkbox in the table header to select every visible row. A bar showing the number of selected processes appears at the bottom of the screen.
  2. Click one of the buttons on that bar: Start, Stop, Restart, Clear Log or Delete Selected. Hover over a button to see its name. Click the close button on the left to deselect everything.

Each button acts only on the selected processes it applies to, just like the button on a single row: Start skips processes that are fully running, Stop skips processes that are not running, Clear Log skips processes without a log file and Delete Selected skips processes with a hand-written config. A button that applies to none of the selected processes is not shown. The commands run in the background and appear in Events; if some could not be sent, one notification lists the failed processes.

Delete Selected opens a confirmation dialog listing the processes that will be deleted. Processes hidden by a filter are deselected automatically, so bulk actions never touch rows you cannot see.

Website processes

Processes created on a website's Supervisor page also appear here, and the Site column shows the website they belong to. When you edit one, User and Directory are locked because a website process always runs as the website's user inside the website's directory.

Configs written by hand

A config file that holds several programs, or whose program name differs from the file name, is shown with a lock icon next to its name. You can start, stop, restart it and read its log, but Edit and Delete are disabled: change it over SSH instead. A program whose config does not write its output to a file has no log to show.

Log files ​

FlashPanel automatically configures each Supervisor process to write its own log file. The log files are stored in the /home/flashpanel/.flashpanel/ directory and are named <name>.log, where <name> is the value in the table's Name column. If the process runs as the root user, the log file is stored in /root/.flashpanel/. Processes created before this version keep their daemon-<ID>.log file; the path is always read from the config file, so Show Log finds it either way.

Processes of a website always write their log to /root/.flashpanel/<name>.log, whatever user they run as. Use Show Log to read it.

WARNING

If you use the user isolation feature of FlashPanel, the log file is in the .flashpanel folder inside the home directory of the user selected in the User field (for example /home/<username>/.flashpanel/).