root/cherokee/trunk/doc/cookbook_django.txt

== link:index.html[Index] -> link:cookbook.html[Cookbook]

Cookbook: Setting up Django
---------------------------

Django is a fantastic high-level Python Web framework that can run
nicely with Cherokee and either the
link:modules_handlers_scgi.html[SCGI] or
link:modules_handlers_fcgi.html[FastCGI] handlers.

To properly set up Cherokee to use Django you will need a working
Django framework, which is not difficult at all to get ready. The
details vary from system to system. You can refer to the official
project's documentation for more information on
link:http://www.djangoproject.com/documentation/install[how to install
Django].


On Debian based systems this will be enough:
----
# apt-get install python-django python-flup
----

You will need Flup because it implements the standard interface
between Python Web applications and Web servers, so you will be using
it to run your web application either as FastCGI or SCGI.

Once you are done with that, you must deploy your Django project:

----
$ cd /var/www
$ django-admin startproject example
----

This will create the basic structure into a new directory called
`example`. Now you are ready to configure Cherokee. You only need to
know how to spawn the FastCGI or SCGI, which is done with a script
provided by your project called `manage.py`.

It can be run on a TCP port or on a Unix socket. In our example we
will be launching it as threaded server on a TCP port with SCGI
protocol. This is acomplished with the following command, which is
what we will have to set up in `cherokee-admin`.

----
./manage.py runfcgi method=threaded host=127.0.0.1 port=3033 protocol=scgi
----

The process is fairly simple. Set up a new rule for this new path and
manage it with the SCGI handler. If you wanted to use the FastCGI
handler instead you would only have to omit the last parameter and
FastCGI would be used by default. The configuration of the handler is
exactly the same for SCGI and FastCGI.

Once you have created the new rule for your `/var/www/example`
directory, choose the desired handler and use the following
configuration.

.Common CGI options
Under `Common CGI options` make sure to check the `Error handler` box and
uncheck `Check file`. This is to prevent possible errors with the
`INFO_PATH` generation that can happen when an application, in this
case 'Django', manages the whole subtree. This is mentioned in the
link:modules_handlers_cgi.html[Common CGI] section of the
documentation. It is a good idea to enable the `Error handler`
checkbox since it will help you determine if an error is associated
with your Django application or with Cherokee. This, however, is not
required.

image::media/images/cookbook_django_common.png[Common CGI options]

.SCGI specific
Under `SCGI specific` make sure to add the hosts providing the
service. This is done by adding one or more information sources.

image::media/images/cookbook_django_infosources.png[Information Sources]

Note that you will have to manually launch the `spawner` if
you use a `Remote host` as `Information source` instead of a `Local
interpreter`.

You will simply have to add as many sources as needed, for instance
our example uses one nicknamed `django1`, created as *local
interpreter* with these parameters on port 3033.

[grid="rows"]
`~~~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Host           , Interpreter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
localhost:3033 , `/var/www/example/manage.py runfcgi method=threaded ` \
                 `host=127.0.0.1 port=3033 protocol=scgi`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can set up as many hosts as desired and Cherokee will balance the
load among them.

Once everything is done you can check if Django is really
working. Simply navigate to the path configured by your rule,
http://localhost/example for instance, and you should see some notes
about your recently created project.

image::media/images/cookbook_django.png[Django example]

*********************************************************************
Should you wish to deploy your Django application directly instead of
through `manage.py` this could be easily achieved. Just remember to
daemonize the script used to launch the interpreter in the relevant
`information source`.

This is done adding the appropriate parameter to the `runfastcgi`
method of `django.core.servers.fastcgi` in your script.

.Using a unix socket:
----
from django.core.servers.fastcgi import runfastcgi

runfastcgi(method="threaded", daemonize="true", maxrequests=5, 
           protocol="scgi", socket="/tmp/cherokee-django.socket",
           pidfile="/tmp/cherokee-django.pid")
----

.Using a host:port configuration:
----
from django.core.servers.fastcgi import runfastcgi

runfastcgi(method="threaded", daemonize="true", maxrequests=5, 
           protocol="scgi", host="127.0.0.1", port=3033)
----
*********************************************************************