- Localindices Suite
*For detailed notes on building a running development environment, see
doc/dev-notes.md*
  
-- COMPILING AND BUILDING

To compile and build the source you will Maven2 (https://maven.apache.org), on
debian/ubuntu you can install it via apt:

sudo apt-get install maven2

Having maven installed, type:

mvn install

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 https://maven.indexdata.com.

-- RUNNING HARVESTER AND HARVESTER-ADMIN

--- Harvester Admin

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.

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').

Makes sure to deploy the harvester before deploying the admin (otherwise there's
nothing to administer and you will get empty list).

For admin configuration (like he harvester's WS URL) look in the web.xml.

--- Harvester

---- MySQL

Make sure you have mysql installed, configured and running. Then create an empty
database and user (using mysql console):

    create database localindices;
    grant all privileges on localindices.* to 'localidxadm'@'localhost' 
                identified by 'localidxadmpass';

Then you can create the tables by running the following command:

$ mysql -u localidxadm -plocalidxadmpass localindices < sql/localindices.sql

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

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

-- 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

-- 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) 

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:

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

After this, the tomcat can be started again. 

---- 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

The SMTP server should accept mail to the domain used in to address. The harvester needs to be restarted to
make changes work. 

---- DataSource

(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.

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

-- OTHER

--- Masterkey Data Access Layer

This project provides Masterkey specific database and web services connectivity.

The output jar file contains all entity (model) definitions (JavaBeans), 
abstracted database access (DAOs) and a generic RESTful WS client.

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.