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.