$Id: README,v 1.24 2007-11-28 16:58:12 mike Exp $

Masterkey is a metasearch portal based on Pazpar2. It is implemented in PHP5,
Java Script and XSLT. 

Copyright (C) 2007, Index Data. See the file LICENSE for details.


MASTERKEY DESCRIPTION

This source tree contains the following Debian packages:
 - masterkey (virtual package)
 - masterkey-core
 - masterkek-gui-default
 - masterkey-gui-example
 - masterkey-auth

The default setup contained in these Debian packages require also
installation of the auxillary packages
- jquery 
- pazpar2 
- mysql-server
on the same server. A distributed layout is possible, though not yet
fully tested. 





QUICK DEBIAN INSTALL OF ALL MASTERKEY MODULES ON ONE BOX

Change your /etc/apt/sources.list to include Index Data's Debian repository


## Indexdata stuff
deb http://ftp.indexdata.dk/debian etch main
deb-src http://ftp.indexdata.dk/debian etch main

Then do 

> sudo apt-get update
> sudo apt-get dist-upgrade
> sudo apt-get install apache2-mpm-worker
> sudo apt-get install masterkey


Remember to enable PHP directory index display by setting 

<IfModule mod_dir.c>
    DirectoryIndex index.php
</IfModule

in your relevant main apache config or virtual host config.

Make sure that the following modules are loaded into Apache:

/etc/apache2/mods-enabled/actions.load
/etc/apache2/mods-enabled/alias.load
/etc/apache2/mods-enabled/dir.load
/etc/apache2/mods-enabled/env.load
/etc/apache2/mods-enabled/php5.conf
/etc/apache2/mods-enabled/php5.load
/etc/apache2/mods-enabled/proxy.conf
/etc/apache2/mods-enabled/proxy.load
/etc/apache2/mods-enabled/setenvif.load

For example, load the PHP5 module by issuing

 a2enmod php5


Then restart apache2 

/etc/init.d/apache2 force-reload

.. and surf into 

http://localhost/masterkey-gui-default

Enjoy!


SOURCE MASTERKEY AND APACHE CONFIGURATION FILES

Example default GUI configuration files are found in the source tarball at:

./mk-if/public/etc/masterkey-gui-default.conf

Other configuration files are found at
./mk-auth/conf/manage.conf

Default values will probably be fine - they assume that ...


Example Apache configuration files are found in the source tarball at:

./mk-if/etc/masterkey-core-apache-alias.conf
./mk-if/public/etc/masterkey-gui-default-apache-alias.conf
./mk-if/public/etc/masterkey-gui-default-apache-directory.conf
./mk-if/public/etc/masterkey-gui-default-apache-virtual.conf


DEBIAN PACKAGE MASTERKEY AND APACHE CONFIG FILES LOCATIONS

The Debian install places for masterkey config files and
masterkey-related apache config files are

/etc/masterkey-core-apache-alias.conf
/etc/masterkey-gui-default-apache-alias.conf
/etc/masterkey-gui-default-apache-directory.conf
/etc/masterkey-gui-default-apache-virtual.conf
/etc/masterkey-gui-default.conf


In addition, the Debian installation places symlinks at

/etc/apache2/conf.d/masterkey-core-apache-alias.conf
/etc/apache2/conf.d/masterkey-gui-default-apache-alias.conf

and restarts the servers. 

Remember to enable PHP directory index display by setting 

<IfModule mod_dir.c>
    DirectoryIndex index.php
</IfModule

in your relevant main apache config or virtual host config.

See section "Debian Install Of Masterkey Authentication Package For Distributed Usage"
for further details.



DEBIAN INSTALL OF MASTERKEY CORE AND DEFAULT GUI FOR DISTRIBUTED USAGE

Change your /etc/apt/sources.list to include Index Data's Debian repository


## Indexdata stuff
deb http://ftp.indexdata.dk/debian etch main
deb-src http://ftp.indexdata.dk/debian etch main

Then do 

> sudo apt-get update
> sudo apt-get dist-upgrade
> sudo apt-get install apache2-mpm-worker libapache2-mod-php5
> sudo apt-get install pazpar2-doc pazpar2 pazpar2-apache2
> sudo apt-get install masterkey-core masterkey-gui-default 


See above section for Apache and config file issues



DEBIAN INSTALL OF MASTERKEY AUTHENTICATION PACKAGE FOR DISTRIBUTED USAGE


> sudo apt-get install masterkey-auth

Edit your GUI config file - for example
/etc/masterkey-gui-default.conf - to enable authentification like
this:

  <!-- resource selection requires auth -->
  <setting name="auth" value="yes"/>
  <setting name="resource_select" value="yes"/>
  <setting name="multi_lang" value="no"/>
  <setting name="profile_edit" value="no"/>


