Mercurial > hg > ltpdarepo
annotate README.rst @ 207:dd5e5fc17a62
Update README.
| author | Daniele Nicolodi <daniele@grinta.net> |
|---|---|
| date | Thu, 17 Nov 2011 11:45:11 +0100 |
| parents | e640b2302fab |
| children | 0c2936ea34bf |
| 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, | |
| 63 ordinarily the `root` user. | |
|
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 |
|
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
109 Deployment |
|
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
110 ---------- |
|
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
111 |
|
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
112 For the deployment to a production server you do not want to use the |
| 207 | 113 embedded HTTP server. You can use any WSGI capable web server. The |
| 114 easiest solution it is probably to use Apache `mod_wsgi`. | |
| 115 | |
| 116 First enable the `mod_wsgi` Apache module:: | |
| 117 | |
| 118 # a2enmod wsgi | |
| 119 | |
| 120 A WSGI script is generated during the application install procedure. | |
| 121 To have Apache load it, copy this configuration snippet into your | |
| 122 Apache server configuration:: | |
| 123 | |
| 124 WSGIScriptAlias /ltpdarepo /srv/ltpdarepo/bin/wsgi | |
| 125 WSGIDaemonProcess ltpdarepo | |
|
40
e640b2302fab
Add short README with install and setup instructions.
Daniele Nicolodi <daniele@grinta.net>
parents:
diff
changeset
|
126 |
| 207 | 127 <Directory /srv/ltpdarepo/> |
| 128 WSGIProcessGroup ltpdarepo | |
| 129 WSGIApplicationGroup %{GLOBAL} | |
| 130 Order deny,allow | |
| 131 Allow from all | |
| 132 </Directory> | |
| 133 | |
| 134 Alias /ltpdarepo/static/foo/ /srv/ltpdarepo/src/ltpdarepo/static/ | |
| 135 | |
| 136 <Directory /srv/ltpdarepo/src/ltpdarepo/static/> | |
| 137 AllowOverride None | |
| 138 Order deny,allow | |
| 139 Allow from all | |
| 140 </Directory> | |
| 141 | |
| 142 In this example the application was installed in the `/srv/ltpdarepo/` | |
| 143 directory. Modify the configuration accordingly for your installation | |
| 144 folder. | |
| 145 | |
| 146 Then restart the Apache server:: | |
| 147 | |
| 148 # apache2ctl restart |