GREENSTONE DIGITAL LIBRARY INSTALLER'S GUIDE

Chapter 2 The Installation Procedure

Contents

Windows
Unix
How to find Greenstone
The Greenstone Librarian Interface (GLI)
Testing and troubleshooting
To learn more

Versions of Greenstone are available for both Windows and Unix, as binaries and in source code form. The Greenstone user interface uses a Web browser: Netscape Navigator or Internet Explorer (version 4.0 or greater in both cases) are both suitable. In case you don't already have a Web browser, Windows versions of Netscape are provided on the CD-ROM.

2.1  Windows

If you are a Unix user, please skip ahead to Section 2.2. For Windows users, if you want just a simple, straightforward installation, go through the following “simple installation” procedure. The Greenstone system occupies about 40 Mb of disk space. For Windows Vista user, go to the 2.1.5 for more instructions on getting Greenstone running on Vista.

If you choose anything other than the default setup, you will have to decide whether you want to install the binary code or the source code. If in doubt, choose the binary code. The installation procedure is the same for both. The following sections tell you more about the options you will be presented with.

When you've finished installation you should skip ahead to Section 2.3.

Simple installation

To install the Windows version from the CD-ROM, insert the disk into the drive (e.g. into D:). If the installation procedure does not start automatically after about 20 seconds, click on the Start menu, select Run and type D:\setup.exe, where “ D ” is the letter that identifies your CD-ROM drive. For Windows 3.1, select Run from the “File manager” and type D:\Windows\win3.1\setup.exe.

For the simplest installation, just accept the default at each point by clicking the Next button. That's all you need to do! Greenstone is installed in the directory C:\Program Files\gsdl.

Once installation is complete, to start your Greenstone system click on the Start button, open the Program menu, and select Greenstone Digital Library. This brings up a dialogue box: just click Enter Library. This automatically starts your Internet browser and loads the Greenstone Digital Library home page, which should look something like the example in Figure 2. You enter the Greenstone Demo collection by clicking on its icon.

Figure 2  Your Greenstone home page


Windows binaries

There are two separate Windows binary programs on the CD-ROM: the Local Library and the Web Library. The default installation described above selects the Local Library version. We strongly recommend that you use this version. The Web Library, which is much harder to set up, is only necessary if you already run a web server and want to use it for Greenstone. Despite its modest name, the Local Library offers a complete, self-contained, web-serving capability.

Local Library. This enables any Windows computer to serve pre-built Greenstone collections. The Greenstone Demo collection will automatically be installed; you can also install the other collections on the CD-ROM (Section 3). The Local Library software is the same as that used on CD-ROMs produced by the Greenstone system.

The Local Library is intended for use on standalone computers or computers that do not already have webserver software. It contains a small built-in webserver so that other computers on the same network can also access the library. (However, the webserver has limited configurability.)

The Local Library software automatically determines whether your computer has network software installed or is connected to a network. It operates correctly under any combinations of these conditions. However, there are two possible problems that may be encountered. Greenstone may

  • cause an unwanted telephone dialup operation;
  • fail to run because network software is installed, but installed incorrectly.

A restricted version of the Local Library is supplied which is intended for use in these situations. The restricted version only works with Netscape (not Internet Explorer). When you invoke the Local Library version of Greenstone, the dialogue box contains a button that allows you to use the restricted version instead. Unless the above problems arise, you should always use the standard version.

Web Library. This enables any computer with an existing webserver to serve pre-built Greenstone collections. As with the Local Library above, the Greenstone Demo collection will automatically be installed. You can also install the other collections on the CD-ROM (see Section 3).

The Web Library differs from the Local Library because it is intended for computers that already have webserver software.

To run the Web Library, you also need

  • Webserver software. One possibility is Apache (see Appendix 7).
  • The Collector. This component, which is included in both the Local Library and the Web Library, allows you to build collections containing material of your choice. (You will not be able to use the Collector on a Windows 3.1/3.11 machine.)

Windows webserver configuration (Web Library version only)

An advantage of the Local Library version of Greenstone is that it runs “out of the box” and does not require any special configuration. For the Web Library version, however, you will have to make some adjustments to your webserver setup.

