Project Bootstrapping

Filesystem Layout

Note

This document is heavily biased towards Unix-style filesystems and may require additional effort to use in other operating systems.

Virtualenv is a must for Python projects. It provides a method to isolate different Python environments. We typically host our production sites from /opt/webapps/<site_name> and our development sites from ~/webapps/<site_name>. Each individual project gets its own virtualenv that also serves as the directory for all the source files associated with the project. We use pip to populate the virtualenv with the necessary packages.

The bootstrap process looks like this:

cd /opt/webapps
virtualenv mysite.com
cd mysite.com
source bin/activate
pip install -r path/to/requirements.txt

Tip

For convenience, you can use virtualenvwrapper which provides some helpers to make working with virtualenvs more friendly.

Packaging

One of the keys to successful deployment is to ensure that the software you develop on is as close as possible to the software you deploy on. Pip provides a simple repeatable method allowing you to consistently deploy Python projects across many machines. Every application that requires third-party libraries should include a pip requirements file called requirements.txt. Projects should aggregate the application requirements files adding any additional requirements as needed.

What to include in your requirements files

In short, everything. While your operating system may provide some Python packages, nearly everything can be installed cleanly with pip these days. By installing everything into your virtualenv, you can isolate your environment and prevent system packages from causing version conflicts.

Warning

Pin your dependencies! Pip makes it easy to install from a VCS, or just grab whatever version it finds on PyPI. This also makes it easy for your deployments to have different versions of different libraries which can lead to unexpected results. Make sure you specify a version for PyPI libs or a specific commit/tag for VCS checkouts. Examples: django==1.4.1 or -e git+https://github.com/toastdriven/django-tastypie.git@v0.9.9#egg=django-tastypie