Search Suggestions

The Ultimate Guide To Installing Django, uWSGI and Cherokee

Emilian F. Published on 28 May, 2012

This guide will show you how to install Django and get it working with Cherokee and uWSGI using virtualenv. I wrote this primarily because there are no good guides available on how to accomplish this. This guide does not attempt to explain WHY you should be using Cherokee or uWSGI, that's for another post!

For this recipe you will need to:

  • know your way around the console
  • use vim / nano or another text editor to modify text files

By the end of the recipe you will have accomplished the following:

  • installed pip, virtualenv and virtualenvwrapper
  • installed Django 1.3.1 in a virtual environment named trunk
  • installed Cherokee and the Cherokee control panel (cherokee-admin)
  • installed uWSGI with virtual environment support

Installing pip + virtualenv + virtualenvwrapper

Pip is used to install Django, virtualenv and virtualenvwrapper. Virtualenv is a virtual environment for Python that basically allows you to have multiple versions of Python libraries on the same system. Virtualenvwrapper is a wrapper around virtualenv that makes it easier to create and switch between different virtual environments.

$ sudo apt-get install python-pip python-dev build-essential 
$ sudo pip install --upgrade pip 
$ sudo pip install --upgrade virtualenv

Now to install virtualenvwrapper enter this in the command line:

$ pip install virtualenvwrapper

Warning!

Make sure that you run the above commands while you are NOT in a virtual environment because you want to install virtualenvwrapper in the base (global) Python installation. If you do not know what this means, then it probably means you do not have an active virtual environment.

Creating a virtual environment for Django

Now we need to create a virtual environment where Django can be installed. This will be done by creating a folder to store the virtual environment and then linking that folder to virtualenvwrapper and pip.

Create the folder that will be used to store the virtual environments in your home directory:

$ mkdir envs

Now we have to connect the ~/envs/ folder with virtualenvwrapper and pip. To do that modify the ~/.bashrc file by entering the following lines of code at the top of the file:

export WORKON_HOME=~/envs
source /usr/local/bin/virtualenvwrapper.sh
export PIP_VIRTUALENV_BASE=$WORKON_HOME
export PIP_RESPECT_VIRTUALENV=true

Save the changes above, and reload the ~/.bashrc file by entering the following code in the command line:

$ source ~/.bashrc

If everything went well you should see a bunch of text informing you that the connection was made and that virtualenvwrapper knows about the ~/envs/ folder.Now we can create the virtual environment, named trunk in this case where we will install Django:

$ mkvirtualenv trunk

Your command prompt should now look like this:

(trunk)$

Notice the (trunk) identifier which basically tells you that you are now in the virtual environment named trunk.

Installing Django

Now all you have to do to install Django is enter the following command in the console:

(trunk)$ pip install django

If you want to install a specific version of Django (for example, Django version 1.3.1) you can enter the following command:

(trunk)$ pip install django==1.3.1

Pip will now install Django in the trunk environment. It will not be available in the base / global Python environment.

Installing Cherokee

The next step is to install the web server, in this case Cherokee. We will also install the control panel for Cherokee to edit the settings.

$ sudo apt-get install cherokee
$ sudo apt-get install cherokee-admin

Installing uWSGI

Now we need to install uWSGI.

$ pip install uwsgi

If you get errors, you might need to install the python headers by running the following command in your console:

$ sudo apt-get install build-essential python-dev libxml2-dev

Warning!

Do not install uWSGI while in the trunk virtual environment. You have to deactivate the virtual environment before installing uWSGI by entering the following command in the console: (trunk)$ deactivate

Laying out the Django project

Now we have to create the Django project files, the uWSGI configuration files and put everything together. We have two uWSGI specific files (uwsgi.conf and reload.wsgi). The first one (uwsgi.conf) contains the configuration for the uWSGI server, while the reload.wsgi file is empty and is only used to reload uWSGI by touching the file.

/home
    username/
        project/
            __init__.py
            reload.wsgi
            manage.py
            settings.py
            urls.py
            uwsgi.conf
 

Contents of the uwsgi.conf file

Create the uwsgi.conf file in the /home/username/project/ directory with the following contents:

[uwsgi]
chdir = /home/username/
pythonpath = /home/username/
env = DJANGO_SETTINGS_MODULE=project.settings
module = django.core.handlers.wsgi:WSGIHandler()
socket = /tmp/uwsgi.sock
touch-reload = /home/username/project/reload.wsgi
daemonize = /var/log/uwsgi.log
processes = 4
master = true
home = /home/username/envs/latest

Make sure to replace username with the actual username that you are logged in with.

Creating a virtual host in Cherokee

The next step is to create the virtual host in Cherokee using the Cherokee admin interface. Let's start Cherokee admin:

$ sudo -b cherokee-admin

Login to the control panel given the credentials in the console and then go to vservers (top right) -> new as shown in the following screen shot:

Pick "Manual" from the list on the left and tnter the required information:

Make sure you replace username and the localhost domain name with the appropriate values.

Adding a new information source for uWSGI

Notice that the configuration value is the same as the socket value in the /home/username/project/uwsgi.conf file. On the next screen make sure to pick "Local Interpreter" instead of "Remote host".

Adding a Behavior rule and handler for the uWSGI Information Source

Now we have to tell Cherokee to redirect all of the requests from the domain name to our uWSGI server. This can be done by adding a behavior rule, then setting up a uWSGI handler for that rule.

Starting uWSGI

Now you have to start uWSGI and feed it the appropriate values to the configuration file.

$ /usr/local/bin/uwsgi --ini /home/username/project/uwsgi.conf

Again, make sure to replace username with the actual username for the website. Notice that we passed in the location of the trunk virtual environment over to the uWSGI server.

Installation complete!

You should now be able to browse to the virtual host in your browser and see the Django welcome page. If you run into any issues please post the error below to get some help.

Emilian F. Published on 28 May, 2012