If you already have a webserver, some small changes have to be made to its configuration to make your Greenstone installation operate. The install script explains what these are for the Apache webserver—see Section 4.2 for instructions for configuring the PWS and IIS webservers. You may need help from a system administrator to reconfigure an existing webserver—they should be able to understand the instructions printed by the install script.

If you do not already have a webserver, you will have to install one. (See the Appendix 7 for information on the Apache webserver.) Then you will have to configure it appropriately. Section 4 gives a detailed account of the parts of a webserver installation that affect Greenstone, and how they need to be altered. It comes down to including half a dozen or so lines in a configuration file.

Windows source

The Greenstone source code occupies 50 Mb of disk space, but to compile it you will need about 90 Mb. To compile the source on Windows you need

  • The Microsoft Visual C++ compiler. (We are currently sorting out some minor problems in compiling Greenstone with various Windows ports of GNU GCC.)

(You do not need GDBM, the Gnu database manager, because it is included in the Greenstone source distribution.)

It is unlikely that you will be able to compile Greenstone on a Windows 3.1/3.11 machine.

In the event that you recompile Greenstone and wish to use the recompiled version to create CD-ROMs, you should note that code produced by recent versions of the Visual C++ compiler does not run under Windows 3.1/3.11, although there is no problem with later Windows systems (95, 98, Me, NT, 2000). If you want your CD-ROMs to operate on early Windows machines, you will need a different version of the compiler. Moreover, Greenstone uses STL, the C++ standard template library, and although these compilers sometimes come with STL, the provided version does not always work properly. Hence to recompile Greenstone in such a way that it produces CD-ROMs that work on early versions of Windows, you need

  • The Microsoft Visual C++ compiler, Version 4.0 or 4.2.
  • An external version of STL, the C++ standard template library. STL is packaged with Greenstone for use with these compiler versions.

Note that the Windows installation procedure does not attempt to compile Greenstone for you if you choose to install the source code. For platform- and compiler-specific instructions on compiling Greenstone, see the Install.txt document which is placed in the top-level Greenstone directory (C:\Program Files\gsdl by default) during the installation procedure.

Windows Vista

If you are using Windows Vista, you need to run the Greenstone installer as an administrator. If you have problems running GLI, it could be because access is denied. Here is a solution thanks to Amanda Hahn.

Running Greenstone in XP compatibility mode does not work. Instead, you MUST change the permissions for the entire greenstone folder otherwise you will keep being told "Access is denied." You must also be an administrator to change this property.

Below are the steps to change the permissions:

  1. Right click on the entire Greenstone program folder (normally under Program Files).
  2. Click Properties. Then Click on the Security tab.
  3. Under Group or User Names, click on Users, then click Edit.
  4. Click on Users again.
  5. Click the checkbox in the window beneath that says Full control in the Allow column.
  6. Here you MUST hit Apply. If you just hit OK the properties won't change. Then hit OK.

2.2  Unix

This section is written for Unix users. (Windows users should skip ahead to Section 2.3.) You need to choose whether to install the binary code or the source code. The binary code occupies about 50 Mb of disk space; the source code requires about 160 Mb to compile.

Unix binaries

The binary code requires an Intel x86-based Linux distribution which includes ELF binary support. Distributions that meet these requirements include:

  • RedHat 5.1
  • SuSE Linux 6.1
  • Debian 2.1
  • Slackware 4.0

More recent versions of these distributions should also work.

You will need a webserver: we recommend Apache. We also strongly recommend you to install your webserver before installing Greenstone—this will make it much easier to answer the questions that are asked during the Greenstone installation procedure. If you want to build new digital library collections, you will also need Perl if this is not already on your system. To check, open a terminal window, type perl —v, and see if a message appears specifying, amongst other things, the version number. For most versions of Linux, Perl is installed by default. The Appendix 7 gives information on how to obtain Apache and Perl.

Unix source

The source code is the same for Unix as for Windows. It has been compiled and tested on Linux, Solaris, and Macintosh OS/X; it should be a fairly routine matter to port it to other flavors of Unix.

To compile the Greenstone source code on Unix, you need

  • GCC, the Gnu C++ compiler.
  • GDBM, the Gnu database manager.

To run the Greenstone software, you also need a Web server and Perl, as described above under Unix binaries.

Unix installation

To install the Unix version from the CD-ROM, insert the disk into the drive, and type

mount /cdrom

