README 4.84 KB
Newer Older
Jakub Skoczen's avatar
Jakub Skoczen committed
1
- Localindices Suite
2
3
*For detailed notes on building a running development environment, see
doc/dev-notes.md*
4
  
Jakub Skoczen's avatar
Jakub Skoczen committed
5
-- COMPILING AND BUILDING
Jakub Skoczen's avatar
Jakub Skoczen committed
6

Jakub Skoczen's avatar
Jakub Skoczen committed
7
8
To compile and build the source you will Maven2 (http://maven.apache.org), on
debian/ubuntu you can install it via apt:
Jakub Skoczen's avatar
Jakub Skoczen committed
9

Jakub Skoczen's avatar
Jakub Skoczen committed
10
sudo apt-get install maven2
Jakub Skoczen's avatar
Jakub Skoczen committed
11

Jakub Skoczen's avatar
Jakub Skoczen committed
12
Having maven installed, type:
13

Jakub Skoczen's avatar
Jakub Skoczen committed
14
mvn install
Jakub Skoczen's avatar
Jakub Skoczen committed
15

Jakub Skoczen's avatar
Jakub Skoczen committed
16
17
18
You can either do it in the top-level ('localindices') dir to build all the 
submodules or in each submodule dir (e.g 'harvester') - in this case maven will
fetch module dependecies from ID's maven repo at http://maven.indexdata.com.
Jakub Skoczen's avatar
Jakub Skoczen committed
19

Jakub Skoczen's avatar
Jakub Skoczen committed
20
-- RUNNING HARVESTER AND HARVESTER-ADMIN
Jakub Skoczen's avatar
Jakub Skoczen committed
21

Jakub Skoczen's avatar
Jakub Skoczen committed
22
--- Harvester Admin
Jakub Skoczen's avatar
Jakub Skoczen committed
23

Jakub Skoczen's avatar
Jakub Skoczen committed
24
25
26
Admin is a simple JavaServer Faces web application and as such runs out-of-the-
box on a compliant JEE 5 Application Server (JSF 1.2 is included) e.g. Glassfish
V2.1.
Jakub Skoczen's avatar
Jakub Skoczen committed
27

Jakub Skoczen's avatar
Jakub Skoczen committed
28
29
Admin will also deploy to Tomcat6 as long as JSF jars are bundled within the 
*.war file (maven's dependency scope 'compile' instead of 'provided').
Jakub Skoczen's avatar
Jakub Skoczen committed
30

Jakub Skoczen's avatar
Jakub Skoczen committed
31
32
Makes sure to deploy the harvester before deploying the admin (otherwise there's
nothing to administer and you will get empty list).
Jakub Skoczen's avatar
Jakub Skoczen committed
33

Jakub Skoczen's avatar
Jakub Skoczen committed
34
For admin configuration (like he harvester's WS URL) look in the web.xml.
Jakub Skoczen's avatar
Jakub Skoczen committed
35

Jakub Skoczen's avatar
Jakub Skoczen committed
36
--- Harvester
Jakub Skoczen's avatar
Jakub Skoczen committed
37

Jakub Skoczen's avatar
Jakub Skoczen committed
38
---- MySQL
39

Jakub Skoczen's avatar
Jakub Skoczen committed
40
41
Make sure you have mysql installed, configured and running. Then create an empty
database and user (using mysql console):
42

Jakub Skoczen's avatar
Jakub Skoczen committed
43
44
    create database localindices;
    grant all privileges on localindices.* to 'localidxadm'@'localhost' 
45
46
                identified by 'localidxadmpass';

Dennis Schafroth's avatar
Dennis Schafroth committed
47
48
Then you can create the tables by running the following command:

49
$ mysql -u localidxadm -plocalidxadmpass localindices < sql/localindices.sql
Dennis Schafroth's avatar
Dennis Schafroth committed
50
51
52
53
54
55
56

However this is recomended to change the password used here. But it will also be required to change the password set 
in the webapps: 

- /etc/masterkey/harvester/harvester-context.xml
- /etc/masterkey/harvester-admin/harvester-admin-context.xml

57
58
You will then need to follow the upgrade path below to build a working installation.

Dennis Schafroth's avatar
Dennis Schafroth committed
59
60
61
62
63
64
65
66
-- Upgrading the Harvester and the MySQL database (V2.3 => V2.4) 

v 2.4 also adds new columns to the database, so it is required to add these fields to an existing V2.3 installation 

$ cd /usr/share/masterkey/harvester/sql/v2.4
$ mysqldump -u <localidxadm> -p<localidxadmpass> localindices > ~/localindices_backup.sql 
$ mysql -f -u <localidxadm> -p<localidxadmpass> localindices < 2013-08-15.sql

67
68
69
70
71
72
73
74
75
-- Upgrading the Harvester and the MySQL database (V2.2 => V2.3) 

v 2.3 also adds new columns to the database, so it is required to add these fields to an existing V2.2 installation 

$ cd /usr/share/masterkey/harvester/sql/v2.3
$ mysqldump -u <localidxadm> -p<localidxadmpass> localindices > ~/localindices_backup.sql 
$ mysql -f -u <localidxadm> -p<localidxadmpass> localindices < alter_2.3.sql 

-- Upgrading the Harvester and the MySQL database (V2.x => V2.2) 
76
77
78
79
80
81

V 2.2 adds some new columns to the database, which is required to be added before the harvester will run. 
Shut down tomcat and upgrade the packages. In the /usr/share/masterkey/harvester/sql/V2.2 there is a 
sql script that will alter the database. Before upgrading it is recommended to backup 
your existing database. Using the command line mysql client this can applied to the database like:

82
$ cd /usr/share/masterkey/harvester/sql/v2.2 
83
$ mysqldump -u <localidxadm> -p<localidxadmpass> localindices > ~/localindices_backup.sql 
84
$ mysql -f -u <localidxadm> -p<localidxadmpass> localindices < alter_2.2.sql 
85
86
87

After this, the tomcat can be started again. 

88
89
90
91
92
93
94
95
96
97
98
---- Configure Notifications 

The harvester can be configured to sent out notifications over e-mail. It requires that it has valid SMTP server 
and reciever address configured in a harvester properties file:

/usr/share/masterkey/harvester/WEB-INF/harvester.properties

harvester.smtp.server=localhost
harvester.smtp.from=harvester@localhost
harvester.smtp.to=operator@localhost

Dennis Schafroth's avatar
Dennis Schafroth committed
99
100
The SMTP server should accept mail to the domain used in to address. The harvester needs to be restarted to
make changes work. 
101

Jakub Skoczen's avatar
Jakub Skoczen committed
102
103
---- DataSource

Jakub Skoczen's avatar
Jakub Skoczen committed
104
105
106
107
108
(You can ignore this if you plan to run the harvester from within Netbeans)

If you plan to deploy on a standalone Glassfish, after setting up the MySQL DB, 
you have to add the pre-canned DS definiton using the Glassfish's 'asadmin' 
utility.
Jakub Skoczen's avatar
Jakub Skoczen committed
109
110
111
112
113
114

asadmin add-resources harvester/setup/sun-resources.xml

-- OTHER

--- Masterkey Data Access Layer
Jakub Skoczen's avatar
Jakub Skoczen committed
115

Jakub Skoczen's avatar
Jakub Skoczen committed
116
This project provides Masterkey specific database and web services connectivity.
Jakub Skoczen's avatar
Jakub Skoczen committed
117

Jakub Skoczen's avatar
Jakub Skoczen committed
118
119
The output jar file contains all entity (model) definitions (JavaBeans), 
abstracted database access (DAOs) and a generic RESTful WS client.
Jakub Skoczen's avatar
Jakub Skoczen committed
120

Jakub Skoczen's avatar
Jakub Skoczen committed
121
122
123
124
125
The RDBMS-based DAO implementation requires javax.persistence (JPA) and 
javax.transaction (JTA) packages, part of JEE5 specs. Those APIs are implemented
as a part of any Application Server and for the time being it is not possible to
deploy the harvester to non-JEE container like Tomcat/Jetty. This will be fixed 
soon by providing third-pary JPA library (hibernate, toplink) and dropping JTA.