Table of Contents

Setting up Remote Greenstone for Greenstone 2

Building Greenstone collections remotely

Until now, using the GLI has required either a complete Greenstone installation, or the GLI applet to be installed on a server machine. In both cases, collaboration on collections is not possible.

This new functionality keeps the collections on a remote Greenstone server, thus allowing users to collaborate on collections (at different times), and without a local Greenstone installation.

Installation

This section describes how to install the remote building functionality on server and client.

Server

The server can be a Linux, Mac OS X or Windows machine. It must have the Java run-time installed (version 1.5 or newer). Note that a binary install of Greenstone includes Java.

To install the server-side functionality:

On Windows: before running the apache web server, rename the Greenstone local library server file server.exe (located in your toplevel Greenstone directory) to something else.

Check that your webserver and Greenstone are working correctly by visiting

http://<your-machine-name>:<port>/greenstone/cgi-bin/library.cgi

(For Greenstone 2.81 and older:

The port will be the number you configured your Apache web server to listen on. This tends to be 8080 or 80, unless these are already in use.

Note: In Greenstone 2.83 and onwards, you should be able to skip this step if you are using a release of Greenstone from an installer, as the installer automatically does the replacement.

Edit the first line of the Greenstone "cgi-bin/gliserver.pl" file and specify the full path of the perl binary.

On Unix it is likely to be:

    #!/usr/bin/perl -w

On Windows this would be something like (if installed in the default location):

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

Note that when using Greenstone 2.82 on Windows, it has the path to perl slightly wrong, so do correct it: …\bin\windows\perl\bin\perl

in a web browser. (In Greenstone 2.81 and earlier, visit http://<your-machine-name>:<port>/gsdl/cgi-bin/gliserver.pl?cmd=check-installation.) You should get a message saying "Java found" and "Installation OK!".

Otherwise, if you're on Linux, it may have to do with not having executable permissions on gliserver.pl. Open an x-term and cd into your greenstone installation folder's cgi-bin folder. There, type:

./gliserver.pl

If it returns a message like "bash: ./gliserver.pl: Permission denied", then type the following to make it executable:

chmod a+rx gliserver.pl

Now see if it works.

Important: Do not continue with these instructions until this is successful, because otherwise nothing will work!

On Unix, use chmod.

On Windows, if using the included Apache web server, it will run under your User Account and the following tends not to be necessary. Otherwise, you would run the following in a DOS prompt:

    cacls "C:\Program Files\Greenstone\collect" /P Everyone:F

If you're working in a language other than English (say German or French), the word "Everyone" in the command above could well be in the language your machine is set to. For instance "Tout le monde" in French (use quotes since it is more than one word).

# Set status to "enabled" if you want the Maintenance and
# Administration facility to be available.
status  	enabled

This will make the "Administration Page" button appear on the Greenstone home page.

./makejar.sh

On Windows, you'd type the following in the DOS prompt:

makejar.bat

This will create the GLIServer.jar file in the gli folder which you can manually copy into the bin/java folder.

If your end users will use the stand-alone GLI client, this is all that is required on the server, and you can skip the next section.

GLI Applet Additional Steps

If your end users will be using the GLI applet, you also need to do the following four steps. These require the Java SDK – if you don't already have this you can download it from here; make sure that the Java SDK's bin directory is included in the PATH environment variable, which may not have been done automatically upon installation.

    keytool -genkey -alias privateKey -keystore appletstore -storepass greenstone
Enter the appropriate details for your organization. When it asks to enter the key password for <privateKey>, choose your own password or hit Enter to use "greenstone".
* Run
    jarsigner -keystore appletstore -signedjar SignedGatherer.jar GLI.jar privateKey
When it prompts, enter the password you used above.
* Move the created SignedGatherer.jar file into the Greenstone "bin/java" directory.
* Edit the Greenstone "etc/main.cfg" file and set the "gliapplet" field to "enabled".

Client

The clients can be Linux, Mac OS X or Windows machines.

To use the stand-alone GLI client:

The first time you run the GLI client on a machine it will ask for the Greenstone library and gliserver URLs. The first will be

http://<your-machine-name>:<port>/gsdl/cgi-bin/library.cgi

Alternatively, if you are using an older version of Greenstone (2.81 and earlier), this URL will end on "library.exe" if the server is Windows and "library" on Linux. The gliserver URL it requires will be

http://<your-machine-name>:<port>/gsdl/cgi-bin/gliserver.pl

To use the GLI applet:

You can now use the GLI to edit collections on the server or create new collections. The first time a collection is opened on a particular machine the GLI will read the plugin and classifier information from the server (this may take a minute or two).

Notes

General

There can be a lot of data transferred between the client and the server. This can make using the client impractical if you don't have a high speed connection between it and the server.

Authentication

The existing Greenstone user account system is used for authentication. User information is stored in the etc/users.db file, and the Administration pages (linked from your Greenstone library homepage) are used for adding, editing and removing users.

Groups are used to control the actions that users are allowed to perform on collections. The group settings have changed for Greenstone v2.71, and you will need to edit your existing users if you are upgrading. The possible group settings are:

For example, a user who needs to create and edit their own collections, and collaborate with others on a shared "papers" collection, should be in the "personal-collections-editor", and "papers-collection-editor" groups.

Collection locking

Each collection may only be open by one person at a time, to prevent synchronization problems. When a request is sent to the server to perform an action on a collection, the server will check for a gli.lck file in the collection directory. This file contains the username of the person who has the collection locked. When the collection is closed, this lock file is deleted.

If the collection is locked by someone other than the person making the request, the action fails. This is reported to the user on the client side, and this user is given the option of "stealing" the lock. Generally this is not recommended, since work may be lost if multiple users are editing a collection at one time. Stealing the lock should only be done in the case where the GLI has exited abnormally and the lock file was not deleted, and only after consulting with the user who has the collection locked.

E-mail notifications

The server can be configured to e-mail the system administrator whenever a collection finishes building. To enable this, edit the Greenstone "cgi-bin/gliserver.pl" file and set "$mail_enabled" to "1", and "$mail_to_address", "$mail_from_address", and "$mail_smtp_server" appropriately.

Missing functionality

There are a few items of functionality that are available in the standalone GLI but not in the client/applet version. These are:

This functionality may be added in the future.

Troubleshooting

If you are experiencing problems or error messages when using the client/server version of the GLI, please follow these steps:

If you think you have found a bug, or still can't get this functionality working, send a message to the Greenstone Users mailing list. Please include the following information:

Miscellaneous problems

"$javapath" -Xmx128M -classpath classes/:GLI.jar Add -Xss16M after the -Xmx128M, which increases the stack size from 2 to 16M. On Windows, in gli.bat, look for the lines starting "%JAVA_EXECUTABLE%" -Xmx128M -cp classes/;GLI.jar and do the same thing.

Future Work