This article is outdated and may not work correctly for current operating systems or software.
Supervisor is a client/server system used to control a number of UNIX processes, more specifically processes related to a project or a customer. For example, you could use supervisor to spawn and monitor an arbitrary number of worker queues of your web application.
The components of this system are:
supervisord: The server piece of the system.
supervisorctl: The command-line interface used to interact with the server.
Web server: A simple web server and a web user interface with basic functionality compared to supervisorctl.
XML-RPC Interface: The same HTTP server used by the web client, serves an XML-RPC Interface that can be used to control supervisor programs.
In this tutorial we will install the most up-to-date version of supervisor, demonstrate how to spawn and manage programs through supervisorctl, and configure a web interface to manage our programs.
We will be installing supervisor through easy_install, a feature of python's setuptools.
First, update your local packages list and then install python setuptools.
sudo apt-get update && sudo apt-get install python-setuptools
Now we can install supervisor.
sudo easy_install supervisor
Once the installation is complete, we have to generate our configuration file. Create a folder named supervisor inside /etc.
sudo mkdir /etc/supervisor
And then execute the following.
echo_supervisord_conf > /etc/supervisor/supervisord.conf
If you aren't logged in with the root user, you may get a Permission denied error (even with sudo). This is due to the redirection. To overcome this, login as root.
sudo su
Then you can run the command again.
echo_supervisord_conf > /etc/supervisor/supervisord.conf
You can now leave the root user with the exit command. The echo_supervisord_conf command was provided by our supervisor installation.
Open the /etc/supervisor/supervisord.conf file and check its contents. You will note that this configuration file follows the INI syntax, and it is divided by sections (representend by brackets as in [section-name]).
To add programs to be managed by supervisor we just need to create the appropriate [program] sections. However, to avoid messing arround with the main configuration file every time we need to add (or change) a program, we will be using the [include] section. Find this section, uncomment it and then edit it to look like the following.
[include]
files=conf.d/*.conf
Now for each program we want to add, we will be creating a .ini file inside the /etc/supervisor/conf.d/ directory. Lets create this folder.
sudo mkdir /etc/supervisor/conf.d
As noted before, supervisor is composed of a server and clients that connect to it. To be able to manage and control programs, we need to start the server. To do so, we will be registering the supervisor server in systemd, so that the server may be started at system startup.
To do so, create a file called supervisord.service in the /etc/systemd/system directory.
sudo touch /etc/systemd/system/supervisord.service
Add the following contents to the file.
[Unit]
Description=Supervisor daemon
Documentation=http://supervisord.org
After=network.target
[Service]
ExecStart=/usr/local/bin/supervisord -n -c /etc/supervisor/supervisord.conf
ExecStop=/usr/local/bin/supervisorctl $OPTIONS shutdown
ExecReload=/usr/local/bin/supervisorctl $OPTIONS reload
KillMode=process
Restart=on-failure
RestartSec=42s
[Install]
WantedBy=multi-user.target
Alias=supervisord.service
Activate the supervisord service.
sudo systemctl start supervisord.service
As long as the service file is located in the /etc/systemd/system directory, it will be automatically started at system startup.
You can check the status of the service.
systemctl status supervisord.service
Also, you can check out the logs.
sudo journalctl -u supervisord.service
The programs controlled by supervisor are given by different [program] sections in the configuration. For each program we want to manage, we will create a standalone configuration file informing the command executable path, any environmental variables, how to perform in case of a shutdown.
First, let's create a simple script that logs a timestamp. Create a file called hello_supervisor.sh (anywhere you wish, we will be referencing the full path of this script).
touch hello_supervisor.sh
Now, put the following contents into it
#!/bin/bash
while true
do
# Echo current timestamp to stdout
echo Hello Supervisor: `date`
# Echo 'error!' to stderr
echo An error ocurred at `date`! >&2
sleep 1
done
Now make it executable
chmod +x hello_supervisor.sh
In practical terms this script is pretty much useless. However, we can use it to demonstrate the power of supervisor. Create the corresponding configuration file by running the following.
sudo touch /etc/supervisor/conf.d/hello_supervisor.conf
Now put the following contents into this file.
[program:hello_supervisor]
command=/home/USER/hello_supervisor.sh
autostart=true
autorestart=true
stderr_logfile=/var/log/hello_supervisor.err.log
stdout_logfile=/var/log/hello_supervisor.out.log
Note: Be sure to replace USER with your username.
We will review this configuration step by step.
[program:hello_supervisor]
command=/home/USER/hello_supervisor.sh
First, the configuration begins by defining a program of name hello_supervisor. It also informs the full path of the executable to be run.
autostart=true
This line states that this program should be automaticaly started when supervisor is started.
autorestart=true
If the program quits, for any reason, this line informs supervisor to automatically restart the process.
stderr_logfile=/var/log/hello_supervisor.err.log
stdout_logfile=/var/log/hello_supervisor.out.log
These lines define the logfile location for stderr and stdout, respectively.
Now that we have installed and configured supervisor, we are able to manage our processes.
After adding a new program, we should run the following two commands, to inform the server to reread the configuration files and to apply any changes.
sudo supervisorctl reread
sudo supervisorctl update
Now execute the supervisorctl client.
sudo supervisorctl
You will be greeted with a list of the registered proccesses. You will see a proccess called hello_supervisor with a RUNNING status.
hello_supervisor RUNNING pid 6853, uptime 0:22:30
supervisor>
Type help for a list of avaialable commands.
supervisor> help
default commands (type help <topic>):
=====================================
add exit open reload restart start tail
avail fg pid remove shutdown status update
clear maintail quit reread signal stop version
In a nutshell, we can start, stop and restart programs by passing the program name as an argument to the respective command.
supervisor> stop hello_supervisor
hello_supervisor: stopped
supervisor> start hello_supervisor
hello_supervisor: started
supervisor> restart hello_supervisor
hello_supervisor: stopped
hello_supervisor: started
supervisor>
We can also take a look at the program output with the tail command.
supervisor> tail hello_supervisor
Hello Supervisor: Mon Sep 25 19:27:29 UTC 2017
Hello Supervisor: Mon Sep 25 19:27:30 UTC 2017
Hello Supervisor: Mon Sep 25 19:27:31 UTC 2017
For the stderr output, you can use tail as well.
supervisor> tail hello_supervisor stderr
An error ocurred at Mon Sep 25 19:31:12 UTC 2017!
An error ocurred at Mon Sep 25 19:31:13 UTC 2017!
An error ocurred at Mon Sep 25 19:31:14 UTC 2017!
By invoking the status command, you can view the status of all registered programs.
Once you are finished, you can quit.
supervisor> quit
To allow access to the supervisord webserver, open the supervisord configuration file and locate the [inet_http_server] section.
nano /etc/supervisor/supervisord.conf
Now update this section's configuration with the following.
[inet_http_server]
port=*:9001
username=your_username
password=your_password
Replace your_username and your_password with your desired credentials, save your modifications and the restart supervisord service.
sudo systemctl restart supervisord.service
Remember to allow TCP access to the port 9001 on your firewall and then access http://{server-ip}:9001 from your browser. When asked, provide your username and password. You can now control your proccesses from web.
We have installed the most up-to-date version of supervisord, learned how to configure it for system auto-start with systemd and also reviewed a basic usage of supervisorctl. For more advanced configuration and use cases you may refer to the official supervisord documentation.