How to set up SuperVisor

To manage processors in Linux, there are initialization systems like systemd. If you need a simpler solution, a program that can manage the processes of your application, either in the system or in a Docker container. Such a program exists - it is supervisor. It is a functionally simple open-source process manager written in Python, which can be used to run as many copies of a process as needed and monitor their state. Below we will show you how to install and configure Supervisor using Ubuntu 20.04 as an example.

Installing supervisor

The easiest way to get the program is to install it from the official repositories. To do this, you need to run the command:

$ sudo apt install supervisor

If you want the program to run all the time, you need to add it to your autoloader and run it. Execute:

$ sudo systemctl enable supervisor --now

Next, you can view the status using the command:

$ sudo systemctl status supervisor

Configuration process

The configuration file is located at /etc/supervisor/supervisord.conf. This is also where the basic settings are located. It is better to use the /etc/supervisor/conf.d/ directory to configure running processes . The main configuration file can be left by default. Let's see how to create configuration files for programs. The syntax of a section for a single process looks like this:

variable name value

For each process it is minimally necessary to pass such variables for it to automatically start and recover after a crash:

• directory - working directory;
• command - command to start the process;
• user - user on behalf of which the process will be started;
• autostart - whether the process should be automatically started;
• autorestart - whether the process should be restarted;

However, there are many more settings available, here are some of them that will be discussed in this article:

• priority - priorityof the process to be started;
• environment - environment variables to be passed to the process;
• stdout_logfile - where to redirect the process stdout output;
• stderr_logfile - where to redirect the process stderr output;
• process_name - process name, with possibility to substitute copy number;
• numprocs - number of copies of the process to be started;
• startretries - number of attempts to start the program;
• redirect_stderr - redirect process error output to supervisor output;
• redirect_stdout - redirect process output to supervisor output.

For a better understanding and an example, let's execute a PHP script that will just hang in the background:

$ sudo vi /home/sergiy/program/process.php

<?php
echo "Started...";
while(true){
  sleep(5);
}

You can create a separate supervisor configuration file for the process. You can insert the configuration right at the end of the main configuration file, but it is better not to do that. It is better to create a separate configuration file for each program in /etc/supervisor/conf.d/ with the name *.conf. For example, for this program this file will look like this:

$ sudo vi /etc/supervisor/conf.d/process.conf

[program:process]


directory=/home/sergiy/program/


command=/usr/bin/php process.php


user=sergiy


autostart=true


autorestart=true

Then you need to restart supervisor, this can be done with systemctl:

$ sudo systemctl restart supervisor

Or with the supervisorctl utility:

$ sudo supervisorctl reload

You can also see the status of the configured processes using the command:

If the process is in RUNNING status, that's all good and it was started successfully. But in this case the process is running in a single instance, and quite often you need to run multiple copies of the same process. For this purpose we can use the process_name and numprocs parameters. The first allows you to modify the process name to contain the copy number, and the second allows you to specify how many copies should be run.

The process_name variable usually contains a python string formatting pattern that contains the program name and process number: %(program_name)s_%(process_num)02d. Here the variable name is in parentheses, followed by its type. For example, to run the same program in four threads, the configuration file should be set to this form:

$ sudo vi /etc/supervisor/conf.d/process.conf

[program:process]


directory=/home/sergiy/program/


command=/usr/bin/php process.php


user=sergiy


autostart=true


autorestart=true


process_name=%(program_name)s_%(process_num)02d


numprocs=4

Now we have to reload supervisorctl again and 4 processes will be started:

$ sudo supervisorctl status

At the same time it is possible to save all data output by the program to the log file. The parameters stdout_logfile and stderr_logfile are used for this purpose. For example, you can output the log file of its execution directly in the folder with the program.

$ sudo vi /etc/supervisor/conf.d/process.conf

[program:process]


directory=/home/sergiy/program/


command=/usr/bin/php process.php


user=sergiy


autostart=true


autorestart=true


process_name=%(program_name)s_%(process_num)02d


numprocs=4


stdout_logfile=/home/sergiy/program/process.log


stderr_logfile=/home/sergiy/program/process.log.error

After restarting the service, logs will appear in the folder with the program:

Similarly, if you want to redirect the output of your processes to the standard supervisor output, you should use the redirect_stderr and redirect_stdout parameters . If your program needs any environment variables, you can pass them using the environment parameter. Variables should be written with commas. For example:

$ environment=DISPLAY=":1",HOME="/root"

After each configuration change, remember to restart supervisor to apply the changes. The supervisorctl utility can be used to control processes. As you have already realized, in order to see the list of processes you need to execute:

$ sudo supervisorctl status

Then, knowing the name of the process, you can restart it, for example process:process_00:

$ sudo supervisorctl restart process:process_00

Stop:

$ sudo supervisorctl stop process:process_00

Or start:

$ sudo supervisorctl start process:process_00

You can also connect to the process and see what it outputs to stdout/stderr using the fg command:

$ sudo supervisorctl fg process:process_00

We have looked at how supervisor is configured and how to use the process management program.