GREENSTONE DIGITAL LIBRARY

INSTALLERS GUIDE

IanH.WittenandStefanBoddie
DepartmentofComputerScience
UniversityofWaikato,NewZealand

Greenstoneisasuiteofsoftwareforbuildinganddistributingdigital
librarycollections.Itprovidesanewwayoforganizinginformation
and publishing it on the Internet or on CDROM. Greenstone is
producedbytheNewZealandDigitalLibraryProjectattheUniversity
of Waikato, and developed and distributed in cooperation with
UNESCO and the Human Info NGO. It is opensource software,
available from http://greenstone.org under the terms of the GNU
GeneralPublicLicense.

Greenstonegsdl2.50

March2004

iiAPPENDIXBGLOSSARYOFTERMS
Wewanttoensurethatthissoftwareworkswellforyou.Please
reportanyproblemstogreenstone@cs.waikato.ac.nz

greenstone.org

About this manual

ThisdocumentexplainshowtoinstallGreenstonesothatyoucanrunit
on your own computer. It also describes how to obtain associated
softwarethatisfreelyavailablethe ApacheWebserverandPerl.We
havestriventomaketheinstallationprocedureassimpleasitpossibly
canbe.
Thesoftwarerunsondifferentplatforms,andindifferentconfigurations.
Consequently there are many issues that affect (or might affect) the
installationprocedure.Section1mentionssomequestionsthatyouwill
need to consider before installing Greenstone. Section 2 details the
installationprocedureforallthedifferentversions;youneedonlyreadthe
part that relates to your operating system. Section 3 describes the
demonstration digital library collections that are included in the
distribution. Section 4 explains how to set up common webservers,
Apache and Microsoft PWS/IIS, to work with Greenstone. Section 5
describesvariousGreenstoneconfigurationoptions,andSection6shows
how to make a personalized home page for your digital library
installation.Finally,anAppendix listspiecesofassociatedsoftwareand
howtoobtainthem.

Companion documents
ThecompletesetofGreenstonedocumentsincludefivevolumes:
GreenstoneDigitalLibraryInstallersGuide(thisdocument)
GreenstoneDigitalLibraryUsersGuide
GreenstoneDigitalLibraryDevelopersGuide
GreenstoneDigitalLibrary:FromPapertoCollection
GreenstoneDigitalLibrary:UsingtheOrganizer

ivCONTENTS

Acknowledgements
TheGreenstonesoftwareisacollaborativeeffortbetweenmanypeople.
Rodger McNab and Stefan Boddie are the principal architects and
implementors. Contributions have been made by David Bainbridge,
George Buchanan,HongChen,MichaelDewsnip,KatherineDon,Elke
Duncker,CarlGutwin,GeoffHolmes, DanaMcKay, John McPherson,
Craig NevillManning, Dynal Patel, Gordon Paynter, Bernhard
Pfahringer,ToddReed,BillRogers,JohnThompson,andStuartYeates.
Other members of the New Zealand Digital Library project provided
adviceandinspirationinthedesignofthesystem:MarkApperley,Sally
JoCunningham,MattJones,SteveJones,TeTakaKeegan,MichelLoots,
Malika Mahoui, Gary Marsden, Dave Nichols and Lloyd Smith. We
wouldalsoliketo acknowledge all thosewhohavecontributedtothe
GNUlicensed packages included in this distribution: MG, GDBM,
PDFTOHTML,PERL,WGET,WVWAREandXLHTML.

CONTENTS
About this manual

ii

1 VERSIONS OF GREENSTONE

2 THE INSTALLATION PROCEDURE

2.1

Windows
Simple installation
Windows binaries
Windows webserver configuration (Web Library version only)
Windows source

3
3
4
5
6

2.2

Unix
Unix binaries
Unix source
Unix installation
Unix webserver configuration

7
7
7
8
9

2.3

How to find Greenstone

Local library (Windows only)
Web library (Windows and Unix)
The Collector
Administration

10
10
10
10
10

2.4

The Greenstone Librarian Interface (GLI)

Running under Windows
Running under Unix
Getting help
Compiling the Greenstone Librarian Interface

10
11
11
11
11

2.5

Testing and troubleshooting

Troubleshooting

12
12

viCONTENTS
2.6

To learn more

13

3 GREENSTONE COLLECTIONS

14

4 SETTING UP THE WEBSERVER

17

4.1

The Apache web server

Setting up the Greenstone cgi-bin directory
The document root directory
Security

18
18
19
20

4.2

The PWS and IIS webservers

20

5 CONFIGURING YOUR SITE

23

5.1

File permissions

23

5.2

The gsdlsite.cfg configuration file

24

6 PERSONALIZING YOUR INSTALLATION

27

6.1

Example

27

6.2

How to make it work

29

6.3

Redirecting a URL to Greenstone

29

APPENDIX ASSOCIATED SOFTWARE

31

A.1

Apache Webserver

31

A.2

Perl

31

A.3

GCC

31

A.4

GDBM

31

A.5

Java runtime environment

32

A.6

Java compiler

32

vii

greenstone.org

1
Versions of Greenstone
The Greenstone software runs on different platforms, and in different
configurations,assummarizedinFigure1.
WindowsorUnix?

3.x

Servescollections
butnobuilding

Windows

Unix

Binariesavailable
forallversions

Mayneedroot
logintoinstall

95/98/Me

NT/2000

Linux

SunSolarisor
MacintoshOS/X

Other

Fullversion
available

Fullversion
available

Fullversion
available

Fullversion
available

Fullversion
available

Sourcecodetested,
binariesavailable

Sourcecode
tested

Untested

OnlyAdministrators
caninstallsoftware

Figure1ThedifferentoptionsforWindowsandUnixversionsofGreenstone
There are many issues that affect (or might affect) the installation
procedure.Beforereadingon,youshouldconsiderthesequestions:
AreyouusingWindowsorUnix?
IfWindows,areyouusingWindows3.1/3.11oramorerecent
version?Althoughyoucanviewcollectionson3.1/3.11machines,
andserveothercomputersonthesamenetwork,youcannotbuild
newcollections.ThefullGreenstonesoftwarerunson95/98/Me,
andNT/2000.
IfUnix,areyouusingLinuxoranotherversionofUnix?ForLinux,

2VERSIONSOFGREENSTONE
abinaryversionofthecompletesystemisprovidedwhichiseasyto
install.ForothertypesofUnixyouwillhavetoinstallthesource
codeandcompileit.Thismayrequireyoutoinstallsomeadditional
softwareonyourmachine.
IfWindowsNT/2000orUnix,canyouloginasthesystem
administratororroot?Thismayberequiredtoconfigurea
webserverappropriatelyforGreenstone.
Doyouwantthesourcecode?IfyouareusingWindowsorLinux,
youcanjustinstallbinaries.Butyoumaywantthesourcecodeas
wellitsintheGreenstonedistribution.
Doyouwanttobuildnewdigitallibrarycollections?Ifso,youneed
tohavePerl,whichisfreelyavailableforbothWindowsandUnix.
Isyourcomputerrunningawebserver?TheGreenstonesoftware
comeswithaWindowswebserver.However,ifyouarealready
runningaWebserver,youmaywanttostaywithit.ForUnix,you
needtorunawebserver.
Doyouknowhowtoreconfigureyourwebserver?Ifyoudontuse
theGreenstonewebserver,youwillhavetoreconfigureyour
existingoneslightlytorecognizetheGreenstonesoftware.