mount the CD-ROM device (this command may differ from one system to another; for example on OS/X you cd to the /Volumes directory and then to the appropriate subdirectory for the CD-ROM)

cd /cdrom

change directory to the CD-ROM's top level

cd Unix

change directory to where the Unix install script resides

sh Install.sh

begin the installation process (an explicit sh is used because many installations forbid you to execute programs directly from CD-ROM)


The final command begins an interactive dialogue which requests the information that is needed to install Greenstone on your system, and gives detailed feedback on what is happening.

The installation procedure begins by asking you which directory to install Greenstone into. The first file placed there is the “uninstall” program that cleans up any partial installation, should you encounter problems or terminate the installation prematurely. Next you choose whether you want to install binaries or source code. You are then asked some questions about your webserver setup. You need to have a valid cgi executable directory (normally called “cgi-bin” on Unix systems); you can either create a new one or use your existing one. If you create a new one, you will need to enter this information in your webserver's configuration file. In either case you need to enter the web address of the cgi directory. The installation dialogue will guide you through all these choices. It is important to set the file permissions correctly on certain directories, and you are prompted for the necessary information. Finally, you are prompted for a password for the “administrator” user admin.

By default, all Greenstone software is installed in the directory /usr/local/gsdl if it is the root user who is doing the installation, and into the directory ~/gsdl otherwise (where “~” is the user's home directory).

Installing the binaries takes just a few minutes, enough time for you to answer the appropriate questions. If you install the source code, the installation script will compile it, which takes from ten minutes to an hour or so, depending on the speed of your processor.

To uninstall the software, type

cd ~/gsdl

or /usr/local/gsdl if it was the root user who installed Greenstone

sh Uni nstall.sh

During the installation procedure you will be asked whether you want to install any Greenstone collections. The Greenstone Demo collection is installed automatically; other collections on the CD-ROM are described in Section 3.

Unix webserver configuration

If you already have a webserver, some small changes will have to be made to its configuration to make your Greenstone installation operate. The install script explains what these are. You will probably need help from your system administrator to reconfigure the webserver—he or she should be able to understand the instructions output by the install script. For your convenience, the output of the install script is written to a file called INSTALL_RECORD in the directory into which you installed Greenstone.

If you do not already have a webserver, you will have to install one. The Appendix 7 gives information on Apache. Then you will have to configure it appropriately. Section 4 gives a detailed account of the parts of an Apache webserver installation that affect Greenstone, and how they need to be altered. It comes down to including half a dozen or so lines in a configuration file.

You do not need to be the Unix “root” user to go through the installation procedure above. When it comes to configuring an existing Apache server, however, you may need “root” privileges—it all depends on how Apache is set up. If you install Apache yourself, you can do it as a user without “root” privileges. If you need to work your way around an uncooperative system administrator, you can always install a second Apache webserver on your computer—even if one exists already.

2.3  How to find Greenstone

Local library (Windows only)

If you are using the Local Library, simply run the Greenstone program from the Start menu. This automatically opens a dialog box that starts your Internet browser and loads the Greenstone Digital Library home page. The Greenstone Demo collection should be accessible from this page. The dialog box contais a File menu item that allows you to change the default browser used by Greenstone. It doesn't matter whether you use Netscape or Internet Explorer, except that if you are running on Windows 2000, we recommend that you use Internet Explorer.

Web library (Windows and Unix)

If you are using the Web Library, once you have installed the software and configured the webserver, use this URL to enter your Greenstone system:

http://localhost/gsdl/cgi-bin/library

The Greenstone Demo collection should be accessible from this page.

The Collector

A link to the Collector is provided on the digital library home page.

Administration

A link to the Administration pages is provided on the digital library home page. The “administrator” user is called admin, with a password that you specified during the installation process. The administrator is authorized to add new users, and to build collections.

2.4  The Greenstone Librarian Interface (GLI)

The Greenstone Librarian Interface (GLI) is a tool to assist you with building digital libraries using Greenstone. It gives you access to Greenstone's collection-building functionality from an easy-to-use “point and click” interface.

GLI is installed automatically with all distributions of Greenstone. It is placed in the subdirectory gli of the top-level Greenstone directory (C:\Program Files\gsdl\gli by default). Note that it runs in conjunction with Greenstone and will not work properly unless it is placed in a subdirectory of your Greenstone installation. If you have downloaded one of the Greenstone distributions, this will be the case.

To use the GLI, your computer needs to have the Java Runtime Environment. If it doesn't, the installer will offer to install a version that is included on the CD-ROM. On Unix, you will also need to ensure that Perl is installed (for Windows, Perl is already included in the Greenstone software). Please report any problems you have running or using the Librarian Interface to greenstone@cs.waikato.ac.nz.

Running under Windows

To run GLI under Windows, browse to the gli folder in your Greenstone installation (e.g. using Windows Explorer), and double-click on the file called gli.bat. This file checks that Greenstone, the Java Runtime Environment, and Perl are all installed, and starts the Greenstone Librarian Interface.

Running under Unix

To run GLI under Unix, change to the gli directory in your Greenstone installation, then run the gli.sh script. This script checks that Greenstone, the Java Runtime Environment, and Perl are all installed and on your search path, and starts the Greenstone Librarian Interface.

Getting help

The Greenstone Librarian Interface has extensive on-line help facilities. You get help by clicking the Help button at the top right of the screen. This opens up the text to a section that relates to what you are doing—which of the GLI panels you are on. You can click around the help text to learn what you need to know. Use it.

Compiling the Greenstone Librarian Interface

If you have downloaded the Greenstone source distribution, you will have the Java source code of the Librarian Interface. To compile it, your computer needs to have a Java Development Kit. The Appendix 7 gives information on how to obtain this. To compile the source code, run the makegli.bat(Windows) or makegli.sh(Unix) files. Once compiled, you can run GLI as described above.

2.5  Testing and troubleshooting

To test Greenstone, point your Web browser at the Greenstone home page and explore the Demo collection and any other collections that you have installed. Don't worry—you can't break anything. Click liberally: most images that appear on the screen are clickable. If you hold the mouse stationary over an image, most browsers will soon pop up a message that tells you what will happen if you click. Experiment! Choose common words like “the” and “and” to search for—that should evoke some responses, and nothing will break.For more information, see the Greenstone Digital Library User's Guide.

Troubleshooting

Problem

Try this

Local Library (Windows only)

When I start Greenstone my computer asks me to dial up my Internet Service Provider.

Push the Cancel button in the dialog box. This usually solves the problem.

When I start Greenstone my computer still asks me to dial up my Internet Service Provider.

Choose the “Restricted version” when you run Greenstone. This version only works with Netscape.

When I point my browser at the digital library, it can't find that page.

Check your Internet Proxy settings and turn proxies off (use Edit preferences on Netscape or Internet options on Explorer).

The Collector seems to be working very slowly!

Are you using Netscape under Windows 2000? If so, try using Internet Explorer instead—on Windows 2000 (only) there seems to be some incompatibility with Netscape.

Web Library (Windows and Unix)

When I start Apache, it quits immediately.

Add a ServerName localhost directive to the Apache configuration file (see Section 4.1).

When I point my browser at the digital library, it displays garbage—a binary file.

Check the ScriptAlias directive in the Apache configuration file, making sure it comes before the Alias directive (see Sections 4.2 and 4.3).

I get the Greenstone home page (Figure 2), but the Demo collection icon does not appear.

Run the program library (in the cgi-bin directory) from the DOS (or shell) prompt to generate debugging information that will help you locate the problem.

Both versions

When I point my browser at the digital library, it can't find that page.

Try using 127.0.0.1 in place of localhost. This reserved IP number is defined to be a “loopback” to your local computer.

My browser complains that it can't find main.cfg.

Check that the Greenstone files exist and are world-readable. If you are using the Web library, try running the library program from the command line. If it runs OK, the problem is with file permissions (see Section 5.1). If not, the gsdlhome variable is probably set incorrectly in the gsdlsite.cfg configuration file (see Section 5.2).

I'm having trouble using the Collector.

Read the Greenstone Digital Library User's Guide, Section .

I've added a new user but they can't seem to log in.

Check that the directory C:\Program Files\gsdl\etc and all its contents are globally writeable (see Section 5.1).


2.6  To learn more

To learn more about the innards of your Greenstone installation, consult the Greenstone Digital Library Developer's Guide. It includes (for example) details of the directory structure that has been created, and information about how to configure your Greenstone site.


Copyright © 2002 2003 2004 2005 2006 2007 by the New Zealand Digital Library Project at the University of Waikato, New Zealand.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”