source: trunk/gsdl3/INSTALL@ 5430

INSTALLATION GUIDE FOR GSDL3

This stuff is all done by a script now:
just need to carry out the following:

source setup.bash
install.bash
source setup.bash 

Note: if you are using mozilla it doesn't seem to like localhost - you should edit the siteConfig files (web/sites/<sitename>/siteConfig.xml) to have your computer name instead of localhost.

Note: the second setup.bash is needed to add the newly created jar files to the CLASSPATH

if you want to use soap, also run
install-soap.bash
you shouldn't run this more than once.

You should now be able to run greenstone - go to localhost:8080/gsdl3, and 'run the library servlet'.

Do not run install.bash more than once. If you need to update your stuff from cvs, or recompile things etc, you can run update.bash.

Some notes for subsequent running of gsdl3:

TOMCAT:

Tomcat is a servlet container. It is used to serve a greenstone site using a servlet.

The file $GSDL3HOME/web/WEB-INF/web.xml contains the setup information for tomcat---tells it what servlets to load, what initial paramaters to pass them, and what web names map to the servlets.
There are three servlets specified in web.xml: one is a test servlet that just prints ``hello greenstone'' to a web page. This is useful for testing tomcat. The other two are greenstone library servlets, ``library'', which serves localsite, and ``library1'' which serves site1.

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

cd $gsdlhome/comms/jakarta/tomcat/bin
./startup.sh

./shutdown.sh shuts down tomcat

The tomcat server can be accessed on the web at http://localhost:8080---this gets you to a welcome page.
The greenstone stuff is at http://localhost:8080/gsdl3---this displays $GSDL3HOME/web/index.html. You should be able to run the test servlet and both library servlets from this page.

Note: tomcat must be shutdown and restarted any time you make changes in the following for those changes to take effect:
web/WEB-INF/web.xml
comms/jakarta/tomcat/conf/server.xml
any classes or jar files used by the servlets

Also if you change any collections, you can restart tomcat to reload them.

Note: stdin and stdout for the servlets both go to $GSDL3HOME/comms/jakarta/tomcat/logs/catalina.out

Symlinks:

Tomcat by default doesn't follow symlinks (although the symlink to lib seems to work). To make it follow symlinks, eg to have the collect directory of a site somewhere else, you need to add the following to tomcats server.xml ($GSDL3HOME/comms/jakarta/tomcat/conf/server.xml):
<Resources allowLinking='true'/>
This needs to go inside the gsdl3 context, i.e.

<Context path="/gsdl3" docBase="$GSDL3HOME/web" debug="1" 
reloadable="true">
   <Resources allowLinking='true'/>
</Context>

By default, tomcat allows directory listings for everything in the docBase directory. For example, you can enter localhost:8080/gsdl3/sites and it will give you a list of all the sites. To turn this off, you need to edit Tomcat's default web.xml file ($GSDL3HOME/comms/jakarta/tomcat/conf/web.xml):

In the default servlet definition, change the 'listings' param to false.

SITES:
There are two greenstone "sites" that come with the checkout: localsite, and site1. localsite has several collections, only two of which have any actual data. The third is a dummy collection. site1 has one dummy collection. Each site has a configuration file which specifies the site name,  site-wide services if any, and a list of remote sites to connect to.
localsite does not connect to any other sites. site1 specifies a SOAP connection to localsite.

The collections which do not have data can be looked at but you cant do any queries on them.

SOAP:

site1 specifies a SOAP connection to localsite. If you run site1 without connecting to localsite, you can only see the local  collections, eg the dummy collection myfiles. However, if you connect to localsite, you can see all of its collections as well.

The SOAP server we use is actually run as a servlet in tomcat. The install-soap.bash script sets up SOAP, sets up the SOAP server class which will be your service, and then deploys that service.

You can also deploy services through the web interface.
The SOAP servlet can be accessed at http://localhost:8080/soap. You should see a welcome page. Click on ``Run the admin client''. This enables you to list, deploy and undeploy SOAP services.

To deploy the SOAPServer for localsite:

Click on ``deploy'' and edit the following fields in the deploy form:


ID:  org.greenstone.localsite
Scope: (any will do)  Request---new instantiation for each reques
              Session---same instantiation across a session
              Application---only uses one instantiation
Methods: process
Java Provider / Provider Class: org.greenstone.gsdl3.SOAPServer


Now click the ``deploy'' button at the bottom of the page. If the service has been deployed, it should appear when you click on the lefthand ``List'' button.

Information about deployed services is maintained between tomcat sessions---you only need to deploy it once. To get the library1 servlet talking to the SOAP server, you need to shutdown and restart tomcat (see above). You should see more collections when you run the library1 servlet.

Debugging SOAP

If you need to debug the SOAP stuff for some reason, or just want to look at the SOAP messages that are being passed back and forth, there is a program called TcpTunnelGui. This intercepts messages coming in to one port, displays them, and passes them to another port.

To run it:

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

tomcat uses port 8080 - you need to modify greenstone to talk to port 8070 instead of 8080. - this is specified in the 'site' element of the site configuration file. 

eg, in sites/site1/siteConfig.xml:

<site name="org.greenstone.localsite" 
      address="http://localhost:8080/soap/servlet/rpcrouter" 
      type="soap"/>

You can replace the 8080 with 8070 if you want to run TcpTunnelGui.

Note that http://localhost:8080/soap/servlet/rpcrouter is the
address for talking to the tomcat SOAP servlet services.

Note: you can change tomcat to use a different port if you like. Edit comms/jakarta/tomcat/conf/server.xml, and change 8080 to whatever. If you do this, and are using soap, you need to remember to change the port number in:

the install-soap.bash file where it tries to deploy site1.
the siteConfig.xml file for any site that wants to talk to a soap service running on this tomcat.