ianBMS Setup
============

This article will guide you through the steps required in order to
deploy and run the ianBMS web application on a UNIX machine behind the
Apache 2.x web server.

First, you need to get the ianBMS web application sources. If for some
peculiar reason you weren't provided with a targz'ed source distro of
the application, then you will probably need to get (or even make) it
yourself. Go to the `ianbms subversion tags`__ for the latest stable
release (lookup the ``webif`` subdirectory).

.. __: http://trac.priv.inaccessnetworks.com/rsc/browser/ianbms/tags

Dependencies
------------

The ianBMS web app depends on a number of Python libraries either
homegrown (developed at inAccess that is) or 3rd-party:

- t3cl: The TEL3 configuration language library. Go to `t3cl
  subversion tags`__ of the TEL3 distro and get anything equal or
  greater than version **5.0**.
  
  .. __: http://trac.priv.inaccessnetworks.com/rsc/browser/tel3dist/t3cl/tags

- logtools: A library (and set of tools) for creating, accessing and graphing IOB data. This
  library is a custom wrapper over the rrdtool, and has the following dependencies:
  
  - python-dateutil_ version 1.3
  
  .. _python-dateutil: http://labix.org/python-dateutil
  
  - rrdtool_ 1.2.19 or greater

  .. _rrdtool: http://oss.oetiker.ch/rrdtool/

  - py-rrdtool_: Custom Python bindings for rrdtool (i.e. not the ones shipped in the
    rrdtool distribution).

  .. _py-rrdtool: http://sourceforge.net/projects/py-rrdtool/
  

  
- CherryPy_: The web application framework. Version should be
  **3.0.2** or higher. Chances are, your distro has not packaged a 3.x version
  of our (at least at the time of this writing) favourite webdev framework.
  
  .. _CherryPy: http://www.cherrypy.org
  
- Cheetah_: The template engine. Version should be **2.0.1** or
  higher. Both Debian and Ubuntu should provide such a package.
  
  .. _Cheetah: http://www.cheetahtemplate.org
  
- python-ldap_: Python library for communicating with LDAP
  servers. Version should be **2.2.1** or higher. I bet you will find
  the required version in a package under Debian / Ubuntu.
  
  .. _python-ldap: http://python-ldap.sourceforge.net/
  
- scgi_: The ``mod_csgi`` Apache 2.x module. You will be needing
  version **1.12** or higher. You will be able to find this library wrapped
  up in package under Debian or Ubuntu.

  .. _scgi: http://python.ca/scgi/ 
  
- flup_: A library providing a set of scgi servers. Version should be
  equal or greater that **1.0**. Not sure if Debian or Ubuntu provides the
  required version of this package.

  .. _flup: http://trac.saddi.com/flup
 
mod_csgi configuration
----------------------

A sample config file for the scgi apache module: ::
 
 /etc/apache2/mods-available/scgi.conf
 
 <IfModule mod_scgi.c>
   <Location "/ianbms">
     # Enable SCGI delegation
     SCGIHandler On
     # Delegate requests in the "/ianbms" path to daemon on local
     # server, port 4000
     SCGIServer 127.0.0.1:4000
   </Location>
 </IfModule>

For more info take a look at this__.

.. __: http://trac.priv.inaccessnetworks.com/rsc/wiki/PythonWebAppDev#install-and-configure-the-scgi-module
 
ianBMS installation
-------------------

I bet you know the drill: it's the usual ``python setup.py install``
stuff. Use the ``--prefix=INSTALL_DIR`` or ``--home=POSSIBLY_A_HOME_DIR``
to override the default installation path. Note that the init script that is automatically 
generated causes the web app server to chuid to the user that installed the app, unless of course it's 
root. For instance, if user "ianbms" installs the app, say in his home directory, then the init script
will cause the daemon to chuid to "ianbms". The setup attempts to install this init script under "/etc/init.d/",
and since user "ianbms" will probably not have write access to that directory, this will fail. So, the init script should 
be sudo-copied there. It can be found in the "scripts" directory of the app's source distro under the name "ianbms".

Configuring ianBMS
------------------

Look for the ``ianbms.conf`` file under the ``etc`` subdirectory of
your root installation directory. This is a sample configuration file
that will be used by default. If you want to put it in an another
place, be user to update the ``/etc/init.d/ianbms`` init script
accordingly.

Bringing the daemon to life
---------------------------

Simple as : ::

  /etc/init.d/ianbms start

In order to shut it down: ::

  /etc/init.d/ianbms stop

Testimonies
-----------

Deployment has already taken place on an Ubuntu machine running 7.04
Feisty Fawn; it worked like a charm. Debian Etch will get on your nerves because most of the packages needed don't play with Python 2.5. Moreover, you will definitely need the attached patch for compiling python-ldap for python 2.5!

Other useful stuff
------------------

You may read :trac:`PythonWebAppDev npat's notes on Python web development`.