<TABAREA tabs="Greenstone3,Greenstone2"> <TAB>

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, 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/.

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 Beginner'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-tomcat

OR:

$ ant start

To stop tomcat:

$ ant stop-tomcat

OR:

$ ant stop

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

$ ant restart

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.

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

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

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
...
ProxyPass /greenstone3 http://puka.cs.waikato.ac.nz:8080/greenstone3
ProxyPassReverse /greenstone3 http://puka.cs.waikato.ac.nz:8080/greenstone3
</VirtualHost>

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.

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.

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.

</TAB> <TAB>

Setting up an Apache web server to work with Greenstone 2.

A walkthrough for Linux on how to set up Apache's httpd.2.2.8 web server for Greenstone v2.80. The following should hopefully work with other releases of the Apache's HTTP Server as well.

Notes:

• commands to be typed in a Linux x-term prompt are indicated with $
• Downloading and verifying

Download the current httpd tar.gz file from http://httpd.apache.org/ e.g. You can go to the mirror site http://ossavant.org/apache and download tar.gz version of httpd2.2.8.

To verify you have an uncorrupted copy of the downloaded file <httpd-version.tar.gz>, you need to download the <httpd-version>.tar.gz.asc file and the KEYS file.

For example:

• the KEYS file from http://httpd.apache.org/download.cgi and
• the httpd2.2.8.tar.gz.asc from http://www.apache.org/dist/httpd/

Now, to verify your download, open an x-term and do as described at http://httpd.apache.org/download.cgi.

For example:

$ gpg --import KEYS
$ gpg --verify <httpd version file name>tar.gz.asc

• Extracting

If you've verified it, extract the contents of the download where you want it:

$ tar -xvzf httpd2.2.8.tar.gz

• Installing by compiling

Now the folder httpd2.2.8 is created. CD into this folder. Inside this folder, there's a README file which points one to the INSTALL file for installation instructions. The following comes from there. First choose the directory where you want to install your apache web server. In the following, PREFIX is the full path to where it will reside.

$ ./configure --prefix=PREFIX
$ make
$ make install

For example, PREFIX might be /home/myname/GS2/apache (no quotes!). In this case, we would do:

$ ./configure --prefix=/home/myname/GS2/apache


$ make


$ make install

• Configuring the server and port

Go into your PREFIX folder again (the "apache" folder where you installed the web server). Locate and open the httpd.conf configuration file for editing. That is, open PREFIX/conf/httpd.conf:

• Add your host server's name in the ServerName section (make sure any other ServerName values are commented out):

ServerName <my.fullservername.location.com>

• Add the port you want your web server to be listening at in the Listen section. Choose a port number that is not in already in use.:

Listen 8080

• Running (starting) and stopping the server

To run, type the following in the exterm:

$ PREFIX/bin/apachectl start

To stop it:

$ PREFIX/bin/apachectl stop

If you need to stop then start it up again, you can do both steps in one go:

$ PREFIX/bin/apachectl restart

Running start, stop and restart also works if you're in the PREFIX/bin folder by:

./apachectl start
./apachectl stop
./apachectl restart

For instance, we might do the following to start it using our example prefix:

$ /home/myname/GS2/apache/bin>./apachectl start

• Testing that the web server runs

Open a browser at http://ServerName:portnumber/ (replace with the values you specified for ServerName and port number in the web server configuration file httpd.conf) and it should work. You will know, if a page loads with the message "It Works!" or some other confirmation message.

• Some reading on your part:

