== link:index.html[Index] -> link:cookbook.html[Cookbook]
///////////////////////////////////////////////////////////////////
Last checked:
* Cherokee: 0.99.25
* uWSGI 0.92
///////////////////////////////////////////////////////////////////

Cookbook: Deployment of an uWSGI application
--------------------------------------------

Python applications can be deployed in many ways, be it using flup,
FastCGI, SCGI, WSGI, etc. link:http://projects.unbit.it/uwsgi/[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 link:modules_handlers_uwsgi.html[uWSGI] handler.

There is a
link:http://www.cherokee-project.com/screencasts.html#django_uwsgi[screencast]
available at the
link:http://www.cherokee-project.com/[Cherokee-Project website] to
demonstrate how easy it is to use the uWSGI wizard.

image:media/images/screencast.png["uWSGI wizard",
link="http://www.cherokee-project.com/screencasts.html#django_uwsgi"]

To run Cherokee with uWSGI four simple steps will suffice:

. You will need to complete a regular
link:http://projects.unbit.it/uwsgi/wiki/Install[uWSGI installation]

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

. Adapt your application to work with uWSGI.

. 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
link:other_community.html#mailing_lists[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]]
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
--------------------------