Portable Django project with Buildout

The last few days I've been working on a project using Django, and to set up my Django projects, I find the best solution is using Buildout. I think messing around with virtual environments is annoying, makes it harder to deploy the project later, and frankly just wastes my time more than it saves it. (It also happens to be the way I learned to do it while working at Opera, but that's besides the point ;) )

The basics

Getting started with Django and Buildout essentially requires two files, the Zope bootstrap.py (available here) and a buildout.cfg for configuring your environment.

A basic buildout.cfg file, utilizing Djangorecipe to install Django, would look something like this:

[buildout]
parts = django

[django]
recipe = djangorecipe
version = 1.1.1
eggs =
	mock
	django-notification
	django-messages
project = my-django-project

This is the configuration for a simple Django project called "my-django-project", which depends on the mock, django-notification and django-messages modules. To build and set up this, you simply enter the following commands:

python bootstrap.py
python bin/buildout

This first runs the bootstrap file, which fetches the necessary modules for running buildout and gives you a buildout binary in the bin/ folder. Then you run the buildout command, which parses the buildout.cfg file, automatically fetching the necessary dependencies, the given Django version (in this case 1.1.1, but you could set it to "trunk" to get the newest development version), and create a version of the Django manager script at bin/django.

This script does exactly what the manage.py script does in a regular django setup, to sync the db you run bin/django syncdb, to start the server you type bin/django runserver, and so on and so forth.

If this is the first time you run the buildout, djangorecipe will also check for the presence of a directory called "my-django-project", and if that doesn't exist, it will create a skeleton Django project with that name, which serves as a great starting point.

All of this greatly simplifies the amount of work needed to start a new django project, you just mock up a tiny buildout config and run buildout, and you have what you need to start easily set up for you.

Taking it further

Now, for me, this still isn't simple enough. It requires the presence of the bootstrap.py file (which isn't strictly a part of the project, and IMO shouldn't be in source control), and two commands. So I made myself a little Makefile to automate the task of running buildout, and it looks a little something like this:

.DEFAULT_GOAL = development
.PHONY = development clean

bootstrap.py :
	wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py

bin/buildout : bootstrap.py
	python bootstrap.py

development : bin/buildout
	python bin/buildout

clean :
	rm -rf bin develop-eggs eggs parts .installed.cfg downloads bootstrap.py

This allows me to simply type in "make" in the directory with the buildout config, and everything will be done automatically, and subsequently type "make clean" if I need to clean out the environment again.

Together with this, I've added a .gitignore file (since I use Git for most of my source control needs), that filters out all the buildout cruft, as well as .pyc files and the SQLite db, if you're using one:

*.egg-info
*.egg
*.pyc
*.db
.installed.cfg
bin/
develop-eggs/
downloads/
eggs/
parts/

These two relatively minor additions allow me to more or less forget about everything that has to do with python virtual environments or even that you need to do special things to make it work. Updating the environment is just a simple "make" away, and the resultant environment stays out of my way in git.