Greenstone Wiki

• Download the appropriate release for your operating system and run it.
• For Linux, you will need to set the file to be executable before running it. (e.g. chmod a+x Greenstone-3.05-linux)
  • The installer initially unpacks into a temporary directory (/tmp on linux). Set TMPDIR environment variable to change this.

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

• Folder where you want greenstone3 to be installed.
• Choosing which packages to install.
  • Greenstone3 will install the Apache Tomcat webserver by default. You can choose not to install it, but then you will need to set up your own version of Tomcat to serve Greenstone. We recommend using Greenstone's Tomcat, at least initially while you get everything set up.
  • ImageMagick is bundled with Greenstone for binary web releases for all platforms, and includes JPEG2000 support. You can choose not to install it if you already have ImageMagick previously installed.
  • Ghostscript is now bundled with Greenstone for binary web releases for Windows and Mac. You can choose not to install it if you already have Ghostscript previously installed.
• Enabling administration pages. (Note, disabling admin pages currently doesn't work. Please enable them and choose a password, otherwise you'll have an admin user with password admin). These pages allow the admin user to inspect and manage the list of registered Greenstone users. You can add new users, and change group settings for existing users. Greenstone user registration is needed if you want to use remote GLI login to the Greenstone server, or if you want to make collections/documents only accessible by certain groups of users. If you choose to enable admin pages, you will be asked to choose a password for the admin user. If admin pages are not enabled initially, they can be enabled later on by TODO-add instructions here. The default password for the admin user is 'admin'. Once you have enabled admin pages, please login in immediately as the admin user (from the login button at the top right of the page). Then click the admin button (top right) and select account settings. Change the password there.

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.

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.

• Download the source code component and unpack it into the top level Greenstone3 folder. For Linux/Mac, please use the tar.gz version as zip doesn't preserve necessary file permissions.
• You will need to have a Java development kit (JDK) installed, version 1.5 or later. Binary Greenstone3 releases come with a JRE installed which is used by default. Please rename the packages/jre folder to something else, then set JAVA_HOME to the root of your JDK installation, and add $JAVA_HOME/bin (or %JAVA_HOME%\bin for windows) to your PATH.
• Then run ant install to compile the source code.
• Note: currently the source code won't compile if installed into a path with spaces.

• Linux and Mac: If it stops with an error about wvware, please download an appropriate (for your OS) version of gnome-lib, from trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk. Just use the minimal version. Download it into greenstone3/gs2build/ext. Unpack it there, then cd to gnome-lib-minimal and run source devel.bash. Cd back to the top level greenstone3 folder, and run ant install again.

• Download the tar.gz source release (Linux/Mac) or .zip release (Windows) and unpack it into a directory without spaces in the path. Rename the top level folder if you want.
• You will need to have a Java development kit (JDK) installed, version 1.5 or later. Set JAVA_HOME to the root of your JDK installation, and add $JAVA_HOME/bin (or %JAVA_HOME%\bin for windows) to your PATH.
• The source distribution comes with Ant. In the top level directory, run source gs3-setup.sh (Linux/Mac) or gs3-setup (Windows) to set up paths for Ant.
• Run ant install.

• Linux and Mac: If it stops with an error about wvware, please download an appropriate (for your OS) version of gnome-lib, from trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk. Just use the minimal version. Download it into Greenstone-3.05-source-distribution/gs2build/ext. Unpack it there, then cd to gnome-lib-minimal and run source devel.bash. Cd back to the top level Greenstone-3.05-source-distribution folder, and run ant install again.

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.

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"

• 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 (greenstone3/web/logs/greenstone.log).
• consult the more detailed instructions at Remote Greenstone for further steps that may be necessary

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.

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

• The majority of the visual elements in the interface are built using jquery-ui, this allows the look and feel of the interface to be easily modified by creating custom themes. Jquery-ui provides a theme-roller service that allows easy creation of these themes. Collection administrators can change the theme in the collection preferences.

• If a document has both a screen image and a source image and the source image is at least 20% larger than the screen image, then you will be given a zoom option. When enabled, moving the cursor over the image will display a zoomed view of the image.

• Quick text search has been added to (nearly) every page, allowing easy searching from anywhere in a collection. The more advanced search types are still available and can be accessed with the links below the quick search area.

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):

• "basic" is previous Greenstone 3 default interface.
• "gs2" is the greenstone 2 look-alike interface.

The default servlets have also been renamed as follows:

• "dev" (which was the development servlet) is now the main servlet and is therefore called "library".
• "gs3library" (the previous Greenstone 3 main servlet) is now called "gs3-library".
• "library" (the previous Greenstone 2 look-alike servlet) is now called "gs2-library".

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:

• http://localhost:8383/greenstone3/library?a=d&c=examplecol&d=HASH1234ABCD&dt=hierarchy

it can now be accessed with the URL:

• http://localhost:8383/greenstone3/library/collection/examplecol/document/HASH1234ABCD.

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

• Includes all patches mentioned on 2.85 Release Notes patch section (PDFBox, OAI Downloading, Extracting metadata from OAI files, Email Plugin).
• New script activate.pl, which deactivates a collection in a persistant server, moves building to index, then reactivates the collection.

• If CJK text segmentation is selected in GLI, then the runtime system needs to do the same segmentation on the query.
• sqlite can be used as the database for a collection, but the Greenstone 3 runtime can't serve it, so the sqlite option has been hidden for now.

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.

• Exploding from GLI now works in a Greenstone 3 environment.
• Format features in Format panel now uses RSyntaxTextArea. This provides coloured highlighting, auto completion of end tags and ctrl-Z for undo.
• The Format Features panel now correctly indents XML.

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>

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.

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

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