Greenstone Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Advanced Server: Greenstone 3 ======


===== Apache Tomcat =====
Tomcat is a servlet container, and Greenstone3 runs as a servlet inside it. 
The file ''$GSDL3SRCHOME/packages/tomcat/conf/server.xml'' is the Tomcat configuration file. 

A Tomcat Context represents a web application. The Context for Greenstone3 is given by the file
$GSDL3SRCHOME/packages/tomcat/conf/Catalina/localhost/greenstone3.xml. 
This tells Tomcat where to find the files for the application including its web.xml file (in the $GSDL3HOME folder, ie the web folder in your greenstone3 installation) , and what URL (/greenstone3) to give it. 

To make changes to these files, don't edit these files directly as Greenstone configures these each time it starts up. See the section on changing Tomcat settings [[#Changing_Tomcat_settings|below]].

Anything inside the Context directory is accessible via Tomcat . For example, the index.html 
file that lives in $GSDL3HOME can be accessed through the URL
 localhost:8383/greenstone3/index.html. The gs2mgdemo collection’s images can be accessed through 
localhost:8383/greenstone3/sites/localsite/collect/gs2mgdemo/images/.

==== Starting and Stopping Tomcat ====

Greenstone provides a little server program which will start the Tomcat server and open the library in a browser. See the [[en:user:greenstone_server|Greenstone Server]] page in the User's Guide.
Alternatively, you can use Ant to stop and start Tomcat. Run these commands from the main Greenstone3 installation directory ($GSDL3SRCHOME).

To start tomcat:
<code>$ ant start-tomcat</code>
OR:
<code>$ ant start</code>
To stop tomcat:
<code>$ ant stop-tomcat</code>
OR:
<code>$ ant stop</code>
To stop and then immediately start up again in one step, use restart:
<code>$ ant restart</code>


==== Changing Tomcat Port Number ====
Greenstone sets up Tomcat to run on port 8383 by default. To change this, you can edit the tomcat.port property in build.properties. If you do this before installing Greenstone, then running ’ant install’ will use the new port number. If you want to change it later on, shutdown tomcat, run ’ant configure’, then when you restart tomcat it will use the new port.
Alternatively, you can change the port number in the File->Settings... menu of the Grennstone Server program, run with gs3-server.sh.

==== Changing Tomcat settings ====
Don't edit the configuration files in Tomcat directly. Edit the versions in $GSDL3SRCHOME/resources/tomcat: greenstone3.xml (copied to $GSDL3SRCHOME/packages/tomcat/conf/Catalina/localhost/greenstone3.xml); server_tomcat7.xml (copied to $GSDL3SRCHOME/packages/tomcat/conf/server.xml);
web.xml (copied to $GSDL3SRCHOME/packages/tomcat/confi/web.xml).

'ant configure-tomcat' will copy these files to their correct places, replacing variable placeholders with their correct values. This is done each time Tomcat is restarted via Ant. Therefore any changes to the files in the Tomcat folder will be overwritten each time Tomcat is restarted.

