Documentation

Cookbook: Deployment of an uWSGI application

Python applications can be deployed in many ways, be it using flup, FastCGI, SCGI, WSGI, etc. uWSGI is a feature rich, developer friendly application to do exactly that. It is a fast (pure C), self-healing, feature-rich WSGI server, aimed for professional python webapps deployment and development.

Cherokee offers native support for it. The configuration is quite easy, and uses the uWSGI handler.

There is a screencast available at the Cherokee-Project website to demonstrate how easy it is to use the uWSGI wizard.

media/images/screencast.png

To run Cherokee with uWSGI four simple steps will suffice:

  1. You will need to complete a regular uWSGI installation

  2. Add the produced binary into your PATH under the name "uwsgi"

  3. Adapt your application to work with uWSGI.

  4. Run the uWSGI Wizard provided by Cherokee and let it handle everything by itself.

Note
 uWSGI has evolved quite a lot since both the recipe and the uWSGI-wizard were written. Currently the uWSGI-wizard has been reported as not working out of the box, and the task of fixing the wizard has been assigned. If you have trouble using the wizard, don’t hesitate to look for assistance on our mailing lists.

The last step, configuring Cherokee, is trivial. The wizard will read the specified configuration file and will configure the web server accordingly.

Adapting your project is also fairly easy. For example, suppose you have a Django application which you want to adapt. You’ll have to create 2 configuration files on your django project directory.

Django

We’ll call this one django_wsgi.py:

django_wsgi.py
import os
import django.core.handlers.wsgi

os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
application = django.core.handlers.wsgi.WSGIHandler()

uWSGI

uwsgi.xml
<uwsgi>
    <pythonpath>/var/www/example/</pythonpath>
    <pythonpath>/var/www/</pythonpath>
    <app mountpoint="/">
        <script>django_wsgi</script>
    </app>
</uwsgi>

Since it is unlikely you’ll have the Django project on your system path, it should be reflected on the pythonpath line. In this example, it would be under /var/www/example/

Cherokee

The wizard will look for the uWSGI server, find out the mountpoint and configure the web server accordingly. Nothing more to do.

Troubleshooting

This should work out of the box, but in case it doesn’t you might need some pointers to determine what is going wrong exactly.

You should check both your error and access log files, and it comes in very handy to execute uWSGI by hand when running your tests. This will give all the help you need in the form of backtraces.

The simplest way to do so is looking into the Information Sources section in Cherokee-Admin, exploring the one created by the uWSGI wizard, and running that command by hand.

/usr/local/bin/uwsgi -s /tmp/cherokee-source1.sock -C -x /<path to my django project>/uwsgi.conf

Make sure to kill other instances running in the background.

Another thing to keep in mind is that sometimes you might modify Python sources and not see the changes reflected on the server. In those cases simply restart Cherokee through Cherokee-Admin or simply by sending the SIGHUP signal.

# killall -SIGHUP cherokee