Alkindi Application CDs		June 1, 2001
----------------------------------------

*** If you have trouble viewing this document, try turning on "word wrap." ***

Contents of this README file:

1. General Description
2. What's included on these CDs
3. What's not included here
4. Main Directories
5. Deployment Notes
6. Running the Matlab Demo 

******************


1. General Description

This CD contains the Alkindi application archive of software Alkindi developed from June 2000 to May 2001.

-------

2. What's included

The application archive include the Recommendation Engine code and user interface code written for the Alkindi website operated during that time. 

In addition, it contains software necessary to deploy and run Alkindi's software. This software consists of three types of servers: an instance of an oracle database server (back end), a jBoss EJB server (middleware), and Caucho Resin JSP server (front end web server).

This software has been modified from the form used on the Alkindi website to allow it all to run together on one machine.

-------


3. What's not included

Specification documents and source code for Alkindi software are not included here. Source code for some servers is included; see section (4) below.

Production network design notes are part of the specification documents and are not included here.


-------

4. Main Directories

/alkindi/httpd		The Alkindi User Interface code

/alkindi/java		Java & Enterprise Java kits used by Resin & jBoss

/alkindi/jBoss		jBoss middleware server

/alkindi/lib		Shared libraries

/alkindi/resin		The Resin web server, supporting Java Server Pages

/alkindi/scripts	BASH shell scripts for managing the Resin & jBoss servers

/alkindi/Tests		Code to test the setup of the Middleware & Database

/matlab_demo		Matlab demo code & data

/oracle_export		An export of the Oracle database used by the Recommendation Engine

/other_software		Unmodified jBoss, resin and Java SDK distributions 

/xml_compressed		Compressed xml movie data
-------

5. Deployment Notes

	a. General
		
		Alkindi's application is an all-Java set of server componenets and applications designed to run on Linux. BASH scripts control the services, while data is managed by an Oracle database.
		
		The architecture of the Alkindi services is certainly beyond the scope of this document. A separate CD contains documentation, specifications and source code for the entire system.
		
		In order to fit everything of interest onto a few CDs, some parts of the system are archived in compressed form. After copying the CDs to an appropriate server's filesystem, expanding them is the next step in deployment.
		 
	b. Expanding Java Kits

	The java kits from the /other_software directory should be expanded into the /alkindi/java directory. 

	c. Specifying the JVM

	If you prefer using a JVM other than the default (Sun), edit the script in make sure the script /alkindi/scripts/alkenv.sh sets the environment variable $JAVA_HOME to your JVM's root. IBM's JDK was used as an alternate.

	d. Installing Movie XML Files

	The user interface depends on movie information in XML form, which goes in a directory tree starting at /alkindi/httpd/www.alkindi.com/html/xml. Since the uncompressed movie XML tree is quite large, one may prefer use a symbolic link rather than copying it all to the same filesystem as the rest of the Alkindi system. 
	The compressed movie xml files are in the file /xml_compressed/moviexml.tgz. To install thie files:
		1. Expand the tar file at the root of the alkindi distribution. This will write xml files into a tree starting at /alkindi/httpd/movie. 
		2. Add a symbolic link which points from /alkindi/httpd/www.alkindi.com/html/xml/movie to /alkindi/httpd/movie.

	e. Oracle installation / restoration 

	Unfortunately, instructions for installing and runnning Oracle 8i are beyond the scope of this document, as are those for restoring the Alkidni database. A compentent DBA should be able to restore the Alkindi database given the files on this CD.

	f. Running the services

	The scripts in /alkindi/scripts manage services other than the Oracle database. They can start and stop the middleware and web servers and initiate operations for the maintenance of the system. The most useful are:
		
		alkenv.sh		-	specifies environment variables
		startall.sh 	-	starts everything
		start_ui.sh		-	starts the web server
		start_mw.sh		-	starts the middelware server
		jndiView.sh		-	dumps middleware named objects at runtime
		clusterMgr.sh	-	initiate a clustering/recalc stats operation

-------

6. Running the Matlab Demo

These instructions assume one is using a computer with Matlab installed.

	a.  Start Matlab.
	b.  In the Matlab command window, change directories to the subdirectory containing the Matlab demo (/Matlab_demo).
	c.  Type "init."  (This runs the program init.m, which initializes all the data structures.)
	d.  Type "manager."  (This runs the prototype rating and recommendation manager.)

-------