--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Mon Nov 21 16:15:28 2011 +0100
@@ -0,0 +1,200 @@
+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::
+
+   # 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 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