Linux distributions have initialization systems for managing processes, for example, Systemd. But sometimes you need something more simplier, a program that will manage your application processes in the system or a docker container. Such a program exists. It is called Supervisor.
It is a simple open-source process manager, written in Python. Supervisor can help run the required quantity of copies of the process and monitor their state. In this article, we will explain how to install and configure supervisor on Ubuntu 22.04.
Install Supervisor on Ubuntu
The simplest way to get the program installed – install it from the official repositories. To do this, run this command:
sudo apt install supervisor
If you want a program to work all the time, add it to autoloading and run. To do this, run the following command:
sudo systemctl enable supervisor --now
After this you can check the program running state using this command:
sudo systemctl status supervisor
How to Configure Supervisor
The program’s configuration file is located in /etc/supervisor/supervisord.conf. It should contain only the main settings. It will be better to use the directory /etc/supervisor/conf.d/ to configure managed processes. You can leave the main configuration file as is. Let’s look how to make configuration files for the processes. The syntax for the process section looks like this:
[program:program_name]
var_name=value
You should set these required variables for each process if you want it to auto start and recover after failing:
- directory – working directory;
- command – command that runs the process;
- user – user that will owe the process;
- autostart – enables automatic start of the process;
- autorestart – enables automatic restart of the process after failing.
However, there are many more settings available. Here are some of those that will be used in this article:
- priority – priority of the process;
- environment – environment variables to be passed to the process;
- stdout_logfile – file for redirecting stdout output from the process;
- stderr_logfile – file for redirecting stderr output from the process;
- process_name – name of process, with the possibility of substituting the process copy number;
- numprocs – number of process copies to run;
- startretries – number of attempts to run the process;
- redirect_stderr – redirect the stderr process output to the supervisor output;
- redirect_stdout – redirect the stdout process output to the supervisor output.
For example, make PHP script that will stick in the background:
sudo vi /home/sergiy/program/process.php
<?php
echo "Started...";
while (true) {
sleep(5);
}
Next, create a supervisor configuration file for this process. You can paste the configuration right at the end of the main configuration file. But it will be better make dedicated config file for each process in /etc/supervisor/conf.d/ directory with name *.conf. For example, configuration file for this program 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
After this, restart supervisor. You can do it using systemctl:
sudo systemctl restart supervisor
Or you can use supervisorctl:
sudo supervisorctl reload
Next, you can check the state of configured processes using this command:
sudo supervisorctl status
If the process is in the RUNNING state it means that everything is okay, and it has run successfully. Now, one copy of the process is running. But very often you may need to run several copies of same process. You can use variables like process_name and numprocs to do it. First variable allows changing name of the process to add a copy number. Second enables setting how many copies will be launched.
The process_name variable usually contain a pattern for Python string formatting that contains program name and process number. For example: %(program_name)s_%(process_num)02d. Here the variable name is placed in the brackets followed by, the variable type after. If you want to run four copies of same process change the process config file so that it looks 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
process_name=%(program_name)s_%(process_num)02d
numprocs=4
Now, restart Supervisor again. After this, you will see four processes in the RUNNING state:
sudo supervisorctl status
In addition, you can save everything that the program outputs to a log file. Use stdout_logfile and stderr_logfile to do this. For example, you can save the execution log directly in the directory 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
You will see log files in the program directory after Supervisor restart.
If you want to redirect process output into the standard Supervisor’s output, use parameters redirect_stderr and redirect_stdout. If your program needs any environment variables, you can pass them using the environment parameter. Divide variables using commas. For example:
environment=DISPLAY=":1",HOME="/root"
Don’t forget to restart Supervisor after each configuration change to apply the changes. You can manage processes manually using the supervisorctl utility. If you want to see a list of all processes, run the following command:
sudo supervisorctl status
Now, you know the process name and can restart it using this command:
sudo supervisorctl restart process:process_00
Or stop it:
sudo supervisorctl stop process:process_00
Or launch it:
sudo supervisorctl start process:process_00
In addition, you can connect to the process output and view what it outputs in stderr/stdout using command fg:
sudo supervisorctl fg process:process_00
Wrapping Up
In this article we have explained how to configure Supervisor and how to use the program to manage your processes. As you can see, the program is very convenient and simple to use. It is especially convenient to use it in Docker, due to the limitation on one running process in a container. You can run only Supervisor, and all other processes run using it.
