Mercurial > hg > ltpdarepo

annotate README.rst @ 109:598f84f0db4e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extend test to exercise the permissions management interface. Doing so improve the 'privileges' function of the command line administration tool, cleanup the implementation and most importantly add CSRF protection that was missing for this form.
author Daniele Nicolodi <daniele@grinta.net>
date Tue, 23 Aug 2011 21:03:50 +0200
parents e640b2302fab
children dd5e5fc17a62
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
40
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
1 INSTALL
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
2 =======
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
3
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
4 This package uses buildout for development and deployment. The use of
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
5 buildout allows for the creation of a self contained environment
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
6 containing application code and most of the required dependencies.
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
7
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
8
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
9 Prerequisites
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
10 -------------
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
11
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
12 1. Running MySQL server version >= 5.0
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
13 2. Python version >= 2.6
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
14 3. MySQLdb Python package
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
15
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
16 To install this application you need a recent python interpreter:
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
17 development and testing have been performed with Python 2.6, but
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
18 Python 2.7 should work as well. MySQL and the Python MySQL connector
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
19 are not installed as part of the buildout recipe because it is much
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
20 easier to do so with the help of the OS package management software.
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
21
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
22 On a Debian or Debian like GNU-Linux installation you can easily
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
23 install all the required packages as follows::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
24
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
25 # apt-get install mysql-server python2.6 python2.6-mysqldb
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
26
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
27
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
28 Install
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
29 -------
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
30
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
31 The buildout recipe takes care of installing all the other required
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
32 component. For that you need to have an Internet connection, if you
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
33 access the Web through a proxy server remember to set it correctly for
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
34 you shell. For a bash shell::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
35
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
36 # export http_proxy=http://proxy.example.net:3128/
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
37 # export https_proxy=http://proxy.example.net:3128/
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
38
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
39 First download the buildout software itself::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
40
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
41 # python2.6 bootstrap.py --distribute
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
42
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
43 Then run the buildout recipe::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
44
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
45 # ./bin/buildout
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
46
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
47
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
48 Setup
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
49 -----
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
50
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
51 The application needs to know how to connect to your MySQL server.
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
52 Those information are stored in file in the application source code
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
53 directory. Edit the configuration file::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
54
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
55 # edit ./src/ltpdarepo/config.py
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
56
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
57 and enter the required information. Chose a database name at will:
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
58 this database will be created during the application initialization.
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
59 The user used in the connection should have administrative
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
60 capabilities on all the MySQL database.
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
61
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
62 To initialize the database use the provide LTPDA Repository
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
63 administration command line tool::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
64
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
65 # ./bin/admin install
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
66
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
67 Then create an administrator user to use in the first connection
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
68 through the Web interface::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
69
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
70 # ./bin/admin useradd username password
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
71 # ./bin/admin grant username % admin
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
72
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
73 Upgrading from the PHP base Web interface is also possible. It is
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
74 strongly recommended to perform a backup of the database before
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
75 attempting the upgrade. Configure the application to connect to the
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
76 old administrative database (the old default administrative database
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
77 name is `ltpda_admin`) and run the upgrade procedure::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
78
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
79 # ./bin/admin upgrade
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
80
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
81 Help on the usage of the command line tool can be obtained with::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
82
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
83 # ./bin/admin help
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
84
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
85 For development and evaluation you can run the Web application within
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
86 an embedded HTTP server::
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
87
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
88 # ./bin/run
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
89
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
90 and connect to it at the address http://localhost:5000/
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
91
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
92
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
93 Deployment
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
94 ----------
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
95
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
96 For the deployment to a production server you do not want to use the
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
97 embedded simple HTTP server. You can use any WSGI capable web server.
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
98 The easiest solution it is probably to use Apache `mod_wsgi`.
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
99
e640b2302fab Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff changeset
100 .. TODO: complete this section