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.
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:
cdvirtualenv vim bin/postactivate
Set the contents as follows:
#!/bin/bash # This hook is run after this virtualenv is activated. export INVOICES_DATABASE_URL="postgresql://username:password@hostname:port/database"; export INVOICES_SECRET_KEY=""; export DJANGO_SETTINGS_MODULE="project.settings.local"; export PYTHONPATH="/path/to/invoices/apps"; export HARVEST_SUBDOMAIN=''; export HARVEST_USERNAME=''; export HARVEST_PASSWORD=''; export STRIPE_SECRET_KEY=''; 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 django-admin.py instead of python manage.py.
Running manage.py commands
Django's manage.py script is located in the apps directory. Any manage.py command can be run as follows:
python apps/manage.py --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 manage.py commands, and substitute django-admin.py for manage.py.
For convenience, Invoices provides makefile targets for most common manage.py commands.
Initialize Your Database
Invoices uses South to manage database migrations.
Start the Development 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:
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.
To run project tests and generate a coverage report, run:
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.