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 [1].

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>

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/


[1] It is also possible to run the application with an user having
reduced privileges. An user with the the minimum set of privileges
required for running the application may be obtained with the
following SQL commands::

    CREATE USER <username>@'localhost' IDENTIFIED BY <password>;

    GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, CREATE VIEW,
    CREATE USER ON *.* TO <username>@'localhost' WITH GRANT OPTION;

    GRANT EXECUTE, CREATE TEMPORARY TABLES
    ON <database>.* TO <username>@'localhost';

However, due to MySQL server limitations, this minimum set of
privileges allows the user to grant himself additional privileges, and
more generally to modify MySQL administrative tables.  Therefore, this
is not an effective protection from security issues.

The initialization of the database and the upgrade procedure require
additional privileges than the ones listed above. Therefore, the
command line administration tool `install` and `upgrade` commands
allow to connect to the database with a different user than the one
specified in the configuration file, via the `--user` and `--password`
parameters. Example::

    # ./bin/admin install --user root --password <password>

An user with the username and password specified in the configuration
file, and with the minimum set of privileges required for running the
application, may be created during the database initialization
procedure with the `--create-user` option of the `install` command::

    # ./bin/admin install --create-user --user root --password <password>


Upgrade
-------

Upgrading from old versions of the application may require chenges to
the databases schema. To permorm the upgrade install and configure the
application and then run the upgrade procedure:: 

   # ./bin/admin upgrade

If the application is configured to run with an user with limited
privileges, as detailed in the previous section, it is necessary to
use the `--user` and `--password` parameters of the `upgrade` commnand
to connect to the database with a user having administration
capabilities::

    # ./bin/admin upgrade --user root --password <password>

Upgrading from the PHP base Web interface is also possible. For doing
that install and configure the application to connect to the old
administrative database (the default administrative database name for
the PHP application is `ltpda_admin`) and run the upgrade procedure.
It is recommended to backup the database content before attempting the
upgrade.


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. On Debian and Debian
derivate GNU-Linux distributions you can simply do::

   # a2enmod wsgi

On other platforms, add the following configuration directive,
properly adjusted for your instllation paths, to the Apache
configuration file::

   LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so

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/ /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 and has been configureted to be reached at the `/ltpdarepo`
path of the webserver. Modify the configuration to adjust for your
installation folder and for the path where the application should be
reached.

Then restart the Apache server::

   # apache2ctl restart