Table of Contents

Release Name: 3.05

Release Date:

Released: Windows, GNU/Linux (32 and 64 bit) releases of Greenstone 3.05. Can be downloaded from sourceforge.

Installation Instructions

Installing and running the binary release

Note that in some cases, the following doesn't work

 export TMPDIR=/something/else
 ./Greenstone-3.05-linux.bin

Use the following instead

 TMPDIR=/something/else ./Greenstone-3.05-linux.bin

During the installation process you will be presented with several options. For many, the default settings will be sufficient. Some important options are

Once you have successfully installed Greenstone3, you can start up the server by choosing Grenstone3 Digital Library from the Start menu (Windows) or running gs3-server.sh/bat. This launches a small server program which starts up Tomcat and launches a browser. A small window pops up which allows you to change some settings for your library and restart the Tomcat server. Closing this program will stop Tomcat running. By default, your library will be available at localhost:8383/greenstone3/library. File→Settings in the Greenstone Server window gives you options to change the port number and which browser it uses by default. More notes about running Greenstone can be found in the README.txt file in the top level Greenstone folder.

To build collections, run GLI from the Start menu (Windows) or by running gli/gli.sh/bat in the top level Greenstone3 folder. Tutorial exercises about building collections in Greenstone 3.05 can be found here.

Adding source code to a binary release

Important note: For the 3.05 Release, the source component does not compile successfully on a Greenstone binary installation on a linux 64 bit machine. Use the source distribution instead, which has been tested to work on linux 64 bit machines. The source component and source distribution work on both linux 32 bit machines and windows.

Installing a source release

Setting up your Greenstone OAI Server and using GLI to download over OAI from a Greenstone server

In Greenstone 3, collections should be available over OAI by default. Their collectionConfig.xml files already specify that each collection is OAI enabled, through use of an OAIPMH element. If you want to disable a collection from being accessibile over OAI, edit the OAIPMH element in that collection's collectionConfig.xml.

If you wish to validate the Greenstone 3 OAIServer, edit web/WEB-INF/classes/OAIConfig.xml to add in the adminEmail property to contain the email to where test results should be sent. If testing the behaviour of the resumptionToken, set the resumeAfter element to a low value like 5.

To validate your OAI server, visit http://www.openarchives.org/Register/ValidateSite.

However, before you can validate your OAI server and before you can try testing if GLI can download over OAI from it, the machine on which you're running the Greenstone 3 server will have to have its firewall and virtual server (port-forwarding) settings set up such that the Greenstone server can be made accessible to the outside world.

For further information on your Greenstone OAI Server, please read through OAI support.

Setting up a remote Greenstone 3 server

This will allow remote client-GLI applications to connect to your Greenstone server, to remotely create and upload new collections to be built and hosted by your server machine.

Remote Greenstone 3 Server

To install the server-side functionality:

1. If you're on Windows, open Tomcat's conf/web.xml file (found in greenstone3/packages/tomcat/conf folder) for editing, as you may need to specify the full path of the Perl library for the parameter "executable" of CGIServlet. This takes the form:

<init-param>
	<param-name>executable</param-name>
        <param-value>C:\Program Files\greenstone3\gs2build\bin\windows\perl\bin\perl.exe</param-value>
</init-param>

2. Edit the first line of the greenstone3/web/WEB-INF/cgi/gliserver.pl file and specify the full path of the perl binary. On Windows this will be (if installed in the default location):

#!C:\Program Files\greenstone3\gs2build\bin\windows\perl\bin\perl -w

3. If you're on Linux and working with a binary release, make sure that the webserver user has executable permissions on gliserver.pl:

cd greenstone3/web/WEB-INF/cgi
chmod a+rx gliserver.pl

4. Make the Greenstone "collect" directory, located in web/sites/localsite, writeable by the webserver user.

On Unix, use chmod.

On Windows, run in a DOS prompt:

cacls "C:\Program Files\Greenstone3\web\sites\localsite\collect" /P Everyone:F

5. Open up the file build.properties located in your greenstone installation folder. Edit the tomcat.server property's value to refer to your server machine's hostname instead of leaving it at the default value of "localhost":

# tomcat info
tomcat.server=your-server-computer-name

Once the server is started up, this will update the same property in greenstone's web/WEB-INF/classes/global.properties file. Then images viewed from a browser on the client side will refer to the correct location on the remote machine.

(If you don't know what your machine's host name is and you're on Windows, then open a DOS prompt and type:

ipconfig /all

Scroll to the top of the output that gets printed to the screen and note what it mentions for HOST NAME. Also note the DNS Suffix Search List.

Put these two together with a period mark to separate them and use this as the value for your tomcat.server property.)

6. Start up your Greenstone 3 server:

ant restart

7. Check that Tomcat and Greenstone3 are working correctly by visiting

http://<your-machine-name>:<port>/greenstone3/library

