Mercurial > hg > ltpdarepo
annotate README.rst @ 209:0c2936ea34bf
Document the unprivileged user possibility in the README.
author | Daniele Nicolodi <daniele@grinta.net> |
---|---|
date | Thu, 17 Nov 2011 11:47:28 +0100 |
parents | dd5e5fc17a62 |
children | 2a9af8163c46 |
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 |
207 | 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:: | |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
57 |
207 | 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, | |
209
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
63 ordinarily the `root` user [1]. |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
64 |
207 | 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:: | |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
70 |
207 | 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:: | |
40
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 install |
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 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
|
82 through the Web interface:: |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
83 |
207 | 84 # ./bin/admin useradd <username> --admin true |
85 # ./bin/admin passwd <username> <password> | |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
86 |
207 | 87 Upgrading from the PHP base Web interface is also possible. For doing |
88 so configure the application to connect to the old administrative | |
89 database (the default administrative database name in the PHP | |
90 application is `ltpda_admin`) and run the upgrade procedure:: | |
40
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 # ./bin/admin upgrade |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
93 |
207 | 94 It is strongly recommended to perform a complete backup of the |
95 database content before attempting the upgrade. | |
96 | |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
97 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
|
98 |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
99 # ./bin/admin help |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
100 |
207 | 101 For development and evaluation you can run the Web application in |
102 standalone mode using the an embedded HTTP server. Execute:: | |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
103 |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
104 # ./bin/run |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
105 |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
106 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
|
107 |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
108 |
209
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
109 [1] An user with the the minimum set of privileges required for |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
110 running the application may be obtained with the following SQL |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
111 commands:: |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
112 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
113 CREATE USER <username>@'localhost' IDENTIFIED BY <password>; |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
114 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
115 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, CREATE VIEW, |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
116 CREATE USER ON *.* TO <username>@'localhost' WITH GRANT OPTION; |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
117 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
118 GRANT EXECUTE, CREATE TEMPORARY TABLES |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
119 ON <database>.* TO <username>@'localhost'; |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
120 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
121 However, due to MySQL server limitations, this minimum set of |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
122 privileges allows the user to grant himself additional privileges, and |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
123 more generally to modify MySQL administrative tables. Therefore, this |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
124 is not an effective protection from security issues. |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
125 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
126 The initialization of the database and the upgrade procedure require |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
127 additional privileges than the ones listed above. Therefore, the |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
128 command line administration tool `install` and `upgrade` commands |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
129 allow to connect to the database with a different user than the one |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
130 specified in the configuration file, via the `--user` and `--password` |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
131 parameters. Example:: |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
132 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
133 # ./bin/admin install --user root --password <password> |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
134 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
135 An user account with username and password specified in the |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
136 configuration file, and with minimum privileges suitable for running |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
137 the application, may be created during the database initialization |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
138 procedure with the `--create-user` option of the `install` command:: |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
139 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
140 # ./bin/admin install --create-user --user root --password <password> |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
141 |
0c2936ea34bf
Document the unprivileged user possibility in the README.
Daniele Nicolodi <daniele@grinta.net>
parents:
207
diff
changeset
|
142 |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
143 Deployment |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
144 ---------- |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
145 |
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
146 For the deployment to a production server you do not want to use the |
207 | 147 embedded HTTP server. You can use any WSGI capable web server. The |
148 easiest solution it is probably to use Apache `mod_wsgi`. | |
149 | |
150 First enable the `mod_wsgi` Apache module:: | |
151 | |
152 # a2enmod wsgi | |
153 | |
154 A WSGI script is generated during the application install procedure. | |
155 To have Apache load it, copy this configuration snippet into your | |
156 Apache server configuration:: | |
157 | |
158 WSGIScriptAlias /ltpdarepo /srv/ltpdarepo/bin/wsgi | |
159 WSGIDaemonProcess ltpdarepo | |
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
160 |
207 | 161 <Directory /srv/ltpdarepo/> |
162 WSGIProcessGroup ltpdarepo | |
163 WSGIApplicationGroup %{GLOBAL} | |
164 Order deny,allow | |
165 Allow from all | |
166 </Directory> | |
167 | |
168 Alias /ltpdarepo/static/foo/ /srv/ltpdarepo/src/ltpdarepo/static/ | |
169 | |
170 <Directory /srv/ltpdarepo/src/ltpdarepo/static/> | |
171 AllowOverride None | |
172 Order deny,allow | |
173 Allow from all | |
174 </Directory> | |
175 | |
176 In this example the application was installed in the `/srv/ltpdarepo/` | |
177 directory. Modify the configuration accordingly for your installation | |
178 folder. | |
179 | |
180 Then restart the Apache server:: | |
181 | |
182 # apache2ctl restart |