greenstone.org

2
The Installation Procedure
Versions of Greenstone are available for both Windows and Unix, as
binariesandinsourcecodeform.TheGreenstoneuserinterfaceusesa
Webbrowser: NetscapeNavigatororInternet Explorer(version4.0or
greaterinbothcases)arebothsuitable.Incaseyoudontalreadyhavea
Webbrowser,Windowsversionsof Netscape are providedontheCD
ROM.

2.1 Windows
IfyouareaUnixuser,pleaseskipaheadtoSection2.2.ForWindows
users,if youwantjustasimple,straightforwardinstallation,gothrough
the following simple installation procedure. The Greenstone system
occupiesabout40Mbofdiskspace.
Ifyouchoose anythingother thanthedefault setup,youwill have to
decidewhetheryouwanttoinstallthebinarycodeorthesourcecode.If
indoubt,choosethebinarycode.Theinstallationprocedureisthesame
forboth.Thefollowingsectionstellyoumoreabouttheoptionsyouwill
bepresentedwith.
WhenyouvefinishedinstallationyoushouldskipaheadtoSection2.3.
Simple installation
ToinstalltheWindowsversionfromtheCDROM,insertthediskinto
the drive (e.g. into D:). If the installation procedure does not start
automaticallyafterabout20seconds,clickontheStartmenu,selectRun
andtype D:\setup.exe,whereDistheletterthatidentifiesyourCD
ROMdrive.ForWindows3.1,select Run fromtheFilemanagerand
typeD:\Windows\win3.1\setup.exe.
For the simplest installation, just accept the default at each point by

4INSTALLATIONPROCEDURE
Figure2
YourGreenstone
homepage

clickingtheNextbutton.Thatsallyouneedtodo!Greenstoneisinstalled
inthedirectoryC:\ProgramFiles\gsdl.
Onceinstallationiscomplete,tostartyourGreenstonesystemclickonthe
Start button, open the Program menu, and select Greenstone Digital
Library. Thisbringsupadialoguebox:justclick EnterLibrary. 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
clickingonitsicon.
Windows binaries
TherearetwoseparateWindowsbinaryprogramsontheCDROM:the
Local Library and the Web Library.The default installationdescribed
aboveselectstheLocalLibraryversion.Westronglyrecommendthatyou
usethisversion.TheWebLibrary,whichismuchhardertosetup,isonly
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,selfcontained,webservingcapability.
LocalLibrary. ThisenablesanyWindowscomputertoserveprebuilt

INSTALLATIONPROCEDURE5
Greenstone collections. The Greenstone Demo collection will
automaticallybeinstalled;youcanalsoinstalltheothercollectionsonthe
CDROM(Section3).TheLocal Librarysoftwareisthesameasthat
usedonCDROMsproducedbytheGreenstonesystem.
The Local Library is intended for use on standalone computers or
computers that do not already have webserver software. It contains a
smallbuiltinwebserversothatothercomputersonthesamenetworkcan
also access the library. (However, the webserver has limited
configurability.)
The Local Library software automatically determines whether your
computerhasnetworksoftwareinstalledorisconnectedtoanetwork.It
operatescorrectlyunderanycombinationsoftheseconditions.However,
there are two possible problems that may be encountered. Greenstone
may
causeanunwantedtelephonedialupoperation;
failtorunbecausenetworksoftwareisinstalled,butinstalled
incorrectly.
ArestrictedversionoftheLocalLibraryissuppliedwhichisintendedfor
useinthesesituations.TherestrictedversiononlyworkswithNetscape
(notInternetExplorer).WhenyouinvoketheLocalLibraryversionof
Greenstone,thedialogueboxcontainsabuttonthatallowsyoutousethe
restrictedversioninstead.Unlesstheaboveproblemsarise,youshould
alwaysusethestandardversion.
WebLibrary.Thisenablesanycomputerwithanexistingwebserverto
serveprebuiltGreenstonecollections.AswiththeLocalLibraryabove,
theGreenstoneDemocollectionwillautomaticallybeinstalled.Youcan
alsoinstalltheothercollectionsontheCDROM(seeSection3).
TheWebLibrarydiffersfromtheLocalLibrarybecauseitisintendedfor
computersthatalreadyhavewebserversoftware.
ToruntheWebLibrary,youalsoneed
Webserversoftware.OnepossibilityisApache(seeAppendix).
TheCollector.Thiscomponent,whichisincludedinboththeLocal
LibraryandtheWebLibrary,allowsyoutobuildcollections
containingmaterialofyourchoice.(Youwillnotbeabletousethe
CollectoronaWindows3.1/3.11machine.)

6INSTALLATIONPROCEDURE
Windows webserver configuration (Web Library version only)
AnadvantageoftheLocalLibraryversionofGreenstoneisthatitruns
outoftheboxanddoesnotrequireanyspecialconfiguration.Forthe
WebLibraryversion,however,youwillhavetomakesomeadjustments
toyourwebserversetup.
Ifyoualreadyhaveawebserver,somesmallchangeshavetobemadeto
itsconfigurationtomakeyourGreenstoneinstallationoperate.Theinstall
scriptexplainswhatthesearefortheApachewebserverseeSection4.2
forinstructionsforconfiguringthePWSandIISwebservers.Youmay
need help from a system administrator to reconfigure an existing
webservertheyshouldbeabletounderstandtheinstructionsprintedby
theinstallscript.
Ifyoudonotalreadyhaveawebserver,youwillhavetoinstallone.(See
theAppendix forinformationontheApachewebserver.)Thenyouwill
havetoconfigureitappropriately.Section 4 givesadetailedaccountof
thepartsofawebserverinstallationthataffectGreenstone,andhowthey
needtobealtered.Itcomesdowntoincludinghalfadozenorsolinesina
configurationfile.
Windows source
TheGreenstonesourcecodeoccupies50Mbofdiskspace,buttocompile
ityouwillneedabout90Mb. Tocompile the sourceonWindowsyou
need
TheMicrosoftVisualC++compiler.(Wearecurrentlysortingout
someminorproblemsincompilingGreenstonewithvarious
WindowsportsofGNUGCC.)
(You do not need GDBM, the Gnu database manager, because it is
includedintheGreenstonesourcedistribution.)
ItisunlikelythatyouwillbeabletocompileGreenstoneonaWindows
3.1/3.11machine.
In the event that you recompile Greenstone and wish to use the
recompiled version to create CDROMs, you should note that code
producedby recent versions oftheVisual C++compilerdoesnotrun
under Windows 3.1/3.11, although there is no problem with later
Windowssystems(95,98,Me,NT,2000).IfyouwantyourCDROMsto
operateonearlyWindowsmachines,youwillneedadifferentversionof

