Remote Greenstone

Remote Greenstone

From GreenstoneWiki

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.4 or newer).

To install the server-side functionality:

  1. Download Greenstone v2.72 and install it. Choose the "Web Library" installation option.
  2. Configure your webserver for use with Greenstone:
    Apache v2.0 (Download)
    After installation, configure Apache by editing the conf\\httpd.conf file as described in the Greenstone Installer's Guide or in the library.txt file installed in the Greenstone directory. Start Apache.
    Apache v1.3
    Apache v1.3 is not suitable for this application; use Apache v2.0 instead.
    IIS (Not recommended)
    See this page. Then right-click on the "cgi-bin" folder, choose Properties, and click Configuration. Add an extension for ".pl", specifying the Greenstone "bin/windows/perl/bin/perl" binary as the executable, with arguments "%s" %s.
    IIS 6: Edit the Greenstone "cgi-bin/gliserver.pl" file and set the "iis6_mode" option to "1".
    Check that your webserver and Greenstone are working correctly by visiting 
    http://<your-machine-name>:<port>/gsdl/cgi-bin/library
    (library.exe on Windows). The port will be "80", unless this is already in use.
  3. 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 will be (if installed in the default location): 

        #!C:\\Program Files\\Greenstone\\bin\\windows\\perl\\bin\\perl -w
  4. Visit 
    http://<your-machine-name>:<port>/gsdl/cgi-bin/gliserver.pl?cmd=check-installation
    in a web browser. You should get a message saying "Java found" and "Installation OK!". If you get a message saying "Java failed", check that the Java run-time is installed and on the webserver's path. If you get a "500 Internal Server Error", check the error log of your webserver for the cause.
    Important: You cannot continue with these instructions until this is successful, as nothing will work without it!
  5. Make the Greenstone "collect" directory writeable by the webserver user.
    On Unix, use chmod.
    On Windows, run in a DOS prompt: 
        cacls "C:\\Program Files\\Greenstone\\collect" /P Everyone:F
  6. Add some user accounts by visiting the Greenstone home page and clicking the "Administration Page" button, then "add a new user". See the Authentication section below for more information.

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.

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.

  1. In the Greenstone "gli" directory, run 
        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".
  2. Run 
        jarsigner -keystore appletstore -signedjar SignedGatherer.jar GLI.jar privateKey
    When it prompts, enter the password you used above.
  3. Move the created SignedGatherer.jar file into the Greenstone "bin/java" directory.
  4. 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:

  1. Download gli-client-2.72.zip (5MB) and unzip it.
  2. Run "client-gli.bat" (Windows) or "client-gli.sh" (Linux/Mac OS X). The first time you run the GLI client on a machine it will ask for the Greenstone library and gliserver URLs. These will be 
    http://<your-machine-name>:<port>/gsdl/cgi-bin/library
    (library.exe if the server is Windows) and 
    http://<your-machine-name>:<port>/gsdl/cgi-bin/gliserver.pl
    respectively.

To use the GLI applet:

  1. Visit your Greenstone library homepage and click "The Librarian Interface", half-way down the page. The GLI applet will begin loading, and after a short wait a "Launch Greenstone Librarian Interface" button will become available. Click this to start using 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:

  • all-collections-editor: Users in this group can create new collections and edit all collections. (Equivalent to the "remote-superuser" group of Greenstone v2.70w and earlier).
  • personal-collections-editor: Users in this group can create and edit "personal" collections. Personal collections have the user's username at the start of the internal collection name, and are created when the "this is a personal collection" option is ticked in the GLI "New Collection" dialog.
  • <collection-name>-collection-editor: Users is this group can create and edit the "<collection-name>" collection. (Equivalent to the "<collection-name>-maintainer" group of Greenstone v2.70w and earlier).

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:

  • The Download pane
  • The File → Write CD/DVD Image... menu item
  • The File → Export... menu item
  • The Rename option when right-clicking on a file or folder in the collection tree (will be available in Greenstone 2.73)
  • The Replace option when right-clicking on a file or folder in the collection tree

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:

  1. Make sure you are using the latest version of Greenstone and have downloaded any patches on this page.
  2. Record any popup GLI error messages, and the last action you performed.
  3. Check for Java exceptions. If you're using the client version of the GLI, these will appear in the black GLI window (Windows) or in the terminal where you ran the GLI (Unix). If you're using the applet version of the GLI, these will appear in the Java Console (available from one of your browser menus -- for Firefox you may have to download this extension).
  4. Check for errors at the bottom of the log files of your webserver. If you're using Apache (recommended), look in the "error_log" file in the Apache "logs" directory.
  5. If you are having problems with the applet version, please check if you have the same problems with the client version.
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:
  • The operating system of the server machine
  • The version of Greenstone installed on the server machine
  • The version of Java installed on the server machine
  • The operating system of the client machine
  • Whether you are using the client or applet version of the GLI
  • The actions you performed leading up to where the error or problem occurs
  • The complete text of any popup GLI error messages, exceptions or errors in the webserver log file

Miscellaneous problems

  • "Premature EOF" errors when building collections are caused by the webserver timing out when no output is generated by the build scripts for some time. The solution is to increase the webserver's timeout setting. For Apache this means increasing the "Timeout" value in the conf/httpd.conf file (don't forget to restart Apache).


Future Work

  • When trying to load the dictionary (in Dictionary.java: ResourceBundle.getBundle(...)), the applet looks in the wrong place initially, causing errors in the Apache error_log. Finding some way of telling Java to look in the JAR file immediately would be nice.
  • Pressing the "Cancel Build" button during the importing or building process doesn't have an immediate effect. The GLI code needs to be changed so GShell (and at a further level, RemoteGreenstoneServer) is a listener on the Cancel button. This will mean the cancel event can be processed much quicker.
  • When the GLI is quit with jobs still on the remote Greenstone server queue, it will wait until these are finished before exiting. A dialog telling the user what is happening would be nice. This should probably have a "force quit" button, even if this is not recommended.
  • Loading the options for DBPlug.pm causes an exception when using a Windows server. If you need to use DBPlug then you must install the DBI and DBD modules that it requires.