Created: 2012-03-21 15:31
Updated: 2014-06-23 15:25
License: wtfpl


Django Base Template


  1. Start with a working deploy config.
  2. Pre-configure the apps that we use on every project.
  3. Follow best practices and conventions wherever possible.
  4. Develop with the same environment as the production server, from any machine.
  5. Provide useful fabric scripts for managing remote servers.


This project assumes that you want to use the following:

Project Initialization

With Django 1.4, you can use the new project template feature. From the console: startproject --template= --extension=py,mkd project_name Where project_name is the name of your app.

Otherwise you can just fork this repo and manually change any instances of {{ project_name }} to the name of your app. This variable exists in the following files:

  • README.mkd
  • deploy/
  • deploy/

Remove everything above this line.

{{ project_name }}


This project requires the following:

  1. An Ubuntu 11.10 server
  2. Vagrant
  3. pip

Included Apps

Initial setup

pip install fabric
vagrant up
fab dev bootstrap

This will take awhile (like, awhile). You may be prompted for input during the fab dev bootstrap step, so you will need to bear it out.

When the initial setup is finished, you will have a running server instance at localhost:8888.


Use vagrant to manage the dev server. Commands include:

  • vagrant up: start server
  • vagrant reload: reload server
  • vagrant suspend: suspend server
  • vagrant destroy: destroy VM (useful for testing the bootstrap command)
  • vagrant ssh: shell into dev server

Get the full list of commands by running vagrant -h

Local Development Server

To access django's local dev server, you have two options - you can spend several hours setting up your MacBook (and helping everyone else on the project get set up), or you can use the environment that we've already built from inside the Vagrant VM.

If you choose the latter option, follow you can use run fab dev run_dev_server, which is a shortcut for:

vagrant ssh
./ runserver_plus

You should now be able to access the local dev server on localhost:8000


This project uses fabric for deployment + provisioning. Several commands are already included (replace 'xxx' with the name of your env from

  • fab xxx bootstrap: Install dependencies, deploy initial app to xxx.
  • fab xxx deploy: Deploy latest git commit to xxx server.
  • fab xxx run_dev_server: Run the development server on port 8000.
  • fab xxx sync_db:xxx,yyy: Copy the database from environment xxx to environment yyy
  • fab xxx rollback: Roll back to previous deploy on xxx.


  • Do NOT use sudo when running pip commands. We use pythonbrew to avoid that mess.
  • Nginx, uWSGI, and Postgres run as the user specified in

Organizational Conventions


Settings that are common to each environment are specified in deploy/ For example, each environment will share the base INSTALLED_APPS list, so that is defined in deploy/

Each environment will have its own unique settings (i.e. DEBUG). These settings should be defined in deploy/

Directory Structure


This directory contains configuration templates that will be formatted with the local settings for the target server.


Files in this directory are pushed to the target server when running fab xxx deploy.


This is where to place apps created with the startapp command.


Static assets, to be collected upon ./ collectstatic.


For miscellaneous helper scripts that don't belong to any particular app.


This folder will contain the files generated by ./ collectstatic. This directory is git-ignored, and the static collection takes place on the server upon deployment.


Django template overrides.


File uploads for local development. This directory is git-ignored - each server will have its own persistent uploads folder.


Useful fabric scripts.

Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more