Add a short description of the project here.

Getting Started - Development

Installing Tools and Dependencies

NOTE Please follow instructions carefully, as this project has been set up to avoid some of the common Django anti-patterns that you may be used to. Most notably, you'll need to define some environment variables.

Set up a virtual environment. Virtualenvwrapper is highly recommended.

mkvirtualenv invoices

The development requirements are defined in the requirements folder. Note that these are divided into separate requirements for production and local development.

Install development requirements with:

pip install -r requirements/local.txt

NOTE: After the first time installing requirements, be sure to go back and add version numbers for all the installed libraries. Do NOT leave unversioned items in a requirements file!

Install the LESS compiler (requires NodeJS)

npm install -g less

Install the watchr gem:

gem install watchr

Setting Environment Variables

Instead of keeping sensitive data like the project SECRET_KEY and database connection strings in settings files, or worse, keeping them in an unversioned local_settings module, we use environment variables to store these bits of data.

If you're using virtualenvwrapper, a convenient place to define these is in your postactivate script. Otherwise, they can go in e.g. ~/bash_profile.

The database connection is defined using a URL instead of separate parameters for database name, password, etc. For PostgreSQL, the string will look like:


For SQLite, use:


You can use a tool like this secret key generator to generate a SECRET_KEY.

NOTE: Be sure to keep a backup copy of the SECRET_KEY used in production!!

Here is a list of the required environment variables:


If you are using virtualenvwrapper, begin editing the postactivate script as follows:

vim bin/postactivate

Set the contents as follows:

# This hook is run after this virtualenv is activated.

export INVOICES_DATABASE_URL="postgresql://username:password@hostname:port/database";
export DJANGO_SETTINGS_MODULE="project.settings.local";
export PYTHONPATH="/path/to/invoices/apps";
export STRIPE_PUB_KEY='';

Setting``DJANGO_SETTINGS_MODULE`` to project.settings.local, is not strictly necessary, but helpful to avoid the need for the --settings flag to django management commands.

Similarly, setting PYTHONPATH lets you use instead of python

Running commands

Django's script is located in the apps directory. Any command can be run as follows:

python apps/ --settings=project.settings.local COMMAND

NOTE: If you've set the DJANGO_SETTINGS_MODULE environment variable, and set your PYTHONPATH, you can omit the --settings=... portion of any commands, and substitute for

For convenience, Invoices provides makefile targets for most common commands.

Initialize Your Database

Invoices uses South to manage database migrations.

make db

Start the Development Server

make server

Now bask in the glory of all the hard work you didn't have to do to get this far!

Editing Static Assets

TL;DR Edit LESS source files, compiled to CSS with make or make watch, and commit both the LESS source and the compiled CSS.

Static assets are stored in static/assets. We use LESS, which must be compiled to CSS. The Makefile default build target will invoke the lessc compiler.

To compile static assets:


To avoid having to run make constantly, running:

make watch

will automatically run the lessc compiler when any .less source files are changed.

Compiled CSS files must be committed to the repository, since the lessc compiler will not be available on production servers.

Running Tests

To run project tests and generate a coverage report, run:

make test

Open htmlcov/index.html in your browser to view the coverage report.


There is an experimental fabfile included, which will need to be edited to fit your needs. Change this documentation as required.