INSTALL
=======

This package uses buildout for development and deployment. The use of
buildout allows for the creation of a self contained environment
containing application code and most of the required dependencies.


Prerequisites
-------------

1. Running MySQL server version >= 5.0
2. Python version >= 2.6
3. MySQLdb Python package

To install this application you need a recent python interpreter:
development and testing have been performed with Python 2.6, but
Python 2.7 should work as well.  MySQL and the Python MySQL connector
are not installed as part of the buildout recipe because it is much
easier to do so with the help of the OS package management software.

On a Debian or Debian like GNU-Linux installation you can easily
install all the required packages as follows::

   # apt-get install mysql-server python2.6 python2.6-mysqldb


Install
-------

The buildout recipe takes care of installing all the other required
component. For that you need to have an Internet connection, if you
access the Web through a proxy server remember to set it correctly for
you shell.  For a bash shell::

   # export http_proxy=http://proxy.example.net:3128/
   # export https_proxy=http://proxy.example.net:3128/

First download the buildout software itself::

   # python2.6 bootstrap.py --distribute

Then run the buildout recipe::

   # ./bin/buildout


Setup
-----

The application needs to know how to connect to your MySQL server.
Those information are stored in file in the application source code
directory.  Edit the configuration file::

   # edit ./src/ltpdarepo/config.py

and enter the required information.  Chose a database name at will:
this database will be created during the application initialization.
The user used in the connection should have administrative
capabilities on all the MySQL database.

To initialize the database use the provide LTPDA Repository
administration command line tool::

   # ./bin/admin install

Then create an administrator user to use in the first connection
through the Web interface::

   # ./bin/admin useradd username password
   # ./bin/admin grant username % admin

Upgrading from the PHP base Web interface is also possible.  It is
strongly recommended to perform a backup of the database before
attempting the upgrade.  Configure the application to connect to the
old administrative database (the old default administrative database
name is `ltpda_admin`) and run the upgrade procedure::

   # ./bin/admin upgrade

Help on the usage of the command line tool can be obtained with::

   # ./bin/admin help

For development and evaluation you can run the Web application within
an embedded HTTP server::

   # ./bin/run

and connect to it at the address http://localhost:5000/


Deployment
----------

For the deployment to a production server you do not want to use the
embedded simple HTTP server.  You can use any WSGI capable web server.
The easiest solution it is probably to use Apache `mod_wsgi`.

   .. TODO: complete this section