Table of Contents

Greenstone 3 Apache Tomcat Server

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 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 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: 

$ ./ant-start-with-exts.sh (unix) or ant-start-with-exts.bat (windows)

OR: 

$ source ./gs3-setup.sh (unix) or gs3-setup.bat (windows)
$ ant start

To stop tomcat: 

$ ./ant-stop-with-exts.sh (unix) or ant-stop-with-exts.bat (windows)

OR: 

$ ant stop

To stop and then immediately start up again in one step, use restart: 

$ ./ant-restart-with-exts.sh (unix) or ant-restart-with-exts.bat (windows)

OR: 

$ ant restart

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. You will need to restart Tomcat for this to take effect (ant-restart-with-exts.sh/bat).

Alternatively, you can change the port number in the File→Settings… menu of the Greenstone Server program, run with gs3-server.sh/bat

Changing Tomcat settings

Don't edit the configuration files in Tomcat directly. Edit the versions in $GSDL3SRCHOME/resources/tomcat:

'ant configure' will copy these files to their correct places, replacing variable placeholders with their correct values. This is done each time Tomcat is restarted. 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:

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

Tomcat can be configured to allow or disallow directory listings. To check or change the settings, look for the ’listings’ parameter in the default servlet definition, in $GSDL3SRCHOME/resources/tomcat/web8.xml.in. Set it to false to disable directory listings. 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.in. Restart Tomcat.

If you are seeing lots of errors in packages/tomcat/logs/catalina.out like the following, then consider increasing the maximum size of the cache - edit the cacheMaxSize attribute on the Resources element in resources.tomcat/greenstone3.xml.in. 

org.apache.catalina.webresources.Cache.getResource Unable to add the resource at [... class name ...] 
to the cache for web application [/greenstone3] because there was 
insufficient free space available after evicting expired cache entries

Using Greenstone inside a frame

Greenstone's cookies are SameSite=none by default (prior to April 2024) or after that, SameSite=strict. Browsers nowadays handle samesite=none in different ways. To get Greenstone to work properly inside a frame, the cookies need to be SameSite=none, partitioned=true. This needs a later version of Tomcat. From April 2024, we use a newer version of Tomcat (8.5.99) instead of 8.5.51. This has the ability to set partitioned for cookies. This feature is available in Greenstone 3.12 and later. Edit resources/tomcat/greenstone3.xml.in - comment out the CookieProcessor line setting strict, and uncomment the one setting none + partitioned. Then restart Tomcat 

<!-- if greenstone is to be run in an iframe, need to use the -->
<!-- sameSiteCookies=none version of the CookieProcessor -->
  <CookieProcessor sameSiteCookies="none" partitioned="true"/>
  <!--<CookieProcessor sameSiteCookies="strict"/>-->

Turn off localhost access logs

By default, one of the enabled forms of logging in Apache Tomcat is the Local Host Access Log. This log tracks every connection made to the server. This can add up to a lot of logs that can quickly overwhelm the hard drive space of your server.

To disable this, edit resources/tomcat/server_tomcat8.xml.in

Look for the <Valve className="org.apache.catalina.valves.AccessLogValve"…/> section and comment it out by surrounding it in <!-- -->

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.in.

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. 

 <VirtualHost xx.xx.xx.xx>
ServerName www.greenstone.org
...

Redirect /greenstone3 /greenstone3/
ProxyPass /webswing-server/ http://puka.cs.waikato.ac.nz:8383/webswing-server/ upgrade=websocket
ProxyPass /greenstone3/ http://puka.cs.waikato.ac.nz:8080/greenstone3
ProxyPassReverse /greenstone3/ http://puka.cs.waikato.ac.nz:8080/greenstone3
<Location /greenstone3>
          ProxyPassReverseCookiePath /greenstone3 /greenstone3
</Location>
</VirtualHost>

Restart Apache for these changes to take effect.

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 build.properties. Set the revproxy fields: 

revproxy.protocol=https
revproxy.domain=www.greenstone.org
##revproxy.opt_port=8383
##revproxy.context=greenstone3

You will also need to edit resources/web/servlets.xml.in Uncomment and set the servlet_url_prefix param: 

<init-param>
   <param-name>servlet_url_prefix</param-name>
   <param-value>//www.greenstone.org/greenstone3/</param-value>
</init-param>

You will need to restart Tomcat for these settings to take effect.

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: 

$ ant stop

Then, deploy (as written in the Greenstone 3 manual, p. 5): 

$ ant deploy-localsite

Check that it works, by starting tomcat again and going to: 

http://localhost:8080/greenstone3/services/

Make sure that the page appears. You can also look at the wsdl file for the gs3 web service that's been exposed: 

http://localhost:8080/greenstone3/services/localsite?wsdl

You can also deploy other sites, see the Greenstone 3 Developer's Manual.