INSTALLATIONPROCEDURE7
thecompiler.Moreover,GreenstoneusesSTL,theC++standardtemplate
library, and although these compilers sometimes come with STL, the
provided version does not always work properly. Hence to recompile
GreenstoneinsuchawaythatitproducesCDROMsthatworkonearly
versionsofWindows,youneed
TheMicrosoftVisualC++compiler,Version4.0or4.2.
AnexternalversionofSTL,theC++standardtemplatelibrary.STL
ispackagedwithGreenstoneforusewiththesecompilerversions.
NotethattheWindowsinstallationproceduredoesnotattempttocompile
Greenstoneforyouifyouchoosetoinstallthesourcecode.Forplatform
and compilerspecific instructions on compiling Greenstone, see the
Install.txtdocumentwhichisplacedinthetoplevelGreenstonedirectory
(C:\ProgramFiles\gsdlbydefault)duringtheinstallationprocedure.

2.2 Unix
ThissectioniswrittenforUnixusers.(Windowsusersshouldskipahead
toSection2.3.)Youneedtochoosewhethertoinstallthebinarycodeor
thesourcecode.Thebinarycodeoccupiesabout50Mbofdiskspace;the
sourcecoderequiresabout160Mbtocompile.
Unix binaries
The binary code requires an Intel x86based Linux distribution which
includesELFbinarysupport.Distributionsthatmeettheserequirements
include:
RedHat5.1
SuSELinux6.1
Debian2.1
Slackware4.0
Morerecentversionsofthesedistributionsshouldalsowork.
Youwillneedawebserver: werecommendApache. Wealsostrongly
recommendyoutoinstallyourwebserverbeforeinstallingGreenstone
thiswillmakeitmucheasiertoanswerthequestionsthatareaskedduring
theGreenstoneinstallationprocedure. Ifyouwanttobuildnewdigital
librarycollections,youwillalsoneedPerlifthisisnotalreadyonyour
system.Tocheck, openaterminalwindow, type perlv, andseeifa
messageappearsspecifying,amongstotherthings,theversionnumber.
FormostversionsofLinux,Perlisinstalledbydefault. TheAppendix

8INSTALLATIONPROCEDURE
givesinformationonhowtoobtainApacheandPerl.
Unix source
The source code is the same for Unix as for Windows. It has been
compiledandtestedonLinux,Solaris,andMacintoshOS/X;itshouldbe
afairlyroutinemattertoportittootherflavorsofUnix.
TocompiletheGreenstonesourcecodeonUnix,youneed
GCC,theGnuC++compiler.
GDBM,theGnudatabasemanager.
ToruntheGreenstonesoftware,youalsoneedaWebserverandPerl,as
describedaboveunderUnixbinaries.
Unix installation
ToinstalltheUnixversionfromtheCDROM,insertthediskintothe
drive,andtype
mount/cdrom

cd/cdrom
cdUnix
shInstall.sh

mounttheCDROMdevice(thiscommandmay
differfromonesystemtoanother;forexampleon
OS/Xyoucdtothe/Volumesdirectoryandthento
theappropriatesubdirectoryfortheCDROM)
changedirectorytotheCDROMstoplevel
changedirectorytowheretheUnixinstallscript
resides
begintheinstallationprocess(anexplicitshis
usedbecausemanyinstallationsforbidyouto
executeprogramsdirectlyfromCDROM)

The final command begins an interactive dialogue which requests the

informationthatisneededtoinstallGreenstoneonyoursystem,andgives
detailedfeedbackonwhatishappening.
Theinstallationprocedurebeginsbyaskingyouwhichdirectorytoinstall
Greenstoneinto.Thefirstfileplacedthereistheuninstallprogramthat
cleans up any partial installation, should you encounter problems or
terminatetheinstallationprematurely.Nextyouchoosewhetheryouwant
toinstall binaries orsource code. Youare then asked some questions
about yourwebserver setup. Youneed to have a valid cgi executable
directory (normally called cgibin on Unix systems); you can either
createanewoneoruseyourexistingone.Ifyoucreateanewone,you

INSTALLATIONPROCEDURE9
willneedtoenterthisinformationinyourwebserversconfigurationfile.
Ineithercaseyouneedtoenterthewebaddressofthecgidirectory.The
installation dialogue will guide you through all these choices. It is
importanttosetthefilepermissionscorrectlyoncertaindirectories,and
you are prompted for the necessary information. Finally, you are
promptedforapasswordfortheadministratoruseradmin.
By default, all Greenstone software is installed in the directory
/usr/local/gsdlifitistherootuserwhoisdoingtheinstallation,andinto
thedirectory~/gsdlotherwise(where~istheusershomedirectory).
Installingthebinariestakesjustafewminutes,enoughtimeforyouto
answer the appropriate questions. If you install the source code, the
installationscriptwillcompileit,whichtakesfromtenminutestoanhour
orso,dependingonthespeedofyourprocessor.
Touninstallthesoftware,type
cd~/gsdl

or/usr/local/gsdlifitwastherootuserwho
installedGreenstone

shUninstall.sh

Duringtheinstallationprocedureyouwillbeaskedwhetheryouwantto
install anyGreenstone collections.TheGreenstone Democollectionis
installedautomatically;othercollectionsontheCDROMaredescribed
inSection3.
Unix webserver configuration
Ifyoualready haveawebserver, somesmall changes willhavetobe
madetoitsconfigurationtomakeyourGreenstoneinstallationoperate.
Theinstallscriptexplainswhattheseare.Youwillprobablyneedhelp
fromyoursystemadministratortoreconfigurethewebserverheorshe
shouldbeabletounderstandtheinstructionsoutputbytheinstallscript.
Foryourconvenience,theoutputoftheinstallscriptiswrittentoafile
called INSTALL_RECORD in the directory into which you installed
Greenstone.
Ifyoudonotalreadyhaveawebserver,youwillhavetoinstallone.The
AppendixgivesinformationonApache.Thenyouwillhavetoconfigure
it appropriately. Section 4 givesa detailed account of the parts of an
ApachewebserverinstallationthataffectGreenstone,andhowtheyneed
tobealtered.Itcomesdowntoincludinghalfadozenorsolinesina
configurationfile.

10INSTALLATIONPROCEDURE
YoudonotneedtobetheUnixrootusertogothroughtheinstallation
procedure above. When it comes to configuring an existing Apache
server,however,youmayneedrootprivilegesitalldependsonhow
Apacheissetup.IfyouinstallApacheyourself,youcandoitasauser
without root privileges. If you need to work your way around an
uncooperative system administrator, you can always install a second
Apachewebserveronyourcomputerevenifoneexistsalready.

2.3 How to find Greenstone

Local library (Windows only)
IfyouareusingtheLocalLibrary,simplyrunthe Greenstone program
fromthe Start menu.Thisautomaticallyopensadialogboxthatstarts
your Internet browser and loads the Greenstone Digital Library home
page. TheGreenstone Democollection shouldbe accessible from this
page.ThedialogboxcontaisaFilemenuitemthatallowsyoutochange
thedefaultbrowserusedbyGreenstone. Itdoesntmatterwhetheryou
use Netscape or Internet Explorer, except that if you are running on
Windows2000,werecommendthatyouuseInternetExplorer.
Web library (Windows and Unix)
IfyouareusingtheWebLibrary,onceyouhaveinstalledthesoftware
andconfigured thewebserver, usethisURLtoenter yourGreenstone
system:
http://localhost/gsdl/cgibin/library
TheGreenstoneDemocollectionshouldbeaccessiblefromthispage.
The Collector
AlinktotheCollectorisprovidedonthedigitallibraryhomepage.
Administration
AlinktotheAdministrationpagesisprovidedonthedigitallibraryhome
page.Theadministratoruseriscalledadmin,withapasswordthatyou
specified during theinstallationprocess. Theadministratorisauthorized
toaddnewusers,andtobuildcollections.

