July 25, 2008

Tutorial: Installing Django on (mt) Media Temple DV 3.5 server with mod_python

When I first set out to install Django on my Media Temple server running under mod_python, I ran into a few gotchas. Luckily, there are lots of people who've tried the same thing and were successful. Unfortunately, however, those tutorials and discussions are scattered all over the place, and there really is no definitive guide to installing Django on a (mt) Media Temple DV. Thus, I'll attempt to do just that, from start to finish.

Root access and Developer Tools package

First thing to do is make sure you've got root access to your server and that you have the (mt) Developer Tools package installed.

You can enable root access and Developer Tools on your DV by going to your (mt) account center, select the server, and select 'Root Access and Developer Tools'. From there, you can switch on root access, as well as the Developer Tools package.

Among other things, the Developer Tools package installs Subversion, which we'll use to grab the latest Django release.

Once you've got root access, you're ready to proceed with installation. Here's a high-level look at what we'll be doing:

Download Django
Install Django
Start a Django project
Serve the project through Apache

First, SSH to your server. Switch to the root user with the password you setup in the account center, with the following command:

su -

You should see something like this:

[root@servername ~]#

Download Django

You'll want to install Django into '/var', so switch to that directory:

cd /var

Once you're there, download Django from djangoproject.com with the following command:

svn checkout http://code.djangoproject.com/svn/django/trunk/ django-trunk

This command will use Subversion to checkout the latest trunk release of Django. This may change in the future as Django approaches a 1.0 release, as trunk checkouts are generally considered unstable.

Install Django

Next, you'll need to install Django. The installation process essentially allows Python to see your Django checkout. Django is technically nothing more than a bunch of Python modules, so installation is simple. Python simply needs to have the Django directory accessible from the PythonPath. Django ships with an installation script to copy your checkout into the Python packages directory, but this eliminates your ability to run periodic Subversion updates on the Django checkout, since Django is still not yet a 1.0 release. Thus, we simply create a symlink from our checkout to the Python packages directory. The following code will do that for you from within the '/var/' directory:

ln -s `pwd`/django-trunk/django /usr/lib/python2.4/site-packages/django

If nothing happens, it was successful. You can test whether or not Python is ready to use Django by hopping into the Python interactive shell by typing the command at any directory other than the parent directory of the 'django-trunk/django' directory (because Python inherits the path you're currently in):

python

You should get:

Python 2.4.3 (#1, Mar 14 2007, 18:51:08) [GCC 4.1.1 20070105 (Red Hat 4.1.1-52)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>>

Type the following at the Python prompt:

import django

then:

django.VERSION

You should see something similar to this:

>>> import django >>> django.VERSION (1, 0, 'alpha') >>>

The version numbers may be different, but that's fine. As long as you didn't see an import error, you've successfully installed Django and can begin building applications.

Start a Django project

Now you need to start your first Django project. Django provides a handy script that starts a base project for you. This script lives within your Django checkout, but for simplicity's sake, it'll be easier to put this script on your system path so you don't need to use the full path to your Django checkout everytime you want to start a new project. Run the following command from your '/var' directory to put the script on your path:

ln -s `pwd`/django-trunk/django/bin/django-admin.py /usr/local/bin

Cool. Let's say you want all of your Django projects to live within one directory ('/var/django-projects'). Head over to '/var' and run the following command:

mkdir django-projects

Now create a project within that directory with the following command:

django-admin.py startproject mysite

That's it. The Django script will generate a directory within django-projects titled 'mysite' which has some basic code to get you up and running with your first application.

Serve the project through Apache

Django comes with a really handy development server, but it is not intended for use as a production server. Thus, the easiest thing to do is to get Apache to server your Django application with mod_python. While mod_python is quite old, and is not the fastest and most preferred method of hosting your Django apps on Apache, it is currently the recommended solution.

Your DV 3.5 server should already have mod_python installed and working under Apache. There's nothing you need to do to get that running.

You do, however, need to let Apache know that you'd like it to serve a Django application somewhere. You'll do this in your vhost directives.

You'll need to be logged in as root to modify your vhost directives, so go ahead and do that, and navigate to your domain's directory. It'll be something like this:

/var/www/vhosts/domain.com

Once in there, navigate to the 'conf' directory for that domain.

Inside of that directory, you'll see this:

httpd.include

Don't touch that. That's a file that's generated from Plesk, and if you modify it, you'll lose your changes the next time Plesk updates. Instead, create a file named 'vhost.conf'. Plesk looks for this file in every 'conf' directory when it updates to include that file if there is one. Thus, you can make all of your changes here, and you'll be good to go.

Within your newly created 'vhost.conf' file, enter this:

<Location "/"> SetHandler python-program PythonPath "['/var/django-projects'] + sys.path" PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonDebug On PythonInterpreter mysite </Location> <Location "/media"> SetHandler None </Location> <LocationMatch "\.(jpg|gif|png)$"> SetHandler None </LocationMatch>

These directives will do a few things:

Tell Apache to let mod_python handle all of the requests to '/' for 'domain.com' (because we're in /var/www/domain.com).
Tell Django where to find the settings file for the Django application. We use mysite.settings here because we used django-admin.py to start the project 'mysite', and 'settings.py' lives within that directory.
Turn the Python debugger on - you'll want this off for production sites (it basically enables detailed error messages).
Set a unique id for the PythonInterpreter. This is needed if you plan to power multiple applications under mod_python (I think).
Tell Apache to not use mod_python for any files under the '/media' directory (or any file ending with .jpg, .gif or .png). This is because we'll want to serve real files under this directory - and mod_python shouldn't touch them.

Once you've saved that file, you need to restart Plesk / Apache so that it will detect this file and process it for directives. On your (mt) DV 3.5, run the following command to restart:

/usr/local/psa/admin/sbin/websrvmng -a -v

Go ahead and load up the domain that you've pointed to use Django, and, with any luck, you're good!

My headache

Now, when I first attemped to get Django running under mod_python, Python wouldn't recognize Django. This made me crazy for about two days, until I realized I had installed Django into my home folder, which Apache was not allowed to read. Sigh.

So that's about it, have fun!