Masterkey-auth requires a running MySQL database to provide the
necessary data. The standard setup assumes that MySQL runs on the same
box as masterkey-auth, but you can use any remote box if you prefer.

> sudo apt-get install mysql-server

Edit your /etc/masterkey-auth.conf config file as root to point to a
running instance of MySQL, choose your database name, login name and
password to your liking.

Make sure that the database and the mysql user exists with the same
credentials as you just have set in /etc/masterkey-auth.conf by running

> mysql --user=root --password=your_mysql_root_password mysql
 
(If you have no MySQL root password yet, issue
> mysqladmin -u root password your_mysql_root_password
first)

mysql> GRANT ALL PRIVILEGES ON your_DB_name.* TO 'masterkey'@'localhost' 
       IDENTIFIED BY 'masterkey_password';
mysql> exit

(In case of a remote MySQL you might want to give remote priviledges
from specific IP numbers as well - read the fine MySQL manual to
figure out how to do this)

> mysql --user=masterkey --password=masterkey_password
mysql> CREATE DATABASE your_db_name;
mysql> exit

Then we need to create the correct table structure by dumping SQL
statements into the database.

> mysql --user=masterkey --password=masterkey_password
  your_db_name < /usr/share/masterkey-auth/data/masterkey-drop-add-tables.sql

From there, you have to add table data by hand.

Alternative: hack /etc/masterkey-auth.conf to point to a MySQL
database on another box which has already the required data.

Alternative2: Export from an existing good database, 

> mysqldump --user=masterkey --password=masterkey_password
  your_db1_name > your_db1_backup.sql

and inject into new database using 

> mysql --user=masterkey --password=masterkey_password
  your_db2_name < your_db1_backup.sql

If you only want to know the table structure, run 
> mysqldump --user=masterkey --password=masterkey_password masterkey | grep -v INSERT | grep -v DROP 

Updating to a new version of the table structure is done by running

> mysql --user=masterkey --password=masterkey_password masterkey < /usr/share/masterkey-auth/data/masterkey-update-tables-1.sql 


ENABELING THE MASTERKEY AUTH MANAGEMENT INTERFACE

Per default, access to the authentication management interface is disabled, 
except for any browser coming from localhost. You need to edit
  
/etc/masterkey-auth-apache-alias.conf 

This part:

<Directory /usr/share/masterkey-auth/public/manage>
  Order Deny,Allow
  Deny from All
  Allow from 127.0.0.1
</Directory>

needs replacing with the apache directives you want to enforce.
Then run 

> sudo /etc/init.d/apache2 reload



BUILDING MASTERKEY DEBIAN PACKAGES FROM CVS

You need at least the PHP Debian packages installed which are listed
in the debian/control file.

On your package build box you need to have some PEAR modules installed
which do not exist as Debian packages. 

$> pear config-set preferred_state beta

$> sudo pear channel-discover pear.phing.info
$> sudo pear install phing/phing

$> sudo pear channel-discover pear.phpdb.org
$> sudo pear install phpdb/propel_generator
$> sudo pear install phpdb/propel_runtime

Then building a distribution tarball is easy;

$> make
$> make dist

Move the distribution tarball to a clean box (for example 'etch') with
no PHP packages installed except the required Debian packages, unpack
and build Debian packages:

$> scp masterkey-0.3.1.tar.gz etch:
$> ssh -X etch
$> tar xvzf masterkey-0.3.1.tar.gz
$> cd masterkey-0.3.1
$> make debian

The resulting Debian packages are created in the mother
directory. Check them for compliance to Debian conventions by issuing 

$> linda ../masterkey*.deb
$> lintian ../masterkey*.deb

Check the contents of these using

$> dpkg --contents ../masterker...deb

Check proper install using

$> sudo dpkg -i ../masterkey*.deb

Test thoroughly by surfing into 

http://localhost/masterkey-gui-default


BUILDING YOUR OWN MASTERKEY-LIKE GUI INTERFACE

> sudo apt-get install masterkey-gui-example
> cd /var/www/your/sandbox
> tar xvzf /usr/share/masterkey-gui-example/masterkey-gui-example.tar.gz

Set up copies of /etc/masterkey-gui-default*.conf config files with the correct
gui portal directory edited into them, softlink to /etc/apache2/conf.d/ 
or /etc/apache2/sites-available, reload apache2 configs, ... and ..
start happy hacking on your new tar-ball based GUI. 



DEBUGGING MASTERKEY INSTALLATIONS

1) PazPar2 acessability:

  Check that   
  http://localhost/pazpar2/search.pz2?command=init
  is available, and is running a PazPar2 web service

  If not, check that 
  http://localhost:8004/search.pz2?command=init
  is up and running, and check that the Apache proxy
  module is loaded and forwarding correctly.

2) JavaScript acessability:

  Honestly, you _need_ Firefox with Firebug enabled to debug your JS problems! 