Mercurial > hg > ltpdarepo
view README.txt @ 228:694acf75447f
Fix HTML to make it W3C valid.
author | Daniele Nicolodi <daniele@grinta.net> |
---|---|
date | Thu, 24 Nov 2011 17:31:32 +0100 |
parents | b9f7aac3fd06 |
children | 0ac15efd8c17 |
line wrap: on
line source
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