Mercurial > hg > ltpdarepo

annotate README.rst @ 171:f1cc11dc09b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Reflect markup changes into doctests.
author Daniele Nicolodi <daniele@grinta.net>
date Sun, 06 Nov 2011 23:15:25 +0100
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