Note: Tomcat must be shutdown and restarted any time you make changes in the following
 for those changes to take effect: 

  * ''$GSDL3HOME/WEB-INF/web.xml ''
  * ''$GSDL3SRCHOME/resources/tomcat/*.xml''  
  * any classes or jar files used by the servlets  (if reloadable is set to false, see [[#xxx|below]].

We have disabled following symlinks for the greenstone servlet. 
To enable it, edit $GSDL3SRCHOME/resources/tomcat/greenstone3.xml and 
set ’allowLinking’ to true. Restart Tomcat.

By default, Tomcat allows directory listings. To disable this, change the ’listings’
 parameter to false in the default servlet definition, in Tomcat’s web.xml file 
($GSDL3SRCHOME/resources/tomcat/web.xml). Restart Tomcat.

We have set the greenstone context to be reloadable. 
This means that if a class or resource file in $GSDL3HOME/WEB-INF/lib or $GSDL3HOME/WEB-INF/classes changes,
 the servlet will be reloaded. This is useful for development, but should be turned off for 
production mode: set the ’reloadable’ attribute to false in $GSDL3SRCHOME/resources/tomcat/greenstone3.xml. Restart Tomcat.

==== Changing collections or services ====
On startup, the servlet loads in its site, collections and services.
If the site or collection configuration files are changed, these changes will not take 
effect until the site/collection is reloaded. This can be done through the reconfiguration
 messages (see Section ?), or by restarting Tomcat.

==== Tomcat Session Handling ====

Tomcat uses a Manager to handle HTTP session information. The Manager is specified in a <Manager> element in the greenstone3.xml context file. By default, Greenstone uses the standard Tomcat default manager.

Session information is stored between normal stop and starts in $GSDL3SRCHOME/packages/tomcat/work/Catalina/localhost/greenstone3/SESSIONS.ser. To disable storing session info between restarts, set the pathname attribute of the Manager element to "" in $GSDL3SRCHOME/resources/tomcat/greenstone3.xml.

To manually clear saved session info, stop Tomcat and delete the SESSIONS.ser file.



==== Proxying Tomcat with Apache ====
Instead of incorporating servlet support into your existing web server, 
an easy alternative is to proxy Tomcat. The http://www.greenstone.org/greenstone3 site 
uses Apache to proxy Tomcat. ''ProxyPass'' and ''ProxyPassReverse'' directives need to be added to 
the Virtualhost description for the www.greenstone.org server.

<code>
 <VirtualHost xx.xx.xx.xx>
ServerName www.greenstone.org
...
ProxyPass /greenstone3 http://puka.cs.waikato.ac.nz:8080/greenstone3
ProxyPassReverse /greenstone3 http://puka.cs.waikato.ac.nz:8080/greenstone3
</VirtualHost>
</code>

In our example, the Greenstone3 servlet can be accessed at 
http://www.greenstone.org/greenstone3/library, instead of at 
http://puka.cs.waikato.ac.nz:8080/greenstone3/library, which is not publicly accessible.

You will also need to tell Greenstone itself about the new web address. Edit 
**web/sites/localsite/siteConfig.xml**. Add a line like the following to the <metadataList>:
<code>
<metadata name="siteURL">http://www.greenstone.org/greenstone3/</metadata>
</code>


Set up the tomcat.port and shutdown port in your ''build.properties'' file if different from the default 8383 and 8305 respectively.

Also edit these files ton contain the new url-prefix (if different from /greenstone3):
<code>
	./resources/web/global.properties.in
	./resources/web/global.properties
</code>
to change 
<code>tomcat.context=@greenstone.context@</code>
to
<code>
	#tomcat.context=@greenstone.context@
	tomcat.context=urban-narrative-greenstone3
</code>

Don't forget to run (from GS3 folder):
<code>
	ant configure-web
</code>
to regenerate the global.properties file in the actual web folder.

Finally, to get everything running:
</code>
./gs3-setup.sh
ant start
<code>
Then
<code>ssh you@remote.public.machine (e.g. puka)</code>
In the same x-term, ssh -L back into the machine running the GS3 server:
<code>puka$ ssh -L port:localhost:port (you@)gs3-server.machine.domain</code>

On any browser, visit:
<code>remote.public.machine/url-prefix/library</code>
=== Running Tomcat behind a proxy ===
Almost everything works fine when Tomcat is running behind a proxy. 
The only time this causes trouble is if the servlet itself needs to 
make external HTTP connections. We do this in the infomine demo collection for example. 
One of the service classes sends HTTP requests to the infomine database at riverside. 
Since this is going through the proxy, a username and password is needed. It is not 
sufficient to prompt the user for a password because they are unlikely to have a 
password for the particular proxy that Tomcat is using. What we have done at present 
is to put a proxy element in the ''siteConfig.xml'' file. Here you have to enter a suitable 
username and password for the proxy server. Unfortunately, these are entered in plain text.
 And the file is viewable via the servlet. So we need a better solution.


==== Deploying a Soap Server on localsite ====


Make sure tomcat has **stopped**. 

In your greenstone3 home folder, $GSDLHOME:
<code>$ ant stop</code>
Then, deploy 
(as written in the [[http://files.greenstone.org/technical/gs3manual.pdf|Greenstone 3 manual]], p. 5):
<code>$ ant deploy-localsite</code>
Check that it works, by **starting** tomcat again and going to:
<code>http://localhost:8080/greenstone3/services/</code>
Make sure that the page appears. You can also look at the wsdl file for the gs3 web service that's been exposed: 
<code>http://localhost:8080/greenstone3/services/localsite?wsdl</code>
You can also deploy other sites, see the [[http://files.greenstone.org/technical/gs3manual.pdf|Greenstone 3 Developer's Manual]].