8. Add some user accounts by visiting the Greenstone default library page (http://YOURHOST:YOURPORT/greenstone3/library) and clicking the "Administration Page" link near the bottom of it, then "add a new user". See the Authentication section below for more information.

Even if the admin user wishes to use the client-gli, they will still need to log in to the Administration Page once after installation in order for the user database to be set up.

9. Finally, visit the following page in the web browser to test that your remote Greenstone server is set up properly:

http://<your-machine-name>:<port>/greenstone3/cgi-bin/gliserver.pl?cmd=check-installation

You should get a message saying "Java found" and "Installation OK!" Important: You cannot continue until this is successful, as the Remote Greenstone 3 server will not work without it!

If you get a message saying "Java failed"

Client-GLI

Assuming that the remote Greenstone server is accessible to the outside world and you're not behind a firewall, you can access the remote Greenstone server from a client-gli application installed on any other machine. To do so,

1. Run client-gli quite as you would GLI. It's accessible from the Windows Start menu, otherwise you can run the client-gli script (located at the toplevel of a Greenstone installation) from a terminal.

2. You'll be asked for the gliserver.pl URL of the remote Greenstone 3 server that you wish to connect to. This is of the form

http://<remote-gs3-server-machine-name>:<remote-port>/greenstone3/cgi-bin/gliserver.pl

It's the same URL as in Step 10 of setting up the remote GS3 server above.

Important Changes and Bug Fixes

New interface

The previous default interface has been replaced with a new and improved interface. The most important new features are:

The old interfaces are still available with the following names (To use a different interface set the interface name in WEB-INF/web.xml for the servlet you want to change):

The default servlets have also been renamed as follows:

Restful URLS

URLs in Greenstone 3 are now much tidier and easier to understand. For example, instead of a URL like this to access the document with the ID HASH1234ABCD:

it can now be accessed with the URL:

Authentication

Greenstone 3 now has a security set up similar to that of Greenstone 2. Users can register themselves on the Greenstone 3 installation and administrators can assign users to various groups. Security constraints can be assigned in the collectionConfig.xml file to prevent certain groups from accessing a collection.

Collection building

Collection building and GLI uses the same code base as Greenstone 2 and corresponds to the 2.85 building code with the following differences. Differences may be bug fixes and/or improvements since the 2.85 release, or features in the Greenstone 2 version that have not been implemented yet for Greenstone 3.

Still to be done for collection building in Greenstone 3

Note, 3.04 (Aug 2009) coincided roughly with the 2.82 release (Jun 2009). To see the collection building changes since 3.04, see the following release notes: 2.83 (Nov 2009), 2.84 (April 2011), 2.85 (Nov 2011). Only GLI and collection building notes will be relevant to Greenstone 3.

GLI changes

IMPORTANT information

Security

In Greenstone 3.05rc2 and earlier, the users database file is publicly accessible, allowing access to its passwords. This is not a problem in Greenstone 3.05. To prevent access to the users database and other database files in your Greenstone 3 installation, 1. in a text editor, open your Greenstone folder's web/WEB-INF/web.xml file

2. add the following just before the final line of text in the file:

  <security-constraint>
    <web-resource-collection>
        <web-resource-name>usersDB files</web-resource-name>
        <description>No direct access to usersDB files.</description>
        <url-pattern>/sites/localsite/etc/usersDB/*</url-pattern>	
        <http-method>POST</http-method>
        <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
        <description>No direct browser access to usersDB files.</description>
        <role-name>NobodyHasThisRole</role-name>
    </auth-constraint>
  </security-constraint>

The above handles the default GS3 site localsite. If you have any other other sites, you'll have to do this for each. In each case, set the line specifiying the url-pattern to match each site.

3. Save the file 4. Restart your Greenstone 3 server

In Greenstone 3.05, we're denying public access to the Greenstone log files by default. If you wish to make your Greenstone logs publicly visible, such as when communicating issues to the Greenstone Team, you will want to edit your Greenstone installation's web/WEB-INF/web.xml file and comment out or remove the following which occurs at the end of the file:

<!-- Deny access to contents of URL pattern /logs/*, although greenstone.log is the important one. It appears the url pattern has to be relative to the web directory.  http://stackoverflow.com/questions/5333266/tomcat-deny-access-to-specific-files
and http://www.coderanch.com/t/84442/Tomcat/write-correct-url-pattern-security -->
  <security-constraint>
    <web-resource-collection>
        <web-resource-name>log files</web-resource-name>
        <description>No direct access to greenstone's logs.</description>
        <url-pattern>/logs/*</url-pattern>
        <http-method>POST</http-method>
        <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
        <description>No direct browser access to log files.</description>
        <role-name>NobodyHasThisRole</role-name>
    </auth-constraint>
  </security-constraint>

Useful information

When you've built a collection of documents, you may discover that there appears to be a copy of all these documents in the collection's import, archives and index subfolders and wonder whether Greenstone could really be so inefficient with space as to keep 3 copies to everything. As it happens though, Greenstone uses hard-links both on Linux and Windows, in order to keep just one set of your documents. Then it simply hardlinks to these, instead of making copies. By default, Windows doesn't show you when files on your filesystem are hard-linked. If you choose to install the Windows extension program Link Shell Extension (LSE), it will put red arrows on files that are hard linked.

Known Issues

Disabling admin access in installer

Currently, even if you don't tick the 'enable admin access' button in the installer, you still get admin access, but with a default password of 'admin'. If you end up in this situation, please change the admin password. Login to the administration page, 'edit' the admin account, adn click 'change password'.

Work Arounds

Greenstone applets (Phind, Collage) crash Firefox

See bugzilla report.

If attempting to view a java applet (like Collage or Phind phrase classifiers) crashes Firefox, then make sure you have the Java Applet plugin installed. If it is installed and Firefox is still crashing, then open firefox and visit the page

about:config

Scroll down to the property:

dom.ipc.plugins.java.enabled

Set it to true (rightclick and choose toggle).