INSTALLATIONPROCEDURE11

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'scollectionbuildingfunctionalityfromaneasytousepoint
andclickinterface.
GLIisinstalledautomaticallywithalldistributionsofGreenstone.Itis
placed in the subdirectory gli of the toplevel Greenstone directory
(C:\ProgramFiles\gsdl\gli bydefault). Notethatitrunsinconjunction
with Greenstone and will not work properly unless it is placed in a
subdirectoryofyourGreenstoneinstallation.Ifyouhavedownloadedone
oftheGreenstonedistributions,thiswillbethecase.
To use the GLI, your computer needs to have the Java Runtime
Environment.Ifitdoesnt,theinstallerwilloffertoinstallaversionthat
isincludedontheCDROM.OnUnix,youwillalsoneedtoensurethat
Perlisinstalled(forWindows,PerlisalreadyincludedintheGreenstone
software). Please report any problems you have running or using the
LibrarianInterfacetogreenstone@cs.waikato.ac.nz.
Running under Windows
TorunGLIunderWindows,browsetotheglifolderinyourGreenstone
installation(e.g.usingWindowsExplorer),anddoubleclickonthefile
called gli.bat. This file checks that Greenstone, the Java Runtime
Environment, and Perl are all installed, and starts the Greenstone
LibrarianInterface.
Running under Unix
TorunGLIunderUnix,changetothe gli directoryinyourGreenstone
installation,thenrunthegli.shscript.ThisscriptchecksthatGreenstone,
theJavaRuntimeEnvironment,andPerlare all installedandonyour
searchpath,andstartstheGreenstoneLibrarianInterface.
Getting help
TheGreenstoneLibrarianInterfacehasextensiveonlinehelpfacilities.
Yougethelpbyclickingthe Help buttonatthetoprightofthescreen.
Thisopensupthetexttoasectionthatrelatestowhatyouaredoing
whichoftheGLIpanelsyouareon.Youcanclickaroundthehelptextto
learnwhatyouneedtoknow.Useit.

12INSTALLATIONPROCEDURE

Compiling the Greenstone Librarian Interface

IfyouhavedownloadedtheGreenstonesourcedistribution,youwillhave
the Java source code of the Librarian Interface. To compile it, your
computerneedstohavea JavaDevelopmentKit.TheAppendixgives
informationonhowtoobtainthis.Tocompilethesourcecode,runthe
makegli.bat (Windows)or makegli.sh (Unix)files.Oncecompiled,you
canrunGLIasdescribedabove.

2.5 Testing and troubleshooting

TotestGreenstone,pointyourWebbrowserattheGreenstonehomepage
andexploretheDemocollectionandanyothercollectionsthatyouhave
installed. Dontworryyoucantbreakanything.Clickliberally:most
imagesthatappearonthescreenareclickable.Ifyouholdthemouse
stationaryoveranimage,mostbrowserswillsoonpopupamessagethat
tellsyouwhat willhappenifyouclick.Experiment! Choosecommon
words like the and and to search forthat should evoke some
responses, and nothing will break. For more information, see the
GreenstoneDigitalLibraryUsersGuide.
Troubleshooting

LOCAL LIBRARY
(WINDOWS ONLY)

Problem

Trythis

WhenIstartGreenstone
mycomputerasksmeto
dialupmyInternet
ServiceProvider.

PushtheCancelbuttoninthedialogbox.
Thisusuallysolvestheproblem.

WhenIstartGreenstone
mycomputerstillasks
metodialupmyInternet
ServiceProvider.

ChoosetheRestrictedversionwhenyou
runGreenstone.Thisversiononlyworks
withNetscape.

WhenIpointmy
browseratthedigital
library,itcantfindthat
page.

CheckyourInternetProxysettingsand
turnproxiesoff(useEditpreferenceson
NetscapeorInternetoptionsonExplorer).

INSTALLATIONPROCEDURE13
TheCollectorseemsto
beworkingveryslowly!

AreyouusingNetscapeunderWindows
2000?Ifso,tryusingInternetExplorer
insteadonWindows2000(only)there
seemstobesomeincompatibilitywith
Netscape.

14INSTALLATIONPROCEDURE

WEB LIBRARY
(WINDOWS AND
UNIX)

BOTH VERSIONS

Problem

Trythis

WhenIstartApache,it
quitsimmediately.

AddaServerNamelocalhostdirectiveto
theApacheconfigurationfile(seeSection
4.1).

WhenIpointmy
browseratthedigital
library,itdisplays
garbageabinaryfile.

ChecktheScriptAliasdirectiveinthe
Apacheconfigurationfile,makingsureit
comesbeforetheAliasdirective(see
Sections4.2and4.3).

IgettheGreenstone
homepage(Figure2),
buttheDemocollection
icondoesnotappear.

Runtheprogramlibrary(inthecgibin
directory)fromtheDOS(orshell)prompt
togeneratedebugginginformationthat
willhelpyoulocatetheproblem.

WhenIpointmy
browseratthedigital
library,itcantfindthat
page.

Tryusing127.0.0.1inplaceoflocalhost.
ThisreservedIPnumberisdefinedtobea
loopbacktoyourlocalcomputer.

Mybrowsercomplains
thatitcantfind
main.cfg.

CheckthattheGreenstonefilesexistand
areworldreadable.Ifyouareusingthe
Weblibrary,tryrunningthelibrary
programfromthecommandline.Ifitruns
OK,theproblemiswithfilepermissions
(seeSection5.1).Ifnot,thegsdlhome
variableisprobablysetincorrectlyinthe
gsdlsite.cfgconfigurationfile(seeSection
5.2).

Imhavingtroubleusing
theCollector.

ReadtheGreenstoneDigitalLibrary
UsersGuide,Section3.

Iveaddedanewuser
buttheycantseemto
login.

CheckthatthedirectoryC:\Program
Files\gsdl\etcandallitscontentsare
globallywriteable(seeSection5.1).

2.6 To learn more

TolearnmoreabouttheinnardsofyourGreenstoneinstallation,consult
the Greenstone Digital Library Developers Guide. It includes (for
example) details of the directory structure that has been created, and
informationabouthowtoconfigureyourGreenstonesite.

INSTALLATIONPROCEDURE15

greenstone.org

