README.rst

   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 Demo
   7 ----
   8
   9 If you want to try out BlueChips, you can go to http://demo.bluechi.ps
  10
  11 Example Scenario
  12 ----------------
  13
  14 1. Larry lives with Curly and Moe.
  15 2. Larry gets the utility bill, and enters it as an expenditure on
  16    their BlueChips site. Everyone shares the utilities, so it's just an
  17    even split.
  18 3. A week later, Moe pays the rent. Curly has a smaller room, so he
  19    pays a smaller fraction of the rent.
  20 4. At any time, any user can visit the BlueChips site and see who
  21    needs to pay who how much in order to settle the books.
  22 5. After a few months, Moe has paid for a disproportionate amount of
  23    stuff, so the other roommates each make a transfer to Moe, and
  24    enter the amounts in BlueChips.
  25
  26 Additional Features
  27 -------------------
  28
  29 * Support for negative expenses
  30 * Uses any authentication mechanism which can set the REMOTE_USER
  31   environment variable, including authentication modules supported by
  32   Apache, nginx, lighttpd, and others.
  33 * Email notifications of changes (optional)
  34 * 100% test coverage
  35
  36 Installation and Setup
  37 ----------------------
  38
  39 Install ``BlueChips`` using easy_install::
  40
  41     easy_install BlueChips
  42
  43 Make a config file as follows::
  44
  45     paster make-config BlueChips config.ini
  46
  47 Tweak the config file as appropriate and then setup the application::
  48
  49     paster setup-app config.ini
  50
  51 Host the application behind an authentication layer which sets REMOTE_USER.
  52
  53 Apache Configuration
  54 --------------------
  55
  56 The recommended deployment platform for BlueChips is Apache, mod_wsgi, and any
  57 Apache module which provides authentication. Here is an example vhost
  58 configuration::
  59
  60     <VirtualHost bluechips.example.com:80>
  61         ServerName bluechips.example.com
  62
  63         WSGIScriptAlias / /var/www/bluechips.wsgi
  64         <Directory /var/www>
  65             Order deny,allow
  66             Allow from all
  67         </Directory>
  68
  69         <Location />
  70             AuthType Basic
  71             AuthName "Example BlueChips Site"
  72             AuthUserFile /etc/apache2/passwords
  73             Require valid-user
  74         </Location>
  75     </VirtualHost>
  76
  77 The ``bluechips.wsgi`` wrapper script looks just like::
  78
  79     from paste.deploy import loadapp
  80     application = loadapp('config:/var/www/ssl/config.ini')
  81
  82 Acknowledgments
  83 ---------------
  84
  85 BlueChips is the latest in a long line of software to make managing
  86 group finances easier, and would not be possible without the
  87 intellectual inspiration of those predecessors.
  88
  89 CUTCAT's `accounting software`_ started the trend of
  90 software-based accounting mechanisms. It inspired a re-implementation
  91 as a curses script by `Nelson Elhage`_, which introduced the
  92 notion of "pushing expenditures" to simplify transfers. The algorithm
  93 used in BlueChips for settling the books is directly cargo-culted from
  94 Nelson's implementation.
  95
  96 .. _accounting software: http://cutc.at/accounting-software.html
  97 .. _Nelson Elhage: http://nelhage.com/