If you installed a Binary distribution of Greenstone 2 (GS2), then the installation wizard would have displayed some information with script code on how to set up the web server for GS2: (In the following, $GSDLHOME is the full path to your greenstone installation folder, usually gsdl.) To use the Greenstone Web Library you will need to have a webserver installed (you'll also need perl if you want to build your own collections). The following information is intended to help you configure your webserver for use with Greenstone. Particular attention is given to the Apache webserver which may be downloaded free from www.apache.org. Greenstone will work with other webservers too if that is your preference.

To refer back to this information later you can find it in the file $GSDLHOME/library.txt

Greenstone has been set up to expect $GSDLHOME/GS2 to be accessible from your webserver at the URL http://localhost/gsdl (localhost will of course be the usual web address of your machine if it has one). Likewise, the $GSDLHOME/cgi-bin directory must be accessible as a cgi executable directory.

For the Apache webserver this means adding the following directives to your httpd.conf configuration file:

ScriptAlias /gsdl/cgi-bin "$GSDLHOME/cgi-bin"
  <Directory "$GSDLHOME/cgi-bin">
     Options None
     AllowOverride None
  </Directory>
  
  Alias /gsdl "$GSDLHOME"
  <Directory "$GSDLHOME">
     Options Indexes MultiViews FollowSymLinks
     AllowOverride None
     Order allow,deny
     Allow from all
  </Directory>

Once your webserver is configured in this way you can access Greenstone by pointing your web browser at http://localhost/gsdl/cgi-bin/library or http://your.server.com/gsdl/cgi-bin/library

For more information on installing and configuring a webserver see the Greenstone Installer's guide.

The above is given in the Greenstone 2 installation wizard. We're going to use it now:

• Setting up the apache web server for Greenstone 2

Open up the httpd.conf file again. It's in your web server installation's conf folder, i.e. PREFIX/conf/httpd.conf. Append the following at the end, making sure to replace $GSDLHOME with the full path to your Greenstone 2 installation folder (usually the GS2 folder's called gsdl):

ScriptAlias /gsdl/cgi-bin "$GSDLHOME/cgi-bin"
  <Directory "$GSDLHOME/cgi-bin">
     Options None
     AllowOverride None
  </Directory>
  
  Alias /gsdl "$GSDLHOME"
  <Directory "$GSDLHOME">
     Options Indexes MultiViews FollowSymLinks
     AllowOverride None
     Order allow,deny
     Allow from all
  </Directory>

• If you haven't done so already, open up the file $GSDLHOME/cgi-bin/gsdlsite.cfg, and
• Change:

gsdlhome    **GSDLHOME**

to the full path of $GSDLHOME (you can put it in quotes, try this especially if your path contains spaces):

gsdlhome    "/full/path/"

• Uncomment: #httpprefix /gsdl

(Make sure that the prefix is the same as the alias registered with your web server.)

httpprefix  /gsdl

• And adjust: "httpimg /images" to

(Make sure that the prefix is the same as the alias registered with your web server.)

httpimg     /gsdl/images

• Viewing pages served by Greenstone 2 in your browser

Open the browser again at http://ServerName:Portnumber/gsdl/cgi-bin/library

And now you can hopefully see the main page for Greenstone 2.

A walkthrough for Windows on how to set up Apache's httpd.2.2.9 web server for Greenstone 2. The following should hopefully work with other releases of the Apache HTTP Server as well.

• Download the binary release of the Apache HTTP server for Windows. I got the "Win32 Binary without crypto (no mod_ssl) (MSI Installer)".
• Double click on the downloaded file–for instance, this may be called apache_2.2.9-win32-x86-no_ssl-r2.msi–and go through the installation wizard. Choose "Typical installation". I accepted Port 8080.
• To start the server, open a DOS prompt and move into the Apache Software Foundation\Apache2.2\bin directory. Once there, type

httpd.exe

To stop it, the Apache HTTP Server online manual says opening a new DOS prompt, going to the Apache server's bin directory and typing the following should stop a running server:

httpd.exe -k shutdown

However, this didn't work for me. You may need to type ctrl-c in the same prompt from where you ran httpd.exe instead. See here for more information.

• Check the server is running by visiting localhost:8080 in a browser. It should show the message "It Works!"
• Edit the file "Apache Software Foundation\Apache2.2\conf\httpd.conf" as follows.

• Make it listen at port 8080 if this is not already set, by finding the "Listen" entry in the file:

Listen 8080

• Set the server name to be the name of your host machine by searching for the "ServerName" entry in the file. (More information can be found in the httpd.conf file where you're making these changes.)

ServerName name-of-your-machine

For example, if you're going to test the remote Greenstone server from the same machine–that is, locally–then you can set this value to "localhost":

ServerName localhost

• At the end of the httpd.conf file, paste the following and replace $GSDLHOME with the full path to your greenstone 2 installation. Take care to use forward slashes this time, and leave the quote-marks intact where you find them in the following:

# Setting up the Apache webserver to work with Greenstone2
ScriptAlias /gsdl/cgi-bin "$GSDLHOME/cgi-bin"
  <Directory $GSDLHOME/cgi-bin>
     Options None
     AllowOverride None
  </Directory>
  
  Alias /gsdl "$GSDLHOME"
  <Directory $GSDLHOME>
     Options Indexes MultiViews FollowSymLinks
     AllowOverride None
     Order allow,deny
     Allow from all
  </Directory>

Instead of "gsdl" in the aliases above, you could choose something else (like "gs2remote"), as long as you use it consistently and use the same in the following steps as well.

• Edit the file gsdlsite.cfg located in your $GSDLHOME\cgi-bin as follows:

• Change the GSDLHOME placeholder in the file to be the full path to your Greenstone2 installation. Use Windows style file separators this time (backslashes). For example C:\gsdl.
• Uncomment the "httpprefix" entry to get

httpprefix  /gsdl

Make sure the prefix is set to the same value as the alias you chose.

• You may also need to adjust the "httpimg" entry to:

httpimg     /gsdl/images

Once again, make sure to use the script alias you'd chosen above.

If the images do not display in the next step, then come back here and change this back to the way it was before.

• Visit http://localhost:8080/gsdl/cgi-bin/library.exe in your browser and hopefully you will now see Greenstone 2's main page. (Or, more generally: http://your-host-name:your-port/your-alias/cgi-bin/library.exe)
• On Windows, there is a local library server which often runs automatically when running the Greenstone Librarian Interface, GLI. To avoid this from interfering with the custom web server you have associated with Greenstone (the Apache web server just configured), you may want to tell it to not start automatically when running GLI.

Make sure server.exe is not running. Go into your Greenstone2 installation directory. In there you will find either one or both of the following files: # gsdlsite.cfg # glisite.cfg

If the glisite.cfg file is missing, make a copy of the gsdlsite.cfg file and rename the *copy* as glisite.cfg.

Open glisite.cfg, and edit two lines: the line with the property "autoenter" and the line with the property "start_browser". Set both properties equal to 0 as follows:

    autoenter=0
    start_browser=0

The above will prevent the local library server (server.exe) from being launched every time you launch GLI.

You will also want to set the greenstone library path in GLI to connect to the correct web server when previewing collections. You do this in GLI, by going to File > Preferences > Connection tab and setting the value of the Greenstone Web Path field to http://YourServerHostName:PortNumber/gsdl/cgi-bin/library.exe (or http://localhost:9020/AliasYouChoseInStep5Above/cgi-bin/library)

• VERY IMPORTANT

If you are using Lucene as indexer you must add the following line to your httpd.conf file:

PassEnv "USERPROFILE" "ProgramFiles" "TEMP" "OS" "LANG"

Apache needs to know the temp folder to run Lucene queries. Otherway, you will have no results.

If you would like to run Greenstone with IIS, instead of Apache, these notes may be useful.

After installing the web library version of Greenstone, configure IIS by following these steps:

1. Visit http://localhost in a web browser to check that IIS is running
2. Run the IIS configuration program (Control Panel → Administrative Tools → Internet Information Services)
3. Double-click on the local computer, then Web Sites. Right-click on Default Web Site, choose New → Virtual Directory. Set the Alias to "gsdl" for 2.80/2.81 and earlier versions (and to "greenstone" in or after 2.82), the Content Directory to the directory where you installed Greenstone (eg. C:\Program Files\Greenstone), and allow "Read" and "Browse" permissions only.
4. Open the new "gsdl" entry, right-click on the "cgi-bin" folder and choose Properties. Enter "Greenstone" as the Application name and choose "Scripts and Executables" for Execute Permissions. Untick "Directory browsing".
5. IIS 6: Copy the gsdlsite.cfg file from the Greenstone "cgi-bin" folder into the main Greenstone folder. If you have only gsdlsite.cfg.in there (may happen in 2.82), copy it to main folder and rename to gsdlsite.cfg. Edit it and modify the gsdlhome variable to be the location of your top level greenstone folder.
6. IIS 6: expand Local Computer, click "Web Service Extension", then right-click "All Unknown CGI Extensions" and choose Allow. (Thanks to Victor T. Jones, Jr.)
7. Close the IIS configuration program.
8. Make the Greenstone "etc\error.txt", "etc\key.db" (or key.gdb) and "etc\users.db" (or users.gdb) files world-writeable by opening a DOS prompt (Start → Run → cmd.exe) then running:

cacls "C:\Program Files\Greenstone\etc\error.txt" /P Everyone:F

cacls "C:\Program Files\Greenstone\etc\key.db" /P Everyone:F

cacls "C:\Program Files\Greenstone\etc\users.db" /P Everyone:F

If error.txt not there, add and empty file called error.txt and change permissions as described.

You should now be able to access your Greenstone library at http://localhost/gsdl/cgi-bin/library.exe, or, for versions since 2.81, at http://localhost/gsdl/cgi-bin/library.cgi

• Additional notes for 2.82, thanks to Diego Spano and Sridhara B
  • Make sure in cgi-bin you have gsdlsite.cfg not gsdlsite.cfg.in. It may be better to rename the file in IIS:

1. Go to IIS
2. Default website
3. click on cgi-bin virtual directory.
4. In the right side cgi-bin files are found and rename gsdlsite.cfg.in to gsdlsite.cfg.

Then edit the values like the following: (this assumes installation into C:\greenstone2)

  gsdlhome    c:\greenstone2
  httpprefix  /gsdl
  httpweb     /gsdl/web
  gwcgi       /gsdl/cgi-bin/library.cgi

</TAB> </TABAREA>