3
Greenstone Collections
Several demonstrationGreenstone collectionsare includedontheCD
ROM.IfyouhaveWebaccess,manyotherscanbedownloaded,ineither
prebuiltorunbuiltform,fromtheNewZealandDigitalLibraryProject
website(nzdl.org).
The Greenstone Demo collection is a small subset of the Humanity
Development Library (HDL), a polished collection. It illustrates that
relativelyrichbrowsingcapabilitiescanbeprovided(solongassuitable
metadataisavailable).Itis included automatically when the softwareis
installed.
Greenstonealsocomeswithsomewelldocumentedexamplecollections
whose about page describes how they are constructed. They
demonstratevariouscapabilitiesofGreenstone.Theinstalldialoguewill
ask you whether you want to include them in your Greenstone
installation; the approximate amount of disk space needed for each
collectionisshownbelow.
demo

GreenstoneDemo
(7Mb)

AsmallsubsetoftheHDL.Ifyouclonethis
collection,thefullfacilitieswillonlyappearif
yournewfilesprovideappropriatemetadata
information.

dlse

Development
LibrarySubset
collection
(150Mb)

LiketheGreenstoneDemo,thisisasubsetof
theHDLbutmuchlarger.Itcontains250
publicationsbooks,reportsandmagazinesin
variousareasofhumandevelopment(thefull
HDLcontains1,230publications).Ithasthe
samestructureastheGreenstoneDemo.It's
fairlycomplex,andifyou'rejuststartingout
youmightprefertolookatsomeother
collectionsfirst(e.g.MSWordandPDF
demonstration,theGreenstoneArchives,orthe

GREENSTONECOLLECTIONS17
Simpleimagecollection).
wrdpdfe

MSWordandPDF
demonstration
(4Mb)

ThiscontainsafewdocumentsinPDF,
MSWord,RTF,andPostscriptformats,
demonstratingtheabilitytobuildcollections
fromdocumentsindifferentformats.The
collectionconfigurationfileisverysimple.

gsarche

GreenstoneArchives
collection
(5Mb)

Acollectionofemailmessagesfromthe
Greenstonemailinglistarchives,thisusesthe
Emailplugin,whichparsesfilesinemail
formats.Thecollectionconfigurationfileisvery
simple.

cltbibe

Bibliography
collection
(7Mb)

Withabout4,000bibliographyentries,this
collectionincorporatesaformbasedsearch
interfacethatallowsfieldedsearching.Itis
fairlycomplex.

cltexte

Bibliography
supplement
(1Mb)

Thistinycollectionof10bibliographyentries
illustratesthe"supercollection"facilitywhich
searchesseveralcollectionstogether,
seamlessly.Itoperatestogetherwiththe
Bibliographycollection,anditsconfiguration
fileisalmostthesame.

MARCexample
(1Mb)

BasedonsomeMARCrecordsfromtheLibrary
ofCongress,thisisasimplecollection(and
doesnotallowformbasedsearching).

OAIdemocollection

UsingtheOpenArchiveProtocolandthe
ImportFromfeature,thisretrievesmetadata
fromanarchiveandbuildsacollectionfromthe
records.Inthiscasetheyareimages,soboththe
OAIandImagepluginsareused.

MARCe

oaie

(18Mb)

imagee

Simpleimage
collection
(1Mb)

Thisverybasicimagecollectioncontainsno
textandnoexplicitmetadatawhichmakesit
ratherunrealistic.Theconfigurationfileisabout
assimpleasyoucanget.

authene

Formattingand
authenticationdemo
(8Mb)

Withthesamematerialastheoriginal
Greenstonedemocollection,thisshowsofftwo
independentfeatures:nonstandarddocument
formatting,andcontrolledaccesstothe
documentsviauserauthentication.

18GREENSTONECOLLECTIONS
garish

isise

Garishversionof
democollection
(8Mb)

Thiscollectionalsocontainsthesamematerial
astheGreenstonedemo.Itsappearancehasbeen
alteredtoshowhowthepagesgeneratedcanbe
setoutdifferently.Itreliesonanonstandard
macrofilethatissuppliedwithGreenstone.

CDS/ISISexample
(1Mb)

ThiscollectionisbuiltfromaCDS/ISIS
databaseofabout150bibliographyentries.It
usestheISISPlugplugin,whichreadsthe
standardISIS.mstand.fdtfilesandconverts
themtoGreenstonemetadata.

greenstone.org

4
Setting up the Webserver
Inthissectionwedescribehowtosetupyourwebservertoworkwith
Greenstone.NotethatallthisisunnecessarywhenusingtheWindows
LocalLibrary,becausethissoftwareworksoutoftheboxanddoesnot
requireawebserver.
WediscussboththeApachewebserver,whichisfreelyavailableforboth
Windows and Unix (see the Appendix for details) and Microsofts
Personal Web Server (PWS) and Internet Information Services (IIS)
webserver.PWSisthestandardMicrosoftserverforWindows95/98;IIS
is the standard webserver for Windows 2000 and the forthcoming
Windows XP; Windows NT can use either. The Apache description
appliesequallytotheWindowsWebLibraryandUnixversions(though
weuseWindowsstyleterminologyandpathnames);thePWS/IISsection
appliesonlytotheWindowsWebLibrary.
Once you have installed your webserver, the next step is to install
Greenstone.Wewillassumethatduringtheinstallprocedure youhave
takenthedefaultactionforeachstagebyclickingontheNextbutton.The
resultisthatthedirectoryC:\ProgramFiles\gsdliscreatedandtheWeb
Librarybinaryisstoredthere,alongwithsomesupportingfiles.
AllwebserversusethespecialURLlocalhosttodenotethecomputer
thatthewebserverisrunningon.Thuswhenyouinstallawebserver,you
cangetatyourHTMLdocumentsbytypingtheURLhttp://localhostintoa
browser.Ifyourcomputerhasadomainnamesetup,thisisusedinstead
oflocalhost toidentifyyourcomputerfrom remotesites.Thusonthe
New Zealand Digital Librarys computer, http://nzdl.org and
http://localhost are equivalent. If you type http://nzdl.org on your
computer you will get the New Zealand Digital Library webserver,
whereasifyoutype http://localhost youwillgetyourowncomputers
webserver.

20SETTINGUPTHEWEBSERVER

4.1 The Apache web server

TheApachewebserverisusuallyinstalledin C:\ProgramFiles\Apache
Group\Apache andisconfiguredsothatthecgibindirectoryis inthe
subdirectory\cgibinandthedocumentrootisthesubdirectory\htdocs.It
is reconfigured by editing the configuration file C:\Program
Files\ApacheGroup\Apache\conf\httpd.conf.Thisisatextfile:itsquite
easytoreadittoseehowthingsaresetup.
Dependingonhowyourcomputersnetworkingsoftwareissetup,you
mayhavetoaddthislinetoApacheshttpd.confconfigurationfile:
ServerNamelocalhost

