Greenstone 3 (GSDL3) Copyright (C) 2003 New Zealand Digital Libraries, University Of Waikato GSDL3 comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt This is free software, and you are welcome to redistribute it Installing Greenstone from a binary distribution (Linux): --------------------------------------------------------- Download the gsdl3-x.xx-linux executable file, and run it. Follow the instructions given. Installing Greenstone from a binary distribution (Windows): ----------------------------------------------------------- Download the gsdl3-x.xx-win32.exe executable file, and double click on it. Follow the instructions given. Installing Greenstone from a CVS checkout (Linux and Windows): -------------------------------------------------------------- Checkout the code: cvs -d :pserver:cvs_anon@cvs.scms.waikato.ac.nz:2402/usr/local/global-cvs/gsdl-src co gsdl3 Build and install: Greenstone is built and installed using Ant (Apache's Java based build tool, http://ant.apache.org). You will need a Java Development Environment (1.4 or higher), and Ant installed to use Greenstone. You can download Ant from http://ant.apache.org/bindownload.cgi. Set the environment variable JAVA_HOME to be the root of your Java installation. We recommend Sun's Java. In the gsdl3 directory, you can run 'ant' which will give you a help message. Running 'ant -projecthelp' gives a list of the targets that you can run - these do various things like compile the source code, startup the server etc. For a first time install, run 'ant install'. The file build.properties contains various parameters that can be set by the user. Please check these settings before running 'ant install'. Greenstone 3 uses some parts of Greenstone 2 for collection building using the Librarian Interface. It downloads the relevant parts during install. If you have Greenstone 2 already installed, please set the gsdl2.installed.path property to be the root of your Greenstone 2 installation. Greenstone 3 will then use this installation rather than downloading the extra Greenstone 2 bits. The install process will ask you if you accept the properties before starting. For a non-interactive version of the install, run ant -Dproperties.accepted=yes install To log the output in build.log, run ant -Dproperties.accepted=yes -logfile build.log install Under Linux, Java and C/C++ compilation is carried out. For windows, since Visual Studio is not a standard component, only Java compilation is carried out. Pre-compiled binaries are provided for the C/C++ components (packages and Greenstone 2 style building). If you have Visual Studio installed (version 6), you can run the compile-windows-c++ targets to compile the code locally. (Don't forget to setup the Visual Studio environment first, by running, e.g. C:/Program Files/Microsoft Visual Studio/VC98/Bin/VCVARS32.BAT or equivalent.) Running Greenstone: ------------------- To startup the servers, run 'ant start'. 'ant restart' and 'ant stop' restarts and shuts down the servers. To start or stop just Tomcat or MYSQL, use the start-tomcat, start-mysql, stop-tomcat, stop-mysql targets. On Windows, if you have installed a binary version, you can also start Greenstone by selecting Greenstone 3 Digital Library from the Start menu. Greenstone will be available in a browser at "http://localhost:8080/gsdl3". Using SOAP (Linux and Windows): ------------------------------- Greenstone comes with Apache Axis installed as a webapp in Tomcat. A SOAP server on localsite is deployed during installation. You should be able to see all localsite's collections through the gateway servlet. To set up a SOAP server on a new site, run ant soap-deploy-site This will prompt you for the sitename (the directory name), and the site uri - this should be a unique identifier for the site's web service. For a non-interactive version, run ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site Building Collections: ----------------------- You can build collections using either Greenstone 2 style building, or native Greenstone 3 style. Greenstone 2: You need to have Perl installed and on your PATH. run 'ant gli", or cd to gsdl3/gli and run gli4gs3.sh/bat. This is a graphical tool for building collections. Greenstone 3: In the gsdl3 directory, run: 'source gs3-setup.sh' (linux) or 'gs3-setup' (windows). To create a new collection, run 'gs3-mkcol.sh/bat ' Put documents in the import directory (gsdl3/web/sites//collect//import), edit the collection configuration file (gsdl3/web/sites//collect//etc/collectionConfig.xml), and run 'gs3-build.sh ' Rename the building directory to index (in gsdl3/web/sites//collect/) and reload the collection in Tomcat (?a=s&sa=a&st=collection&sn=), or restart Tomcat. See the manual for more details about both styles of collection building. Other Notes: --------------- See gsdl3/docs/manual/manual.pdf for more details about the software and installation etc. Under Linux, Tomcat logs output in gsdl3/comms/jakarta/tomcat/logs/catalina.out. To prevent Tomcat showing directory listings, edit the gsdl3/comms/jakarta/tomcat/conf/web.xml file and set the value of the "listings" servlet parameter to false. ant can't seem to do cvs using authenticated cvs on windows: there were some classes missing - www.ibiblio.org/maven/jsch/jars/jsch-0.1.17.jar many ssh processes seemed to be started up - all waiting in the background for password?? So should only use anonymous cvs. Using External Tomcat: ------------------------ If you want to use an existing Tomcat, set the path to its base directory in build.properties. You will need to modify the Tomcat setup slightly. 1. Add in the Greenstone context to Tomcat's server.xml. Alternatively, you can rename the gsdl3/web directory to gsdl3 and move it into Tomcat's webapps directory. (i.e. the resulting directories will be like webapps/gsdl3/WEB-INF, no web directory). TODO: check that this works. You will need to set the web.home property in the build.properties file eg web.home=path-to-tomcat/webapps/gsdl3 2. Set up the JNI libraries and Java wrappers. JNI libraries and their Java wrappers cannot go into the web app. The libraries need to be loaded by the same class loader as their wrappers. The libraries need to be in java.library.path, and I think get loaded by the system class loader. The wrappers need to be loaded by this too. To get the native libraries loaded, the directory they are in needs to be in the PATH variable (Windows) or the LD_LIBRARY_PATH variable (linux). These JNI bits are located by default in the lib/jni directory. There are two ways to get them into Tomcat: A: Keep all the Greenstone stuff inside the gsdl3 directory, and just modify the environment that Tomcat runs in set LD_LIBRARY_PATH/PATH to include gsdl3/lib/jni directory. add all the jar files in gsdl3/lib/jni directory to the CLASSPATH, then edit tomcats setclasspath.sh/bat to use the system CLASSPATH. (in setclasspath.bat, change set CLASSPATH=%JAVA_HOME%\lib\tools.jar to set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CLASSPATH% in setclasspath.sh, change # Set standard CLASSPATH if [ "$1" = "debug" -o "$1" = "javac" ] ; then CLASSPATH="$JAVA_HOME"/lib/tools.jar fi to # Set standard CLASSPATH if [ "$1" = "debug" -o "$1" = "javac" ] ; then CLASSPATH="$JAVA_HOME"/lib/tools.jar:"CLASSPATH" fi B: Copy the files into Tomcat installation: Move the gsdl3/lib/jni jar files into tomcat's shared/lib directory. Move the gsdl3/lib/jni library files (.so/.dll) into shared/classes, and set LD_LIBARARY_PATH/PATH to include this directory. This has the advantage that you can use this for other webapps without modifying the Tomcat environment.