# HG changeset patch
# User Daniele Nicolodi <daniele@grinta.net>
# Date 1309300807 -7200
# Node ID e640b2302fab1cb9c7f7025c71504e44272b9a83
# Parent  532d9d070ef5bc091fd3d6f70e184dce78b178ab
Add short README with install and setup instructions.

diff -r 532d9d070ef5 -r e640b2302fab README.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.rst	Wed Jun 29 00:40:07 2011 +0200
@@ -0,0 +1,100 @@
+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