Ifthislineisnotincluded,thesystemattemptstofindyourserversname.
However,therearebugsinsomeversionsofWindowsthatcausethisto
fail.Inthiscase,Apachewillexitimmediatelywhenyoustartitup.It
does display an error message, but it is immediately erased and you
probablycantreadit.
Setting up the Greenstone cgi-bin directory
Cgibin is a directory from which the webserver treats documents as
executableprograms.Apaches ScriptAlias directiveisusedtocreatea
cgibindirectory.Notethatthisdirectivecanmakeanydirectoryacgi
executabledirectoryitdoesnthavetobecalledcgibin!Conversely,
a directory called cgibin isnt special unless ScriptAlias has been
appliedtoit.
When installed, Apache has a cgibin directory of C:\Program
Files\Apache Group\Apache\cgibin.Thismeansthat ifpresented with
the URL http://localhost/cgibin/hello, the webserver will attempt to
executeafilecalledhellofromwithintheabovedirectory.
There is one Greenstone program, which is called library.exe, that
needstobeexecutedbythewebserver;itinturnreadsafilecalledthe
Greenstonesiteconfigurationfile,orgsdlsite.cfg,whichneedstobe
locatedinthesamedirectory.
ThebestwayofarrangingthisistouseApachesScriptAliasdirectiveto
create a new cgibin directory. Heres the excerpt from Apaches
httpd.conf configurationfilethatadds C:\ProgramFiles\gsdl\cgibin as
anadditionalcgibindirectory:

SETTINGUPTHEWEBSERVER21
ScriptAlias/gsdl/cgibin/"C:/ProgramFiles/gsdl/cgibin/"
<DirectoryC:/ProgramFiles/gsdl/cgibin>
OptionsNone
AllowOverrideNone
</Directory>

(ItsacuriousfactthatApacheconfigurationfilesuseforwardslashesin
placeofstandardWindowsbackslashes.)
ThismeansthatanyURLsoftheformhttp://localhost/gsdl/cgibin...will
besoughtinthedirectoryC:\ProgramFiles\gsdl\cgibin,andexecutedby
the web server. For example, if presented with the URL
http://localhost/gsdl/cgibin/hello,thewebserverwillattempttoretrieve
thefileC:\ProgramFiles\gsdl\cgibin\helloandexecuteit.However,the
URL http://localhost/cgibin/hello looks in Apaches regular cgibin
directory for the file C:\Program Files\Apache Group\Apache\cgi
bin\helloandexecutesit,justasitdidbefore.
The document root directory
Thedocument rootdirectory istheroot ofyourwebservers directory
structure.Wheninstalled,Apachehasadocumentroot ofC:\Program
Files\ApacheGroup\Apache\htdocs.Thismeansthatifpresentedwiththe
URL http://localhost/hello.html,thewebserverwillattempttoretrievea
filecalledhello.htmlfromwithintheabovedirectory.
SeveralfileswithinGreenstoneneedtobereadbythewebserver.The
simplestwaytoarrangethisistousetheAliasdirective,whichisjustlike
ScriptAlias exceptthatitappliestoordinarywebpages,notcgiscripts.
InserttheselinesintoyourApacheconfigurationfile,aftertheScriptAlias
directive,toaddC:\ProgramFiles\gsdlasanadditionalplacetolookfor
documents.
Alias/gsdl/"C:/ProgramFiles/gsdl/"
<DirectoryC:/ProgramFiles/gsdl>
OptionsIndexesMultiViewsFollowSymLinks
AllowOverrideNone
Orderallow,deny
Allowfromall
</Directory>

ThismeansthatanyURLsthatmatchthefirstargumentofAlias(gsdl)
aresoughtasfilesintheplacecorrespondingtothesecondargument.In
otherwords,URLsoftheformhttp://localhost/gsdl/...willbesoughtas
filesinthedirectory C:\ProgramFiles\gsdl.Forexample,ifpresented
withtheURLhttp://localhost/gsdl/hello.html,thewebserverwillattempt

22SETTINGUPTHEWEBSERVER
toretrievethefile C:\ProgramFiles\gsdl\hello.html.However,theURL
http://localhost/hello.htmllooksintheregularhtdocsdirectoryforthefile
C:\ProgramFiles\ApacheGroup\Apache\htdocs\hello.html,justasitdid
before.
Be sure to add the Alias directive after the ScriptAlias directive.
InstructingApache toalias /gsdl before /gsdl/cgibin wouldmatchthe
URL /gsdl/cgibin/library against the Alias directive rather than the
ScriptAlias,anditwouldbeinterpretedasarequestforadocumentrather
than the result of executing a program. The outcome would be to
displaythebinaryprogramfileasapageintheWebbrowser,insteadof
executingit.
Security
YoushouldbeawarethatiftheweblibraryversionofGreenstoneisset
upasinstructedabove,anyonewillbeallowedtodownloadanyfileinthe
gsdl directory structure. This includes the index files and source
documentsofanycollectionsyoumake,theuserdatabase,usagelogs,
etc.
Ifyouareconcernedaboutthis,youcaneasilytightenupyourwebserver
configurationtoimprovesecurity.FortheApachewebserver,putthese
linesintotheconfiguration fileinstead ofthosegivenintheprevious
subsection:
Alias/gsdl/"C:/ProgramFiles/gsdl/"
<Directory"C:/ProgramFiles/gsdl">
Orderallow,deny
Denyfromall
<FilesMatch
"\.(gif|jpe?g|png|css|mov|mpeg|ps|pdf|doc|rtf|jar|class)$">
Orderallow,deny
Allowfromall
</FilesMatch>
</Directory>

Thismeansthatonlyfileswhoseextensionsmatchtheregularexpression
intheFilesMatchlinemaybedownloaded.

4.2 The PWS and IIS webservers

AlthoughneitherPWSnorIISisinstalledbydefaultoncurrentWindows
systems,they caneasilybeinstalledusingtheAdd/Removeprograms
controlpanel.IftheyarenotalreadyonyourWindowsdistributionCD
ROM you will have to download them from the Microsoft web site

SETTINGUPTHEWEBSERVER23
(www.microsoft.com).
ThesetupprocedureforGreenstoneisidenticalforbothPWSandIIS.
InvokethePersonalWebManagerandperformthefollowingactions.
1.

SelectAdvancedtogettheAdvancedOptionsscreen.

2.

SelectHomeandclickAdd.Filloutthefieldsasfollows:
Directoryfield:
Aliasfield:
Accesspermissions:
Applicationpermissions:
ClickOK

C:\ProgramFiles\gsdl
gsdl
Read
None

ThismakesGreenstonefilesaccessibletothewebserver.
3.

Backin AdvancedOptions,select gsdl and click Add.Filloutthe

fieldsasfollows:
Directoryfield:
Aliasfield:
Accesspermissions:
Applicationpermissions:
ClickOK

C:\ProgramFiles\gsdl\cgibin
cgibin
None
Execute

ThisallowstheGreenstone program library.exe tobeexecutedby

thewebserver.
4.

GototheURLhttp://localhost/gsdl/cgibin/library.exe.
Note:youneedtospecifythe.exefileextensionwithPWSandIIS.

24SETTINGUPTHEWEBSERVER

greenstone.org

5
Configuring your Site
For Greenstone to work properly, access permissions for certain files
mustbesetupappropriately.Also,thereisaconfigurationfileassociated
with each Greenstone site. The install procedure creates a generic
configurationfilebasedonyourinstallationchoices;howeveritscontents
canbetailoredtocopewithdifferent situations.Thissectionexplains
bothoftheseissues.

5.1 File permissions

