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 be configured. Copy the example configuration
file to the expected configuration file location::

   # cp etc/ltpdarepo.ex etc/ltpdarepo

Then edit this file and enter the required information::

   # edit etc/ltpdarepo

Chose a database name at will: this database will be created during
the application initialization. The user used in the connection should
be an user with administrative capabilities on the MySQL database,
ordinarily the `root` user.

Remember to set an unique encryption key for the SECRET_KEY parameter.
This key is used in the application for generating cryptographic
hashes and the security of your application depends on selecting an
unique and unpredicible value for this key. A good way to obtain a
random string on an Unix machine is to execute::

   # dd bs=1024 count=16 if=/dev/random 2>/dev/null | md5

Note that in the default configuration notification emails are not
sent. To enable notification emails set the TESTING parameter to False.

To initialize the database use the 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> --admin true
   # ./bin/admin passwd <username> <password>

Upgrading from the PHP base Web interface is also possible. For doing
so configure the application to connect to the old administrative
database (the default administrative database name in the PHP
application is `ltpda_admin`) and run the upgrade procedure::

   # ./bin/admin upgrade

It is strongly recommended to perform a complete backup of the
database content before attempting the 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 in
standalone mode using the an embedded HTTP server. Execute::

   # ./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 HTTP server. You can use any WSGI capable web server. The
easiest solution it is probably to use Apache `mod_wsgi`.

First enable the `mod_wsgi` Apache module::

   # a2enmod wsgi

A WSGI script is generated during the application install procedure.
To have Apache load it, copy this configuration snippet into your
Apache server configuration::

   WSGIScriptAlias /ltpdarepo /srv/ltpdarepo/bin/wsgi
   WSGIDaemonProcess ltpdarepo

   <Directory /srv/ltpdarepo/>
       WSGIProcessGroup ltpdarepo
       WSGIApplicationGroup %{GLOBAL}
       Order deny,allow
       Allow from all
   </Directory>

   Alias /ltpdarepo/static/foo/ /srv/ltpdarepo/src/ltpdarepo/static/

   <Directory /srv/ltpdarepo/src/ltpdarepo/static/>    
       AllowOverride None
       Order deny,allow
       Allow from all
   </Directory>

In this example the application was installed in the `/srv/ltpdarepo/`
directory. Modify the configuration accordingly for your installation
folder.

Then restart the Apache server::

   # apache2ctl restart