Mercurial > hg > ltpdarepo

comparison README.txt @ 221:2de8715f0d59

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Better names and location for README.rst and COPYING.
author Daniele Nicolodi <daniele@grinta.net>
date Mon, 21 Nov 2011 16:15:28 +0100
parents README.rst@2a9af8163c46
children bec775b8c364
comparison
equal deleted inserted replaced
220:a5f5caf65dd5 221:2de8715f0d59
1 INSTALL
2 =======
3
4 This package uses buildout for development and deployment. The use of
5 buildout allows for the creation of a self contained environment
6 containing application code and most of the required dependencies.
7
8
9 Prerequisites
10 -------------
11
12 1. Running MySQL server version >= 5.0
13 2. Python version >= 2.6
14 3. MySQLdb Python package
15
16 To install this application you need a recent python interpreter:
17 development and testing have been performed with Python 2.6, but
18 Python 2.7 should work as well. MySQL and the Python MySQL connector
19 are not installed as part of the buildout recipe because it is much
20 easier to do so with the help of the OS package management software.
21
22 On a Debian or Debian like GNU-Linux installation you can easily
23 install all the required packages as follows::
24
25 # apt-get install mysql-server python2.6 python2.6-mysqldb
26
27
28 Install
29 -------
30
31 The buildout recipe takes care of installing all the other required
32 component. For that you need to have an Internet connection, if you
33 access the Web through a proxy server remember to set it correctly for
34 you shell. For a bash shell::
35
36 # export http_proxy=http://proxy.example.net:3128/
37 # export https_proxy=http://proxy.example.net:3128/
38
39 First download the buildout software itself::
40
41 # python2.6 bootstrap.py --distribute
42
43 Then run the buildout recipe::
44
45 # ./bin/buildout
46
47
48 Setup
49 -----
50
51 The application needs to be configured. Copy the example configuration
52 file to the expected configuration file location::
53
54 # cp etc/ltpdarepo.ex etc/ltpdarepo
55
56 Then edit this file and enter the required information::
57
58 # edit etc/ltpdarepo
59
60 Chose a database name at will: this database will be created during
61 the application initialization. The user used in the connection should
62 be an user with administrative capabilities on the MySQL database,
63 ordinarily the `root` user [1].
64
65 Remember to set an unique encryption key for the SECRET_KEY parameter.
66 This key is used in the application for generating cryptographic
67 hashes and the security of your application depends on selecting an
68 unique and unpredicible value for this key. A good way to obtain a
69 random string on an Unix machine is to execute::
70
71 # dd bs=1024 count=16 if=/dev/random 2>/dev/null | md5
72
73 Note that in the default configuration notification emails are not
74 sent. To enable notification emails set the TESTING parameter to False.
75
76 To initialize the database use the LTPDA Repository administration
77 command line tool::
78
79 # ./bin/admin install
80
81 Then create an administrator user to use in the first connection
82 through the Web interface::
83
84 # ./bin/admin useradd <username> --admin true
85 # ./bin/admin passwd <username> <password>
86
87 Help on the usage of the command line tool can be obtained with::
88
89 # ./bin/admin help
90
91 For development and evaluation you can run the Web application in
92 standalone mode using the an embedded HTTP server. Execute::
93
94 # ./bin/run
95
96 and connect to it at the address http://localhost:5000/
97
98
99 [1] It is also possible to run the application with an user having
100 reduced privileges. An user with the the minimum set of privileges
101 required for running the application may be obtained with the
102 following SQL commands::
103
104 CREATE USER <username>@'localhost' IDENTIFIED BY <password>;
105
106 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, CREATE VIEW,
107 CREATE USER ON *.* TO <username>@'localhost' WITH GRANT OPTION;
108
109 GRANT EXECUTE, CREATE TEMPORARY TABLES
110 ON <database>.* TO <username>@'localhost';
111
112 However, due to MySQL server limitations, this minimum set of
113 privileges allows the user to grant himself additional privileges, and
114 more generally to modify MySQL administrative tables. Therefore, this
115 is not an effective protection from security issues.
116
117 The initialization of the database and the upgrade procedure require
118 additional privileges than the ones listed above. Therefore, the
119 command line administration tool `install` and `upgrade` commands
120 allow to connect to the database with a different user than the one
121 specified in the configuration file, via the `--user` and `--password`
122 parameters. Example::
123
124 # ./bin/admin install --user root --password <password>
125
126 An user with the username and password specified in the configuration
127 file, and with the minimum set of privileges required for running the
128 application, may be created during the database initialization
129 procedure with the `--create-user` option of the `install` command::
130
131 # ./bin/admin install --create-user --user root --password <password>
132
133
134 Upgrade
135 -------
136
137 Upgrading from old versions of the application may require chenges to
138 the databases schema. To permorm the upgrade install and configure the
139 application and then run the upgrade procedure::
140
141 # ./bin/admin upgrade
142
143 If the application is configured to run with an user with limited
144 privileges, as detailed in the previous section, it is necessary to
145 use the `--user` and `--password` parameters of the `upgrade` commnand
146 to connect to the database with a user having administration
147 capabilities::
148
149 # ./bin/admin upgrade --user root --password <password>
150
151 Upgrading from the PHP base Web interface is also possible. For doing
152 that install and configure the application to connect to the old
153 administrative database (the default administrative database name for
154 the PHP application is `ltpda_admin`) and run the upgrade procedure.
155 It is recommended to backup the database content before attempting the
156 upgrade.
157
158
159 Deployment
160 ----------
161
162 For the deployment to a production server you do not want to use the
163 embedded HTTP server. You can use any WSGI capable web server. The
164 easiest solution it is probably to use Apache `mod_wsgi`.
165
166 First enable the `mod_wsgi` Apache module::
167
168 # a2enmod wsgi
169
170 A WSGI script is generated during the application install procedure.
171 To have Apache load it, copy this configuration snippet into your
172 Apache server configuration::
173
174 WSGIScriptAlias /ltpdarepo /srv/ltpdarepo/bin/wsgi
175 WSGIDaemonProcess ltpdarepo
176
177 <Directory /srv/ltpdarepo/>
178 WSGIProcessGroup ltpdarepo
179 WSGIApplicationGroup %{GLOBAL}
180 Order deny,allow
181 Allow from all
182 </Directory>
183
184 Alias /ltpdarepo/static/foo/ /srv/ltpdarepo/src/ltpdarepo/static/
185
186 <Directory /srv/ltpdarepo/src/ltpdarepo/static/>
187 AllowOverride None
188 Order deny,allow
189 Allow from all
190 </Directory>
191
192 In this example the application was installed in the `/srv/ltpdarepo/`
193 directory and has been configureted to be reached at the `/ltpdarepo`
194 path of the webserver. Modify the configuration to adjust for your
195 installation folder and for the path where the application should be
196 reached.
197
198 Then restart the Apache server::
199
200 # apache2ctl restart