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.