Changeset 3637

Timestamp:

2002-12-20T16:48:29+13:00 (21 years ago)

Author:

kjdon

Message:

added back in some usage notes

File:

• trunk/gsdl3/INSTALL (modified) (1 diff)

trunk/gsdl3/INSTALL

@@ -6 +6 @@
 source setup.bash
 install.bash
+source setup.bash 
+
+Note: the second setup.bash is needed to add the newly created jar files to teh CLASSPATH
 
 if you want to use soap, also run
 install-soap.bash
 
+You should now be able to run greenstone - go to localhost:8080/gsdl3, and 'run the library servlet'.
 
+If you run these install scripts more than once you end up with multiple entries in some config files. 
+If you are getting problems, edit gsdl3/comms/tomcat/jakarta/conf/server.xml and remove any duplicates of <Context> elements.
+
+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 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 if you are having trouble getting tomcat set up. 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/tomcat/jakarta-tomcat-4.0.1/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/tomcat/jakarta-tomcat-4.0.1/conf/server.xml
+any classes or jar files used by the servlets
+
+Note: stdin and stdout for the servlets both go to comms/tomcat/jakarta/logs/catalina.out
+
+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.
+
+