Development¶

Getting the coffeestats source¶

To start development on coffeestats you have several options for getting a working environment. Everything starts with a git clone:

git clone https://github.com/coffeestats/coffeestats-django.git

Development environment setup¶

We recommend using Vagrant to have a completely isolated working environment. You can also use virtualenv if you don’t want the overhead of a full virtual machine.

If you do not use Vagrant you are on your own when it comes to database setup and definition of environment variables.

Vagrant¶

To use Vagrant you can just run:

vagrant up

from within your git working copy. Just wait a few minutes (depending on the speed of your network connection and system performance) and you will have a running coffeestats instance available at http://localhost:8080/.

You can then just work with the files in your working copy. If you want to perform service restarts or any other system administration in your coffeestats virtual machine you can use:

vagrant ssh

A fresh Vagrant VM has everything setup and all dependendencies installed in a virtualenv in ~vagrant/coffeestats-venv/. If you need to update the dependencies you can use:

sudo salt-call state.highstate

The Salt invocation will take care of restarting uwsgi and nginx if needed.

Virtualenv¶

If you want to avoid the overhead of a virtual machine you can also use virtualenv to setup your development environment.

You will need a PostgreSQL database and have to take care of setting the necessary environment variables for the Django settings yourself. Look at the Salt state descriptions to get an idea what has to be done.

Virtualenv Only¶

First, make sure you are using virtualenv. Once that’s installed, create your virtualenv:

virtualenv ~/coffeestats-venv
cd coffeestats && add2virtualenv `pwd`

Use the following command to work with the virtual environment later:

. ~/coffeestats-venv/bin/activate

Virtualenv with virtualenvwrapper¶

In Linux and Mac OSX, you can install virtualenvwrapper which will take care of managing your virtual environments and adding the project path to the site-directory for you:

mkvirtualenv coffeestats-dev
cd coffeestats && add2virtualenv `pwd`

To work with the virtual environment later use:

workon coffeestats-dev

Installation of dependencies¶

If you use a virtual environment you have to install the necessary dependencies. You need Python and PostgreSQL development headers installed before the installation of the development dependencies will work. On Debian based systems you can use apt to install both:

sudo apt-get update
sudo apt-get install libpq-dev python-dev

Development dependencies are defined in requirements/local.txt. Use the following command to install the dependencies in your currently activated environment:

pip install -r requirements/local.txt

Development session¶

If you are using Vagrant as recommended you can start a development session by opening a terminal and an editor session inside of your coffeestats clone. In the terminal session you run:

vagrant up
# ... wait for the VM to start
vagrant ssh
# ... should now be logged in to your vagrant VM
. csdev.sh
. coffeestats-venv/bin/activate
cd /vagrant/coffeestats

If you are not familiar with Django you should start with the Django tutorial.

Directory structure¶

.

base directory with .gitignore, .travis.yml, CONTRIBUTORS.txt, LICENSE.txt, README.txt, Vagrantfile

coffeestats

base directory for the project code and other project files

assets

directory for static files to be served by a web server. This directory is populated by manage.py collectstatic

caffeine

directory containing the caffeine app. This app contains the main model classes, code for generating statistics as well as the views used to display the web user interface

caffeine_api_v1

directory containing the REST API v1.0 implementation

coffeestats

directory containing the configuration code for coffeestats like the main URL configuration, settings for different environments (local, test, production) and the WSGI application entry point

core

directory containing code to be used by multiple Django apps

functional_tests

directory containing functional tests based on Selenium

static

directory containing subdirectories with static assets for coffeestats

css

Sass sources as well as generated and hand-written CSS

common: common styling like fonts, colors, icons and mediaqueries
components: Sass components / pageareas which will be imported and compiled in the caffeine.scss
fonts: font files

images

icons and other image files

js

JavaScript libraries and a common scripts.js (app specific JavaScript code is kept in static/<appname>/js subdirectories of the corresponding apps)

templates

directory containing the HTML and email text templates

docs

directory containing the Sphinx documentation source

requirements

directory containing pip requirements files

salt

directory containing the Salt states and pillars that are used to provision the Vagrant VM

CSS generation with Sass¶

We use Sass to generate our Cascading Style Sheets (CSS) file. Sass is a CSS generator feeded by a CSS like language. On Debian systems you can install Sass by running:

sudo apt-get install ruby-sass

On other systems with a Ruby Gems installation you can run:

gem install sass

During development you can continuosly run sass to generate the coffeestats/static/css/caffeine.css:

cd coffeestats/static
sass --watch css/caffeine.scss:css/caffeine.css

You can also run sass before committing your changes on coffeestats/static/css/caffeine.scss manually:

cd coffeestats/static
sass css/caffeine.scss:css/caffeine.css

Warning

Please be aware that all changes in css/caffeine.css you make manually will be overwritten the next time somebody runs Sass. You should always modify css/caffeine.scss instead.

SASS files which look like this: _filename.scss are for imports in other sass files. Sass won’t generate own css files of them.