Table of Contents

Setting up Remote Greenstone for Greenstone 3

Preliminary notes for those using the Greenstone 3.03 binary release

if [ ! -f "${thisdir}/client-gli.sh" ]; then

change this to:

if [ ! -f "${thisdir}/client-gli4gs3.sh" ]; then
if exist client-gli.bat goto start

Make sure it says:

if exist client-gli4gs3.bat goto start

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:

cd greenstone3/packages/tomcat/server/lib
 mv servlets-ssi.renametojar servlets-ssi.jar
 mv servlets-cgi.renametojar servlets-cgi.jar

b. On Windows Vista, Tomcat 6 and hence Java 1.5 are required to get the Remote Greenstone server to work. If you're working with Java 5 (1.5) or higher, Greenstone 3 would have set you up with Tomcat 6. In such a case, you will need to adjust the file packages\tomcat\conf\Catalina\localhost\greenstone3.xml to include the line privileged="true" as follows.

<Context path="/greenstone3" 
  docBase="...GS304/web" 
  debug="1" reloadable="true" 
  allowLinking="false"
  privileged="true">
</Context>

There's a CGIServlet element that's commented out; edit the commented out servlet element (or replace it with the servlet element below) so that the live file contains the following.

Code:

<servlet>
        <servlet-name>cgi</servlet-name>
      <servlet-class>org.apache.catalina.servlets.CGIServlet</servlet-class>
        <init-param>
          <param-name>debug</param-name>
          <param-value>6</param-value>
        </init-param>
        <init-param>
          <param-name>cgiPathPrefix</param-name>
          <param-value>WEB-INF/cgi</param-value>
        </init-param>
        <init-param>
           <param-name>passShellEnvironment</param-name>
           <param-value>true</param-value>
         </init-param>
        <init-param>
            <param-name>executable</param-name>
           <param-value>/usr/bin/perl</param-value>
        </init-param>
         <load-on-startup>5</load-on-startup>
    </servlet>

Please note the uppercase letter 'E' in passShellEnvironment above. It was previously entered as lowercase on this page. If at that time you had copied and pasted the text above, it may have caused your remote Greenstone 3 to not work properly. You may then also want to look for any occurrence of "param-alue" in your web.xml file and correct it to "param-value".

NOTE: Specify the full path of the Perl library for the parameter "executable" of CGIServlet. On Linux, it may look like:

<init-param>
 	<param-name>executable</param-name>
        <param-value>/usr/bin/perl</param-value>
  </init-param>

for Windows, it may look like:

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

Uncomment the mapping for the CGI servlet (to uncomment a commented section of XML, remove the that surround the section):

Code:

<servlet-mapping>
        <servlet-name>cgi</servlet-name>
        <url-pattern>/cgi-bin/*</url-pattern>
    </servlet-mapping>

Don't forget to type the 'bin' part in the cgi-bin value for the url-pattern.

ant start

Check that Tomcat and Greenstone3 are working correctly by visiting

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

The port will be "8080" by default, unless you chose another or if this is already in use. If nothing shows up on the page, then try step 1b above.

On Linux, it may look like:

gsdl3srchome    /full/path/to/your/greenstone3
gsdlhome    /full/path/to/your/greenstone3/gs2build

On Windows, it may look like:

gsdl3srchome    "c:\Program Files\greenstone3"
gsdlhome    "c:\Program Files\greenstone3\gs2build"

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\greenstone3\gs2build\bin\windows\perl\bin\perl -w
ant restart

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
("chmod a+rx gliserver4gs3.pl" for those using the Greenstone 3.03 binary release)

Visit

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

in a web browser. (If you're using the Greenstone 3.03 binary release, then replace gliserver.pl in the URL string above with gliserver4gs3.pl.) 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 (see also the javahome property in step 4 above). If you get a "500 Internal Server Error", check the error log of your webserver for the cause (greenstone3/web/logs/greenstone.log).

If the web page that loads is empty, then try step 1b above.

Important: You cannot continue with these instructions until this is successful, as nothing will work without it!

On Unix, use chmod.

On Windows, run in a DOS prompt:

cacls "C:\Program Files\Greenstone3\web\sites\localsite\collect" /P Everyone:F
<serviceRack name="Authentication"/>
# tomcat info
tomcat.server=your-server-computer-name

Now images viewed from a browser on the client side will refer to the correct location on the remote machine.

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.

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

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 **"greenstone3/web/applet"** directory.
* Edit the Greenstone3 "greenstone3/web/interfaces/default/transform/home.xsl" file and uncomment the line below to display an applet gli link on the home page:
<a href="{$library_name}?a=p&amp;amp;sa=gli4gs3">
<xsl:value-of select="util:getInterfaceText($interface_name, /page/@lang, 'home.librarian_interface')"/></a>

Client

The clients can be Linux, Mac OS X or Windows machines. To use the stand-alone GLI client:

(If you're using the Greenstone 3.03 binary release, run "client-gli4gs3.bat" when on Windows or "client-gli4gs3.sh" when on Linux/Mac OS X).

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

On subsequent times, you can use the drop down box to choose a gliserver URL entered earlier.

The first time you run the GLI client on a machine it will ask for the Greenstone3 library. It will be

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

If the URL of the Greenstone3 library is not given, it will ask for the Greenstone3 gliserver URL. The Greenstone3 gliserver URL will be

http://<your-machine-name>:<port>/greenstone3/cgi-bin/gliserver4gs3.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 Greenstone3 user account system is used for authentication. User information is stored in /etc/usersDB of each site, for example, the "web/sites/localsite/etc/usersDb" directory stores users' infomation at site "localsite" , 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 possible group settings are:

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

Note: After the greenstone3 environment has been set, use commands below to export the users table to text or import user records from a txt file.

java org.greenstone.gsdl3.util.usersDB2txt full_path_of_usersDB
java org.greenstone.gsdl3.txt2usersDB full_path_of_the_text_file full_path_of_the_usersDB
~/.gli

On Windows, it is located at:

c:\Documents and Settings\username\Application Data\Greenstone\GLI

Check two arguments ("general.gliserver_url", "general.library_url") of the file if the remote gli couldn't connect to the server. They are like to be:

<Argument name="general.gliserver_url">http://localhost:8080/greenstone3/cgi-bin/gliserver.pl</Argument>
 <Argument name="general.library_url">http://localhost:8080/greenstone3</Argument>

If you're using the Greenstone 3 binary release, look for gliserver4gs3.pl instead of gliserver.pl at the end of the first Argument above.

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.

Things have to be done if GLI needs to be re-compiled

If some changes have been made on the source files of GLI, run makegli.sh and makejar.sh(Linux) (makegli.bat and makejar.bat for Windows) to recompile the GLI. And then, do remember to copy the GLIServer.jar file to Greenstone3/gs2build/bin/java on the Greenstone3 server.

Troubleshooting

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

perlpath /full/path/to/perl/bin/folder

Similarly, if your JAVA_HOME is not set, you can set the JAVA_HOME property in the same manner.

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: