is a monitoring tool which controls various child processes and
handles starting/restarting of these child processes when they exit
abruptly or exit due to some reasons. It can be extended to control
the processes via the XML-RPC API over remote locations without logging
in to the server. I will cover the XML-RPC API in the second part of this two-part series.
In the first part of this tutorial series, I will take you through how to set up Supervisor to work with our application. For this, I will create a trivial application in Flask along with Gunicorn to act as our WSGI HTTP server.
I assume that you have a basic understanding of Flask, Gunicorn and environment setup best practices using virtualenv to be followed while developing a Python application.
The following packages need to be installed for developing and controlling the application we'll be developing.
$ pip install gunicorn supervisor Flask
I will now create a trivial application in Flask. This application is small but will meet the needs of this tutorial.
Below is the structure of the application:
flask_app/ my_app/ - __init__.py - views.py
from flask import Flask app = Flask(__name__) import my_app.views
In the file above, the application has been configured and initialised.
from my_app import app @app.route('/') def hello_world(): return 'Hello to the World of Flask!'
In the file above, I have created a simple Hello World endpoint.
To run the application as a process, we can use Gunicorn. To check if Gunicorn is working as expected, just run the following command from inside the application folder.
$ gunicorn -w 4 -b 127.0.0.1:8000 my_app:app
After this, point your browser to http://127.0.0.1:8000/ to see the application's
Now, we need to do the same using Supervisor so that this runs as a daemon and will be controlled by Supervisor itself rather than human intervention.
First of all, we need a Supervisor configuration file. Supervisor, by default, looks for an
etc folder that has a file named
supervisord.conf. In system-wide installations, this folder is
/etc/, and in virtualenv,
it will look for an
etc folder in virtualenv and then fall back to
In the case of a system-wide installation, run:
$ echo_supervisord_conf > /etc/supervisord.conf
In the case of virtualenv, from inside the virtualenv root folder, run:
$ echo_supervisord_conf > etc/supervisord.conf
echo_supervisord_conf program is provided by
Supervisor; it prints a sample config file to the location specified. This will create a file named
supervisord.conf at the location specified in the above command.
To configure Supervisor for our application, add the following block somewhere in this file:
[program:supervisor_demo] command=<path/to/virtualenv>/bin/gunicorn -w 4 -b 127.0.0.1:8000 my_app:app directory=<path/to/virtualenv>/supervisor-tutsplus-demo user=someuser # Relevant user autostart=true autorestart=true stdout_logfile=/tmp/app.log stderr_logfile=/tmp/error.log
Here we configure the command that needs to be run and from which directory location it needs to do so under which user. Also specified is whether to restart the application in case of any failure. The log files' locations can also be specified. There are many other configuration options, which can be looked up in the official documentation of Supervisor.
Make a note that one should never run the applications as a root user.
This is a huge security flaw as the application crashes, which
can harm the OS itself.
To run the application using Supervisor, run the following commands:
$ supervisord $ supervisorctl status supervisor_demo RUNNING pid 22550, uptime 0:00:04
The first command invokes the
supervisord server, and the next one gives a status of all
the child processes.
Every time you make a change to your application and then wish to restart Gunicorn in order for it to reflect the changes, run the following command:
$ supervisorctl restart all
You can also give specific processes instead of restarting everything:
$ supervisorctl restart supervisor_demo
Supervisor also provides a Web UI interface which can be enabled by enabling the
inet_http_server configuration block in
supervisord.conf. This Web UI can be looked up on http://localhost:9001/.
In this tutorial, we have seen how to configure Supervisor and use it to run an application as a daemon process and control the processes collectively or selectively. In the second part of this tutorial series, we will see how to control and interrogate Supervisor and its programs/processes using the XML-RPC API.