Overview

By now, most people doing Django development should be familiar with pip, virtualenv and virtualenvwrapper. If you're not, the basic problem these tools solve is how to maintain multiple versions of python libraries on your system so that you can seamlessly switch back and forth between different python environments.

For instance, when developing Satchmo, I may have 1 or 2 local branches as well as multiple forks from bitbucket. I may also have client sites in progress that are using older versions of python, django and/or satchmo. In the past, I have used some custom scripts to manage my satchmo and django versions but that process quickly got unwieldy. Coming back to a project after letting it sit for months would always be a challenge. I've also spent time tracking down problems when I realized I was pulling in the wrong version of a package that wasn't immediately obvious. Most of what I'll cover is detailed in these package's excellent docs. However, I will use a couple of the features that aren't as commonly described in other tutorials.

I am using my notes from my recent Ubuntu 10.04 upgrade. For those of you on other systems, you'll need to modify some of the apt-get code to use your system's package management tools.

Several of the python modules have libraries that are compiled from c code. I'll walk through a couple of Ubuntu libraries you can install before hand (or ensure are already installed) so that the rest of the process goes smoothly.

Dependencies

As mentioned above, I recommend you apt-get install a couple of libraries before beginning the rest of this process. These are probably already installed but if not, go ahead and do it so the rest of the process works,

Ensure you can compile c by installing build-essential:

sudo apt-get install build-essential

Now install the python development libraries:

sudo apt-get install python2.6-dev

Before installing any of the other python packages, you should install a couple of libraries so your PIL and Reportlab installs will be complete:

sudo apt-get install libjpeg62 libjpeg62-dev
sudo apt-get install zlib1g-dev
sudo apt-get install libfreetype6 libfreetype6-dev

Python Packages

Now that those packages are installed, you can install pip, virtualenv and virtualenvwrapper:

sudo apt-get install python-setuptools
sudo apt-get install python-virtualenv
sudo easy_install pip
sudo pip install virtualenvwrapper

In order to make the most use of virtualenvwrapper, ensure the following lines are at the end of your ~.bashrc file:

export PIP_RESPECT_VIRTUALENV=true
export WORKON_HOME=$HOME/ve
source /usr/local/bin/virtualenvwrapper.sh

One quick note about the WORKON_HOME variable - that's where the virtualenvs are going to be stored. Modify that so it fits your system.

Before moving to the next step, make sure your source your new .bashrc so all the virtualenvwrapper goodness will be available to you.

Create a Virtualenv

Now, you should have all the pieces you need to create a virtualenv for Satchmo development. Let's create the isolated environment:

mkvirtualenv --no-site-packages satchmo-tip

When it's done, you should have the new environment enabled, so go ahead and install the following packages. Yes, I do know you can use a requirements file to do this in one command but for the purposes of this article, I'm showing each command:

pip install django
pip install sorl-thumbnail==3.2.5
pip install pycrypto
pip install http://www.satchmoproject.com/snapshots/trml2pdf-1.2.tar.gz
pip install django-registration
pip install reportlab
pip install pyyaml
pip install PIL

This has all been pretty straightforward virtualenv process. You should also notice that I haven't installed Satchmo or some of its dependencies yet. In my case, I am actively working on these dependencies and have full hg checkouts of all of these in /home/chris/src/hg-stuff and I would prefer to leave them there and not install a copy in this environment.

That's where the add2virtualenv command comes in handy. This command will create and add lines to a virtualenv_path_extensions.pth file in your virtualenv. I choose to link a handful of these to my development versions as shown below:

add2virtualenv /home/chris/src/hg-stuff/satchmo-working/satchmo/apps
add2virtualenv /home/chris/src/hg-stuff/django-keyedcache
add2virtualenv /home/chris/src/hg-stuff/django-threaded-multihost
add2virtualenv /home/chris/src/hg-stuff/django-caching-app-plugins
add2virtualenv /home/chris/src/hg-stuff/django-signals-ahoy
add2virtualenv /home/chris/src/hg-stuff/django-livesettings

If you don't want to do a local checkout, you could use the following commands to install them directly in your environment:

pip install -e hg+http://bitbucket.org/bkroeze/django-threaded-multihost/#egg=django-threaded-multihost
pip install -e hg+http://bitbucket.org/bkroeze/django-caching-app-plugins/#egg=django-caching-app-plugins
pip install -e hg+http://bitbucket.org/bkroeze/django-signals-ahoy/#egg=django-signals-ahoy
pip install -e hg+http://bitbucket.org/bkroeze/django-keyedcache/#egg=django-keyedcache
pip install -e hg+http://bitbucket.org/bkroeze/django-livesettings/#egg=django-livesettings
pip install -e hg+http://bitbucket.org/chris1610/satchmo/#egg=satchmo

Putting it all together

Assuming it's all working for you, you should be able to use the workon command to see your environments:

chris@enigma:~$ workon
satchmo-0.9
junk
satchmo-tip
django1-1

Now, workon on your new satchmo environment:

 chris@enigma:~$ workon satchmo-tip
(satchmo-tip)chris@enigma:~$

If you want to see your site packages, try this:

cdsitepackages
lssitepackages

I find those two commands very useful for seeing what is installed in your environment.

Now that your environment is setup, you can build your satchmo store in an isolated location that is totally independent from any other python and django projects on your system. I find this is a great way to experiment with multiple projects and decide which ones may or may not warrant additional study.

EDIT: Nov 28, 2010: Added specific version to sorl thumbnail install.