README.md

   1 BlueChips is a simple finance tracking application designed for small groups of
   2 people with shared expenses. It was designed and developed by groups of
   3 students who got tired of the headaches of managing lots of little payments
   4 between roommates.
   5
   6 Example Scenario
   7 ----------------
   8
   9 1. Larry lives with Curly and Moe.
  10 2. Larry gets the utility bill, and enters it as an expenditure on their
  11 BlueChips site. Everyone shares the utilities, so it's just an even split.
  12 3. A week later, Moe pays the rent. Curly has a smaller room, so he pays a
  13 smaller fraction of the rent.
  14 4. At any time, any user can visit the BlueChips site and see who needs to pay
  15 who how much in order to settle the books.
  16 5. After a few months, Moe has paid for a disproportionate amount of stuff, so
  17 the other roommates each make a transfer to Moe, and enter the amounts in
  18 BlueChips.
  19
  20 Additional Features
  21 -------------------
  22
  23 * Support for negative expenses
  24 * Uses any authentication mechanism which can set the REMOTE_USER environment
  25 variable, including authentication modules supported by Apache, nginx,
  26 lighttpd, and others.
  27 * Email notifications of changes (optional)
  28 * 100% test coverage
  29
  30 Installation and Setup
  31 ----------------------
  32
  33 Install ``BlueChips`` using easy_install::
  34
  35     easy_install BlueChips
  36
  37 Make a config file as follows::
  38
  39     paster make-config BlueChips config.ini
  40
  41 Tweak the config file as appropriate and then setup the application::
  42
  43     paster setup-app config.ini
  44
  45 Host the application behind an authentication layer which sets REMOTE_USER.
  46
  47 Apache Configuration
  48 --------------------
  49
  50 The recommended deployment platform for BlueChips is Apache, mod_wsgi, and any
  51 Apache module which provides authentication. Here is an example vhost
  52 configuration:
  53
  54     <VirtualHost bluechips.example.com:80>
  55         ServerName bluechips.example.com
  56
  57         WSGIScriptAlias / /var/www/bluechips.wsgi
  58         <Directory /var/www>
  59             Order deny,allow
  60             Allow from all
  61         </Directory>
  62
  63         <Location />
  64             AuthType Basic
  65             AuthName "Example BlueChips Site"
  66             AuthUserFile /etc/apache2/passwords
  67             Require valid-user
  68         </Location>
  69     </VirtualHost>
  70
  71 The ``bluechips.wsgi`` wrapper script looks just like:
  72
  73     from paste.deploy import loadapp
  74     application = loadapp('config:/var/www/ssl/production.ini')