Managing Gunicorn Processes With Supervisor

Last week, I have written a post about gunicorn applications. We started gunicorn manually, and our application worked. Yay!

However, everything is not so great. When (If) the server reboots, gunicorn must be started manually, again. We should find a way to automate this. Actually, there are few ways to accomplish this, such as: init scripts, and supervisord.

Init scripts are more than enough. But they have some drawbacks. They are not so easy to write or maintain. If you have several projects, things get even harder. Supervisord is a relatively easier way for managing multiple gunicorn processes.

Let’s start with installing supervisor:

sudo apt-get install supervisor

Supervisor uses configuration files for applications located in /etc/supervisor/conf.d/ directory. The configuration for our application is below:

[program:hello]
command = gunicorn hello:app
directory = /path/to/hello/
user = username

This is a very basic configuration required to run gunicorn. Since we are using virtualenv, we need to change “command” parameter to use python and gunicorn from our environment instead of global ones.

command = /path/to/virtualenv/bin/python /path/to/virtualenv/bin/gunicorn hello:app

Now we can test, whether our configuration works or does not. Reload supervisor with following commands and start our application. Stop gunicorn if it is running, and start it again with supervisor.

supervisorctl reread
supervisorctl update
supervisorctl start hello

Now gunicorn must be running, you can make sure by visiting page. If server reboots, supervisor starts it. If gunicorn fails, supervisor restarts it. Finally, everything is great!

You can find more information about supervisor configuration parameters in the documentation. You can also read my blog post about restarting and reloading supervisor.

Supervisord: Restarting and Reloading

Supervisord is a great daemon for managing application processes. However it does not have a reload option, and restart works different than we get used to. These command makes the following effects.

service supervisor restart

Restart supervisor service without making configuration changes available. It stops, and re-starts all managed applications.

supervisorctl restart <name>

Restart application without making configuration changes available. It stops, and re-starts the application.

If you create a new configuration. None of the commands above will make it available. If you want to apply your configuration changes in both existing and new configurations, start applications in new configurations, and re-start all managed applications, you should run:

service supervisor stop
service supervisor start

If you do not want to re-start all managed applications, but make your configuration changes available, use this command:

supervisorctl reread

This command only updates the changes. It does not restart any of the managed applications, even if their configuration has changed. New application configurations cannot be started, neither. (See the “update” command below)

supervisorctl update

Restarts the applications whose configuration has changed.
Note: After the update command, new application configurations becomes available to start, but do not start automatically until the supervisor service restarts or system reboots (even if autostart option is not disabled). In order to start new application, e.g app2, simply use the following command:

supervisorctl start app2