source: trunk/gsdl3/INSTALL@ 3476

INSTALLATION GUIDE FOR GSDL3

1. you also need to get mgpp code - comes in a separate checkout.
I once added a directory for mgpp into gsdl3/packages in cvs - now I cant get 
rid of it, so you need to delete it before you start.
cd packages
rm -r mgpp
cvs co mgpp
cd mgpp
./configure --prefix <gsdl3home>
make
make install
cd ../..

Note: you need to use your gsdl3 home directory as the prefix for configure 
at this stage - mgpp has been set up properly, but gsdl3 hasn't


2. Make the gsdl3 stuff

First need to unpack the tomcat stuff, cos we use a jar file from there

cd comms/tomcat/

tar xzvf jakarta-tomcat-4.0.1.tar.gz 

cd ../..

source setup.bash - to set up your CLASSPATH

do a 'make', then 'make install', in each of the following directories

src/java/org/greenstone/gdbm
src/java/org/greenstone/testing
src/java/org/greenstone/gsdl3
src/java/org/greenstone/applet/phind

3. set up the sample mgpp collection

in sites/localsite/collect/mgppdemo/index/

tar xzvf mgpp-indexfiles.tar.gz

this is a collection built using mgpp in greenstone 2 - MGPPGDBMService works 
with this type of collection.

Note, you can use the new Java Queryer program to query this collection (see 
RUNNING)


4. set up the servlet information for tomcat

edit web/WEB-INF/web.xml

in the init-param entries for the servlet, you need to change the siteshome
and interfaces home params to reflect your installation setup. - should point to the sites and interfaces directories.

in web, add symbolic links to your interfaces, sites and lib directories 

is likely to be:
ln -s ../interfaces
ln -s ../sites
ln -s ../lib

5. set up tomcat

cd comms/tomcat/jakarta-tomcat-4.0.1

edit bin/catalina.sh:

on line 89 add $CLASSPATH to the CP="...." line ie. CP="$CLASSPATH:..." - this 
sets up the class path properly 

edit conf/server.xml:

you need  add a context for gsdl servlets
add these lines (putting the correct path for GSDL3HOME)

<!-- GSDL3 Service -->
<Context path="/gsdl3" docBase="<GSDL3HOME>/web" debug="1" reloadable="true"/>

when you edit server.xml, (or change web.xml in gsdl3/web/WEB-INF/web.xml) or
change the classes, you need to shutdown and restart the server. also you may 
need to clear the cache of your browser

(conf/server.xml is the place to change the port number if needed)


6. run tomcat

to run tomcat, you need to have sourced setup.bash in GSDL3HOME to set up $CLASSPATH

then cd to comms/tomcat/jakarta-tomcat-4.0.1/bin

run ./startup.sh

(to shut down tomcat, run ./shutdown.sh)

the tomcat server can be accessed on the web via localhost:8080

the greenstone stuff is at localhost:8080/gsdl3 - this uses index.html - has 
links to the test servlet and the greenstone servlets

you should be able to run library from the index page

System.out/err and cout/cerr go to comms/tomcat/jakarta-tomcat-4.0.1/logs/catalina.out - if need to debug stuff

7. The test servlet

a test servlet is provided to make sure you have tomcat set up properly

in web/WEB-INF/classes, do 'javac TestServlet.java'

you can click on the link on the gsdl3 index page to run the test. 
or can specify it directly:
localhost:8080/gsdl3/testing

the path 'testing' is determined by servlet-mapping entry in 
web/WEB-INF/web.xml 



USING SOAP TO TALK TO A REMOTE SITE

this is needed if you have a setup such as for site1 - it uses a SOAP 
connection to site2.

1. set up SOAP 

untar soap-bin-2.2.tar.gz in the comms/soap directory

edit comms/tomcat/jakarta-tomcat-4.0.1/conf/server.xml

add the following (put proper path for <GSDL3HOME>)

<!-- SOAP Service -->
<Context path="/soap" docBase="<GSDL3HOME>/comms/soap/soap-2_2/webapps/soap" debug="1" reloadable="true"/>


2. set up SOAP Server:

the class SOAPServer is a wrapper around a messagerouter - so can serve 
the collections

it has a path hard coded in  - need to set this to your appropriate site - 
for the example sites that I've set up, it should be <GSDL3HOME>/sites/site2

3. deploy your service - SOAPServer

you can access the soap service though the web, at http://localhost:8080/soap

Run the admin client

can list, deploy, undeploy soap services

to deploy the SOAPServer for site2:

edit the following fields in the deploy form:

ID:  org.greenstone.site2
Scope: any will do: Request - new instantiation for each request
            Session - same instantiation across a session
            Application - only uses one instantiation

Methods: process

Java Provider / Provider Class: org.greenstone.gsdl3.SOAPServer

then click deploy.
hopefully all will be well.

4. debugging soap:

tomcat output goes to jakarta-tomcat-4.0.1/logs/catalina.out

if you recompile the classes, you need to shutdown and restart tomcat to get 
the new classes.

deployment info is retained between shutdown and start up - dont need to 
redeploy it each time.

TcpTUnnelGui:

this program allows you to view the actual soap messages

run like:

java org.apache.soap.util.net.TcpTunnelGui 8070 localhost 8080

tomcat uses 8080, and you need to modify the greenstone stuff to talk to port 
8070 instead of 8080:

sites/site1 is the site that talks to the SOAPServer for site2

in site1/sitecfg.xml, in the address field, replace 8080 with 8070 when you 
want to use TcpTunnelGui.

note that 
http://localhost:8080/soap/servlet/rpcrouter

is the address for talking to the tomcat soap thingy.