ThissectionisirrelevantforWindows95/98,becausethesesystemsdont
identifytheownersoffiles.
OnWindowsNT,2000andUnixsystems,cgiscriptsdontrunasnormal
users,becauseuserscantbeidentifiedovertheWeb.Instead,theyrunas
theuserwhostartedupthewebserverprogram(onWindowssystems),or
asaspecialuser(commonlycallednobodyonUnixsystems).Becauseof
this, all files and directories within C:\Program Files\gsdl need to be
globally readable (or at least readable by the cgiscript user, perhaps
nobody).Totestwhetherfilepermissionsaresetupcorrectly,runthe
program library.exe fromthecommandline.Ifthefilesareintheright
places but the permissions are set incorrectly, it will run from the
commandlinethatis,when youexecuteitbutnotfromabrowser
thatis,whenthenobodyuserexecutesit.Anothertestistologinas
anotherusertoseeifthefilepermissionsarespecifictoyouroriginaluser
account.
ToworkthroughaWebbrowser,alltheGreenstonedirectoriesmustbe
globallyreadable.Also,the C:\ProgramFiles\gsdl\etc directoryandall
itscontentsmustbegloballywritable.Thisisthedirectoryintowhichthe
library program writestheusagelog,error andinitializationlogs,and
varioususerdatabases.Ifyourereluctanttomakethisdirectoryglobally
writable, you can set permissions so that just the files errout.txt,

26CONFIGURINGYOURSITE
initout.txt, key.db, users.db, history.db and usage.txt arewritablebythe
cgiuser.
IffilepermissionsarenotsetupcorrectlyforC:\ProgramFiles\gsdl\etc,
youmayfindthatuserauthenticationandsearchhistorydonotwork,and
thatnousagelog(usage.txt)isgenerated.

5.2 The gsdlsite.cfg configuration file

TheinstallprocedurecreatesagenericGreenstonesiteconfigurationfile
based on your installation choices. For our installation this file is
C:\ProgramFiles\gsdl\cgibin\gsdlsite.cfganditscontentis:
#SiteconfigurationfileforGreenstone.
#Linesbeginingwith
#arecomments.
#Thisfileshouldbeplacedinthesamedirectoryasyourlibrary
#executablefile.itshouldbeeditedtosuityoursite.
#pointstotheGSDLHOMEdirectory
gsdlhomeC:/ProgramFiles/gsdl
#thisisthehttpaddressofGSDLHOME
#ifyourwebserversDocumentRootissetto$GSDLHOME
#thenhttpprefixcanbecommentedout
httpprefix/gsdl
#thisisthehttpaddressofthedirectorywhich
#containstheimagesfortheinterface.
httpimg/gsdl/images
#shouldcontainthehttpaddressofthiscgiscript.This
#isnotneededifthehttpserversetstheenvironmentvariable
#SCRIPT_NAME
#gwcgi/cgibin/library
#maxrequestsisthemostrequestsafastcgiprocess
#willservebeforeitexits.Thiscanbesettoa
#lowfigure(like1)whiledebuggingandthenset
#toahighfigure(like10000)wheneverythingis
#workingwell.
#maxrequests10000

Youcancustomiseyourinstallationbyeditingthisfile,althoughyouwill
probablynotneedtodoso.
ThegsdlhomelinesimplypointstotheC:\ProgramFiles\gsdldirectory.
httpprefixisthewebaddressofthedirectorythatGreenstoneisinstalled
in.WeexplainedearlierhowtocreateanaliassothatURLsoftheform
http://localhost/gsdl/...aresoughtintheC:\ProgramFiles\gsdldirectory.
Putting a line httpprefix /gsdl into the gsdlsite configuration file

CONFIGURINGYOURSITE27
establishesthesameconventionfortheGreenstonesoftware.
httpimgisthewebaddressoftheC:\ProgramFiles\gsdl\imagesdirectory,
whichcontainsallthegifimagesusedintheinterface.Inanystandard
Greenstoneinstallationthiswillalwaysbehttpprefix/images,andtheline
inthefileaboveisleftuntouched.
gwcgiisthewebaddressofthelibrarycgiprogram.Thisisnotrequired
bymostwebservers(includingApache),andshouldremaincommented
out.Dontuncommentitunlessyouresureyouneedto,becausethatmay
introduceproblems.
maxrequests isonlyusedbyversionsofGreenstone thatarecompiled
withthefastcgioptionon.Thestandardbinarydistributiondoesnot
includethisoptionbecausenotallwebserversareconfiguredtosupport
it.Fastcgispeedsupcgiexecutionsbykeepingthemainexecutablein
memorybetweeninvocationsofthesoftware, ratherthanloadingitin
from disk each time a web page is requested from the Greenstone
software.Thetradeoffistheamountofmemoryused,whichcangrow
thelongertheprogramremainsinmemory.Oncemaxrequestspageshave
beengenerated,thecgiprogramquits,therebyfreeinganyaccumulated
memory.TorespondtothenextrequestforaWebpage,thecgiprogram
isreadinfromdiskagain,andanewcycleofpagerequestsisbegun.
Most installations use the standard cgi protocol, which means that
maxrequestscanbesafelyignored.

28CONFIGURINGYOURSITE

greenstone.org

6
Personalizing your
Installation
Probably the first thing you will want to do once your Greenstone
installationisupandrunningispersonalizethehomepage.Thefilethat
generatestheGreenstonehomepageiscalledhome.dm,andislocatedin
the macros subdirectory of the directory into which you installed
Greenstone.(ThedefaultforWindowssystemsisC:\ProgramFiles\gsdl.)
Thisisaplaintextfilethatyouwillhavetoedittocreateanewhome
page. Instead of editing it, we recommend creating a new file, say
yourhome.dm. This will be like home.dm but will define package
homewhichisthebitthatdoestheactualworkinadifferentway.
When you make a different home page, there must be some way of
linkingintothedigitallibrarypagessothatyoucansearchandbrowse
thecollectionsonyoursystem.ThesolutionthatGreenstoneadoptsisto
usemacros. Thatswhythehomepagefileiscalled .dmandnot
.htmlitsamacrofileratherthanaregular HTML file.Butdont
quail:themacrofilebasicallycontainsjust HTML,sprinkledwithafew
mysticalincantantationswhichareexplainedbelow.Themacrolanguage
isapowerfulfacility,andonlyasmallpartofitisdescribedbelowsee
theGreenstoneDigitalLibraryDevelopersGuideformoreinformation.

6.1 Example
Figure3showsanexampleofanewdigitallibraryhomepage.Eachof
theClickherelinkstakesyoutotheappropriateGreenstonefacility.
Thispagewasgeneratedbythefilecalledyourhome.dmshowninFigure
4.
You can useFigure4asatemplateforcreatingyourownspecialized
Greenstone home page. Basically, it defines a macro called content.

30PERSONALIZINGYOURINSTALLATION
InsidethecurlybracesisordinaryHTML.Youcouldinsertadditionaltext,
alongwithanyHTMLformattingcommands,toputthecontentthatyou
wanttoseeonthepage.Thetextisregular HTML; ifyouwant youcan
includehyperlinksandusealltheotherfacilitiesthatHTMLprovides.

PERSONALIZINGYOURINSTALLATION31
Figure3
YourownGreenstone
homepage

Figure4
yourhome.dmusedto
createFigure3

packagehome
_content_{
<h2>YourownGreenstonehomepage</h2>
<ul>
<table>
<trvalign=top><td>Searchpageforthedemocollection<br></td>
<td><ahref="_httpquery_&c=demo">Clickhere</a></td></tr>
<tr><td>"About"pageforthedemocollection</td>
<td><ahref="_httppageabout_&c=demo">Clickhere</a></td></tr>
<tr><td>Preferencespageforthedemocollection</td>
<td><ahref="_httppagepref_&c=demo">Clickhere</a></td></tr>
<tr><td>Homepage</td>
<td><ahref="_httppagehome_">Clickhere</a></td></tr>
<tr><td>Helppage</td>
<td><ahref="_httppagehelp_">Clickhere</a></td></tr>
<tr><td>Administrationpage</td>
<td><ahref="_httppagestatus_">Clickhere</a></td></tr>
<tr><td>TheCollector</td>
<td><ahref="_httppagecollector_">Clickhere</a></td></tr>
</table>
</ul>
}
#ifyouhatethesquirlygreenbardownthelefthandsideofthe
#page,uncommenttheselines:
#_header_{
#}

Tomakeyournewhomepagelinkinwithotherdigitallibrarypages,you

32PERSONALIZINGYOURINSTALLATION
needto use an appropriatemagicspell.Inthismacrolanguage,magic
spellsarewordsflankedbyunderscores.YoucanseetheseinFigure4.
For example, _httppagehome_ takes you to the home page,
_httppagehelp_ tothehelppage,andsoon.Insomecasesyouneedto
includeacollectionname.Forexample, _httpquery_&c=demo specifies
thesearchpageforthedemocollection;forothercollectionsyoushould
replacedemobytheappropriatecollectionname.
Thedefinitionofthemacrocalled_content_isplainHTML.Anystandard
HTMLcodemaybeplacedwithinamacrodefinition.However,thespecial
characters {, }, \, and _ must be escaped with a backslash to
preventthemfrombeingprocessedbythemacrolanguageinterpreter.
Note that the _content_ macro definition does not contain any HTML
headerorfooter.Ifyouwanttochangetheheaderorfooterofyourhome
page,youshoulddefine_header_and/or_footer_macros,addingthemto
theyourhome.dmfileintheform
_macroname_{
...
}

Forexample,thesquirlygreenbardownthelefthandsideofGreenstone
pagesisdefinedinthe_header_macro,andmakingthismacronullwill
removeit,asindicatedattheendofFigure4.

6.2 How to make it work

YouhavetotellGreenstoneaboutthenewhomepageyourhome.dm.The
system reads in the macro files that are specified in the main
configurationfilemain.cfg,soifyoucreateanewoneyoumustincludeit
there.Nameclashesarehandledsensibly:themostrecentdefinitiontakes
precedence.
ThustomaketheGreenstonedigitallibrarysoftwareusethehomepage
inFigure3insteadofthedefault,firstputtheyourhome.dmfileinFigure
4intothe macrosdirectory.Theneditthe main.cfg configurationfileto
replace home.dm with yourhome.dm inthelist ofmacro filesthat are
loadedatstartup.

6.3 Redirecting a URL to Greenstone

YoumaywanttoredirectamoreconvenientURLtoyourGreenstonecgi
program.Forexample,onoursystemtheURL http://nzdl.org (whichis

PERSONALIZINGYOURINSTALLATION33
shorthand for http://nzdl.org/index.html) is redirected to
http://nzdl.org/cgibin/library.TheApachewebserveraccomplishesthis
withtheRedirectdirective.Alongwithotherdirectives,thisgoesintothe
C:\Program Files\Apache Group\Apache\conf\httpd.conf configuration
file. To redirect the URL http://www.yourserver.com to
http://www.yourserver.com/cgibin/library,putthislineintohttpd.conf:
Redirect/index.htmlhttp://www.yourserver.com/cgibin/library

ThenyouwillreachyourdigitallibrarysystemdirectlyfromtheURL
http://www.yourserver.com. Instead, if you wanted a URL like
http://www.yourserver.com/greenstone
to be redirected to
http://www.yourserver.com/cgibin/library,includeinthehttpd.conffile
Redirect/greenstonehttp://www.yourserver.com/cgibin/library

If your computer doesnt have a domain name (like the

www.yourserver.com above), just replace www.yourserver.com by
localhost inthelinesabove.Solongasthebrowserisrunningonthe
same machine as the webserverwhich it surely is if your computer
doesnt have a domain namethis has the same effect as the above
redirections.
Instead of putting redirect directives into the file httpd.conf, you can
equallywell put themintoafilecalled .htaccess withinyourservers
document root directory. In fact, doing so has two advantages. First,
changesto.htaccesstakeeffectimmediately,whereasyouhavetorestart
theApachewebservertoseetheeffectofchangestohttpd.conf.Second,
onUnixsystems youusuallyhavetobeloggedinastherootuserto
edithttpd.conf,whereasyoudonttoedit.htaccess.

greenstone.org

Appendix
Associated Software
Hereishowtoobtainthesoftwarepackagesmentionedabove.

A.1 Apache Webserver

TorunanyversionofGreenstoneapartfromtheWindowsLocalLibrary
version,youneedanexternalwebserver.Manyinstallations,particularly
larger ones, will already have a webserver. If you are using Linux,
Apachemaybeonyourinstallationdiskbutmaynothavebeenselected
during the installation procedure. The Apache Webserver from
www.apache.orgisfree,andeasytoinstall.

A.2 Perl
Greenstone uses the Perl language when building collections. For
Windows, Perl is already included in the Greenstone software. Most
Unix systems already have Perl installed, but if not, source code and
binaries for a wide range of Unix platforms are freely available at
www.perl.com.Perlversion5.0orhigherisneeded.

A.3 GCC
TheUnixversionofGreenstonecompilesundertheGnuC++compiler,
GCC. Greenstone makes extensive use of the C++ standard template
library (weve foundittobebrokenonsomeolderversionsofGCC;
please tell us if you have STL problems). Note that this version of
GreenstonedoesnotcompileunderGCC3.0.

A.4 GDBM
AllversionsofGreenstoneusetheGnuDatabaseManager,GDBM.Itis
supplied with all Windows versions of Greenstone and installed

PERSONALIZINGYOURINSTALLATION35
automatically during the installation procedure. Linux systems already
haveGDBM,sowedonotprovideitforLinux.MostotherUnixsystems
haveit,butifnecessaryyoucandownloaditfromwww.gnu.org.

A.5 Java runtime environment

TousetheGreenstoneLibrarianInterface,youneedasuitableversionof
theJavaRuntimeEnvironment.Ifyoudontalreadyhavethis,asuitable
version is included on the CDROM, or you can download the latest
version from http://java.sun.com/j2se/downloads.html. Version 1.4.0 or
higherisneeded.

A.6 Java compiler

TocompilethesourcecodeoftheGreenstoneLibrarianInterface,you
mustfirstinstallaJavaDevelopmentKit.YoucandownloadtheJ2SE
SoftwareDevelopmentKitfromhttp://java.sun.com/j2se/downloads.html.
Version1.4.0orhigherisneeded.