| 1 | Greenstone 3 (GSDL3)
|
|---|
| 2 | Copyright (C) 2003 New Zealand Digital Libraries, University Of Waikato
|
|---|
| 3 | Greenstone3 comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt
|
|---|
| 4 | This is free software, and you are welcome to redistribute it
|
|---|
| 5 |
|
|---|
| 6 | You will need Java and Ant to run Greenstone 3.
|
|---|
| 7 |
|
|---|
| 8 | Your Java version should be 1.4 or higher. We recommend Sun Java. You need the SDK (development environment). Set the environment variable JAVA_HOME to be the root of your Java installation.
|
|---|
| 9 |
|
|---|
| 10 | Ant (Apache's Java based build tool) can be downloaded from http://ant.apache.org/bindownload.cgi. Set the environment variable ANT_HOME to be the root of your Ant installation, and make sure the Ant executables are on your PATH. You may have problems with earlier versions. This has been tested with version 1.6.2
|
|---|
| 11 |
|
|---|
| 12 | In the greenstone3 directory, you can run 'ant' which will give you a help message.
|
|---|
| 13 | Running 'ant -projecthelp' gives a list of the targets that you can run - these
|
|---|
| 14 | do various things like compile the source code, start up the server etc.
|
|---|
| 15 |
|
|---|
| 16 | On GNU/Linux MySQL seems to have trouble with spaces in paths, so it's best to install Greenstone into a path with no spaces.
|
|---|
| 17 |
|
|---|
| 18 | Installing Greenstone
|
|---|
| 19 | ---------------------------------------------------------
|
|---|
| 20 |
|
|---|
| 21 | Download the appropriate zip/tar file (greenstone-3.xx-linux.tar.gz/greenstone-3.xx-win32.zip/greenstone-3.xx-macOSX.tar.gz) from sourceforge.net/projects/greenstone3, and unzip/untar it. In the greenstone3 directory, edit the build.properties file (see 'Configuring your installation' below), and run 'ant install'.
|
|---|
| 22 |
|
|---|
| 23 | See 'Using External Tomcat' and 'Using External MySQL' sections below if you want to use an existing version.
|
|---|
| 24 |
|
|---|
| 25 | See 'Installing from a Source Distribution' section below for extra notes about installing from Source.
|
|---|
| 26 |
|
|---|
| 27 | See the README-CVS.txt file for extra notes about installing from CVS.
|
|---|
| 28 |
|
|---|
| 29 | Configuring your installation:
|
|---|
| 30 | --------------------------------------------------------
|
|---|
| 31 |
|
|---|
| 32 | The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
|
|---|
| 33 | Note, either forward slash '/' or double backslash '\\' can be used as path separators in the build.properties file, but not single backslash '\'.
|
|---|
| 34 |
|
|---|
| 35 | Greenstone 3 comes with MySQL and Tomcat bundled in.
|
|---|
| 36 |
|
|---|
| 37 | If you already have Tomcat running, you can set the 'tomcat.installed.path' property (in build.properties) to the base directory of your Tomcat installation, and Greenstone will not use its own Tomcat. (You can delete the packages/tomcat directory if you like.) Please read the section "Using External Tomcat" for details about how to configure Tomcat for Greenstone.
|
|---|
| 38 |
|
|---|
| 39 | Greenstone 3 uses MySQL for the collection database (with Greenstone 3 native building). If you already have MySQL installed, set the 'mysql.installed.path' property (in build.properties) to the base directory of your MySQL installation, and Greenstone will not use its local MySQL. (You can delete the packages/mysql directory if you like.) Please read the section "Using external MySQL server" for details about how to configure MySQL for Greenstone.
|
|---|
| 40 |
|
|---|
| 41 | If you are using MySQL that comes with greenstone 3, and you are installing greenstone 3 on an NFS drive, MySQL may not work properly (it has problems removing locks on its data files). After installation, copy the data directory from greenstone3/packages/mysql to a local drive, then set the path to this directory in the mysql.datadir property in build.properties.
|
|---|
| 42 | If the version of MySQL that greenstone is using is not suitable for your setup (see notes on versions below), please install an appropriate version and set the mysql.installed.path property.
|
|---|
| 43 |
|
|---|
| 44 | Mac OS X: You need to have GDBM installed (http://www.gnu.org/software/gdbm/gdbm.html). Please set the gdbm.installed.path property (in build.properties) to the root of your gdbm installation if it is not installed in a default place. If you run GLI or GS2 collection building from the command line, you will need to set the DYLD_LIBRARY_PATH environment variable to include <path-to-gdbm>/lib.
|
|---|
| 45 |
|
|---|
| 46 | The install target will ask you if you accept the properties before starting.
|
|---|
| 47 | To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
|
|---|
| 48 | ant -Dproperties.accepted=yes install
|
|---|
| 49 |
|
|---|
| 50 | To log the output in build.log, run
|
|---|
| 51 | ant -Dproperties.accepted=yes -logfile build.log install
|
|---|
| 52 |
|
|---|
| 53 | Running Greenstone:
|
|---|
| 54 | ---------------------------------------------------------
|
|---|
| 55 |
|
|---|
| 56 | To startup the local servers (Tomcat adn/or MySQL), run 'ant start'.
|
|---|
| 57 | 'ant restart' and 'ant stop' restarts and shuts down the servers.
|
|---|
| 58 | To start or stop just Tomcat or MySQL, use the start-tomcat, start-mysql, stop-tomcat, stop-mysql targets.
|
|---|
| 59 | These will only start/stop local servers (ones installed by Greenstone). You will need to manually start/stop external Tomcat/MySQL. if you are using both external Tomcat and external MySQL, then the start, restart, stop targets do nothing.
|
|---|
| 60 |
|
|---|
| 61 | Once the Tomcat server is running, Greenstone will be available in a browser at "http://localhost:8080/greenstone3".
|
|---|
| 62 | You can change the port number by changing the 'tomcat.port' property in build.properties, then running 'ant configure'.
|
|---|
| 63 |
|
|---|
| 64 | MySQL is only needed if you want to use the GS3MGDemo collection, or if you want to build collections using Greenstone3 native collection building.
|
|---|
| 65 |
|
|---|
| 66 |
|
|---|
| 67 | Building Collections:
|
|---|
| 68 | ----------------------------------------------------------
|
|---|
| 69 |
|
|---|
| 70 | You can build collections using either Greenstone 2 style building, or native Greenstone 3 style.
|
|---|
| 71 |
|
|---|
| 72 | Greenstone 2 style:
|
|---|
| 73 |
|
|---|
| 74 | You need to have Perl installed and on your PATH. Perl is included as part of the Windows binary distribution.
|
|---|
| 75 | run 'ant gli", or cd to greenstone3/gli and run gli4gs3.sh/bat. This is a graphical tool for building collections. Once you have created and built a collection, you can see it by clicking 'Preview collection' on the Build panel.
|
|---|
| 76 |
|
|---|
| 77 | Note that GLI doesn't start up the Greenstone server (Tomcat/MySQL) so you should run 'ant start' before previewing your collection.
|
|---|
| 78 |
|
|---|
| 79 | Greenstone 3 style:
|
|---|
| 80 |
|
|---|
| 81 | In the greenstone3 directory, run: 'source gs3-setup.sh' (GNU/Linux, Mac OS X) or 'gs3-setup' (Windows).
|
|---|
| 82 | To create a new collection, run 'gs3-mkcol.sh/bat <sitename> <collname>'
|
|---|
| 83 | Put documents in the import directory (greenstone3/web/sites/<sitename>/collect/<collname>/import), edit the collection configuration file (greenstone3/web/sites/<sitename>/collect/<collname>/etc/collectionConfig.xml), and run 'gs3-build.sh <sitename> <collname>'
|
|---|
| 84 | Rename the building directory to index (in greenstone3/web/sites/<sitename>/collect/<collname>) and reload the collection in Tomcat (?a=s&sa=a&st=collection&sn=<collname>), or restart Tomcat.
|
|---|
| 85 |
|
|---|
| 86 | See the manual for more details about both styles of collection building.
|
|---|
| 87 |
|
|---|
| 88 | Recompiling
|
|---|
| 89 | -------------------------------------------------------
|
|---|
| 90 | To recompile your Greenstone3 installation, in the top level greenstone3 directory, run:
|
|---|
| 91 |
|
|---|
| 92 | ant configure
|
|---|
| 93 | ant configure-c++
|
|---|
| 94 | ant clean
|
|---|
| 95 | ant compile
|
|---|
| 96 |
|
|---|
| 97 | The compile target, under GNU/Linux and Mac OS X, does Java and C/C++ compilation. 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 (src/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.)
|
|---|
| 98 |
|
|---|
| 99 | Any sub targets can be run by themselves. Run 'ant -projecthelp' for a list of public targets, otherwise you can look at the build.xml file to see which targets depend on other ones.
|
|---|
| 100 |
|
|---|
| 101 | If you run your install using an external Tomcat, the SOAP web service for localsite (used by the gateway servlet) will not be loaded. You need to start up Tomcat, then run 'ant soap-deploy-site' and accept the defaults for sitename and siteuri (both localsite). If you want to use the gateway servlet without restarting Tomcat, you will need to reload the site information. Visit the URL http://localhost:8080/greenstone3/gateway?a=s&sa=c (substituting your server name and port number if necessary). See the user guide for more information about run time reconfiguration.
|
|---|
| 102 |
|
|---|
| 103 |
|
|---|
| 104 | Using SOAP:
|
|---|
| 105 | -------------------------------------------------------
|
|---|
| 106 |
|
|---|
| 107 | Greenstone comes with Apache Axis installed as part of the Greenstone web application. A SOAP server on localsite is deployed during installation. You should be able to see all localsite's collections through the gateway servlet. (http://localhost:8080/greenstone3/gateway)
|
|---|
| 108 |
|
|---|
| 109 | To set up a SOAP server on a new site, run
|
|---|
| 110 | ant soap-deploy-site
|
|---|
| 111 | 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.
|
|---|
| 112 |
|
|---|
| 113 | For a non-interactive version, run
|
|---|
| 114 | ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site
|
|---|
| 115 |
|
|---|
| 116 | The service is accessible at http://localhost:8080/greenstone3/services/<siteuri>
|
|---|
| 117 | (or http://<computer-web-address>:<port>/greenstone3/services/<siteuri>)
|
|---|
| 118 |
|
|---|
| 119 |
|
|---|
| 120 | Using External Tomcat:
|
|---|
| 121 | ---------------------------------------------------
|
|---|
| 122 |
|
|---|
| 123 | If you want to use an existing Tomcat, set the path to its base directory
|
|---|
| 124 | in build.properties (tomcat.installed.path)
|
|---|
| 125 |
|
|---|
| 126 | You will need to modify the Tomcat setup slightly.
|
|---|
| 127 |
|
|---|
| 128 | 1. Tell Tomcat about the Greenstone web app. There are two ways to do this.
|
|---|
| 129 |
|
|---|
| 130 | A. Copy the file greenstone3/resources/tomcat/greenstone3.xml into Tomcat's conf/Catalina/localhost directory. You'll need to edit the file and replace @gsdl3webdir@ with the full path to the web directory of your greenstone 3 installation. Any path separator is fine here ('/', '\\', '\').
|
|---|
| 131 |
|
|---|
| 132 | B. Alternatively, you can move (and rename) the greenstone3/web directory to tomcat/webapps/greenstone3 (i.e. the resulting directories will be like
|
|---|
| 133 | tomcat/webapps/greenstone3/WEB-INF, no web directory). This should be done after running the initial 'ant install'.
|
|---|
| 134 |
|
|---|
| 135 | You will need to set the web.home property in the build.properties file
|
|---|
| 136 | i.e.
|
|---|
| 137 | web.home=${tomcat.installed.path}/webapps/greenstone3
|
|---|
| 138 | And then run 'ant configure-web' to reset gsdl3home.
|
|---|
| 139 |
|
|---|
| 140 | 2. Set up the JNI libraries and Java wrappers.
|
|---|
| 141 | 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.
|
|---|
| 142 | The wrappers need to be loaded by this too.
|
|---|
| 143 |
|
|---|
| 144 | These JNI bits are located by default in the lib/jni directory. There are two ways to get them into Tomcat:
|
|---|
| 145 | A: Keep all the Greenstone stuff inside the greenstone3 directory, and just modify the environment that Tomcat runs in
|
|---|
| 146 |
|
|---|
| 147 | Set LD_LIBRARY_PATH (GNU/Linux), DYLD_LIBRARY_PATH (Mac OS X) or PATH/Path (windows) to include the greenstone3/lib/jni directory.
|
|---|
| 148 | Add all the jar files in greenstone3/lib/jni directory to the CLASSPATH, then edit tomcats setclasspath.sh/bat to use the system CLASSPATH.
|
|---|
| 149 | (in setclasspath.bat, change
|
|---|
| 150 | set CLASSPATH=%JAVA_HOME%\lib\tools.jar
|
|---|
| 151 | to
|
|---|
| 152 | set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CLASSPATH%
|
|---|
| 153 |
|
|---|
| 154 | in setclasspath.sh, change
|
|---|
| 155 | # Set standard CLASSPATH
|
|---|
| 156 | if [ "$1" = "debug" -o "$1" = "javac" ] ; then
|
|---|
| 157 | CLASSPATH="$JAVA_HOME"/lib/tools.jar
|
|---|
| 158 | fi
|
|---|
| 159 |
|
|---|
| 160 | to
|
|---|
| 161 | # Set standard CLASSPATH
|
|---|
| 162 | if [ "$1" = "debug" -o "$1" = "javac" ] ; then
|
|---|
| 163 | CLASSPATH="$JAVA_HOME"/lib/tools.jar:"$CLASSPATH"
|
|---|
| 164 | fi
|
|---|
| 165 |
|
|---|
| 166 |
|
|---|
| 167 | B: Copy the files into Tomcat installation:
|
|---|
| 168 | Move the greenstone3/lib/jni jar files into tomcat's shared/lib directory.
|
|---|
| 169 | Move the greenstone3/lib/jni library files (.so for GNU/Linux, .jnilib for Mac OS X .dll for Windows) into shared/classes, and set LD_LIBARARY_PATH (GNU/Linux), DYLD_LIBRARY_PATH (Mac OS X) or PATH/Path (Windows) to include this directory.
|
|---|
| 170 | This has the advantage that you can use this for other webapps without modifying the Tomcat environment.
|
|---|
| 171 |
|
|---|
| 172 | Once all these changes have been made, you will need to restart the Tomcat server for them to take effect.
|
|---|
| 173 |
|
|---|
| 174 | Using External MySQL
|
|---|
| 175 | -------------------------------------------------------------
|
|---|
| 176 |
|
|---|
| 177 | Set the mysql.installed.path property in build.xml to be the path to your installation of mysql, before running the Greenstone install process. (This path is not actually used other than to check that its non-empty).
|
|---|
| 178 |
|
|---|
| 179 | You will need to add the two greenstone users: gsdl3reader and gsdl3admin to your mysql server. The reader user is only used for accessing the database, the admin user can be used for modification. You may also specify passwords for these two users.
|
|---|
| 180 |
|
|---|
| 181 | Run MySQL as the root user (or a user with account creation privileges).
|
|---|
| 182 |
|
|---|
| 183 | Commands to add the two users:
|
|---|
| 184 | GRANT SELECT,INSERT,DELETE,UPDATE,DROP,CREATE ON *.* TO gsdl3admin@localhost identified by 'admin-password';
|
|---|
| 185 | GRANT SELECT ON *.* TO gsdl3reader@localhost identified by 'reader-password';
|
|---|
| 186 |
|
|---|
| 187 | The "identified by 'xxx-password'" bits can be left out if you don't want to set any passwords. This will mean that anyone can log in to mysql using these usernames.
|
|---|
| 188 |
|
|---|
| 189 | You will need to edit the global.properties file and set the two passwords that you used:
|
|---|
| 190 | mysql.admin.password and mysql.reader.password
|
|---|
| 191 | Set these to be empty if you haven't used any passwords.
|
|---|
| 192 | The mysql.tcp.port property specified here should be set to the port that your MySQL is running on. (default 3306), and the mysql.server property should be set to the server address.
|
|---|
| 193 |
|
|---|
| 194 | This file is in greenstone3/resources/java/global.properties.in before greenstone3 installation, and greenstone3/web/WEB-INF/classes/global.properties after installation.
|
|---|
| 195 |
|
|---|
| 196 | You should also load up the database for the gs3mgdemo collection:
|
|---|
| 197 | create database localsite_gs3mgdemo;
|
|---|
| 198 |
|
|---|
| 199 | Close MySQL, then run
|
|---|
| 200 | mysql localsite_gs3mgdemo < <path-to-greenstone3>/web/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql
|
|---|
| 201 |
|
|---|
| 202 | (Note that if you have installed the Greenstone web directory into Tomcats webapps dir, then this command will be
|
|---|
| 203 | mysql localsite_gs3mgdemo < <path-to-tomcat>/webapps/greenstone3/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql )
|
|---|
| 204 |
|
|---|
| 205 | You may need to run this using '--user=root -p'
|
|---|
| 206 |
|
|---|
| 207 | Notes for Mac OS
|
|---|
| 208 | ------------------------------------------------
|
|---|
| 209 |
|
|---|
| 210 | Set JAVA_HOME to be /Library/Java/Home
|
|---|
| 211 |
|
|---|
| 212 | Notes for Windows
|
|---|
| 213 | -----------------------------------------------
|
|---|
| 214 |
|
|---|
| 215 | You can set environment variables by going to Control Panel->System->Advanced->Environment Variables.
|
|---|
| 216 |
|
|---|
| 217 | Installing from a Source Distribution
|
|---|
| 218 | ----------------------------------------------
|
|---|
| 219 |
|
|---|
| 220 | Download the greenstone-3.xx-src.tar.gz package from sourceforge.net/projects/greenstone3, and unpack it.
|
|---|
| 221 | In the greenstone3 directory, edit the build.properties file and run
|
|---|
| 222 | ant prepare install
|
|---|
| 223 |
|
|---|
| 224 | Tomcat and MySQL will be downloaded as part of the prepare process. To stop this set the tomcat.installed.path and/or mysql.installed.path to be the root of existing Tomcat/MySQL installations.
|
|---|
| 225 | The Tomcat distribution is cross platform, but MySQL is not - only Windows, GNU/Linux and Mac OS X versions will be used (see below). If you require a different version of MySQL, then you will need to install it yourself.
|
|---|
| 226 |
|
|---|
| 227 | * Solaris notes:
|
|---|
| 228 | ** Make sure /usr/local/bin is in your PATH ahead of /usr/bin etc.
|
|---|
| 229 | ** Add /usr/local/lib to LD_LIBARY_PATH
|
|---|
| 230 | ** The gdbm database files (gs2mgdemo and gs2mgppdemo collections) were generated on a Mac, and don't seem to be compatible with Solaris. A text version of the file (database.txt) is included in the index/text directory. After installing Greenstone, and before running it, you'll need to:
|
|---|
| 231 | in greenstone3/gs2build directory: run 'source setup.bash' (Or if you have greenstone 2 already installed, run 'source setup.bash' in your greenstone 2 installation)
|
|---|
| 232 | in greenstone3/web/sites/localsite/collect/gs2mgdemo/index/text directories, run 'txt2db gs2mgdemo.bdb < database.txt'
|
|---|
| 233 | in greenstone3/web/sites/localsite/collect/gs2mgppdemo/index/text directories, run 'txt2db gs2mgppdemo.bdb < database.txt'
|
|---|
| 234 | ** GLI shell scripts may not work like "./gli4gs3.sh". In this case, run "bash ./gli4gs3.sh" etc. You will need to compile GLI by hand (run "bash ./makegli.sh" in greenstone3/gli directory).
|
|---|
| 235 | ** Set CC=gcc environment variable if you don't have cc, before running ant install.
|
|---|
| 236 |
|
|---|
| 237 | * Windows notes:
|
|---|
| 238 | ** The main install target doesn't do C++ compiling on Windows. You'll need Visual Studio 6, and run the compile-windows-c++ target, i.e.
|
|---|
| 239 | ant prepare install compile-windows-c++
|
|---|
| 240 | 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.
|
|---|
| 241 |
|
|---|
| 242 | Notes on Versions of Third Party packages
|
|---|
| 243 | -----------------------------------------------
|
|---|
| 244 |
|
|---|
| 245 | Tomcat:
|
|---|
| 246 |
|
|---|
| 247 | apache-tomcat-5.5.12.zip: latest production quality release as of October, 2005.
|
|---|
| 248 | apache-tomcat-5.5.12-compat.zip: Tomcat 5 requires Java 1.5. If using Java 1.4, need to use this compatibility module.
|
|---|
| 249 |
|
|---|
| 250 | website: http://tomcat.apache.org/
|
|---|
| 251 | download: http://tomcat.apache.org/download-55.cgi
|
|---|
| 252 |
|
|---|
| 253 | MySQL:
|
|---|
| 254 |
|
|---|
| 255 | Relational database. Binary versions. latest version 4 stable release as at October 2005.
|
|---|
| 256 | mysql-noinstall-4.1.15-win32.zip (Windows, without installer)
|
|---|
| 257 | mysql-standard-4.1.15-apple-darwin7.9.0-powerpc.tar.gz (Mac OS X v10.3, without installer)
|
|---|
| 258 | mysql-standard-4.1.15-pc-linux-gnu-i686.tar.gz (GNU/Linux, x86, glibc-2.2, static (Standard only), gcc)
|
|---|
| 259 |
|
|---|
| 260 | http://dev.mysql.com
|
|---|
| 261 |
|
|---|
| 262 | Axis:
|
|---|
| 263 |
|
|---|
| 264 | Apache Web Services Project, SOAP implementation. Axis is a follow on project to Apache SOAP
|
|---|
| 265 |
|
|---|
| 266 | axis-bin-1_2_1.zip: latest stable release as of October, 2005
|
|---|
| 267 | website: http://ws.apache.org/axis/
|
|---|
| 268 | download: http://www.apache.org/dyn/closer.cgi/ws/axis/1_2_1
|
|---|
| 269 |
|
|---|
| 270 | All available from www.greenstone.org/gs3files if not available at their respective websites.
|
|---|
| 271 |
|
|---|
| 272 | Other Notes:
|
|---|
| 273 | -------------------------------------------------
|
|---|
| 274 |
|
|---|
| 275 | See greenstone3/docs/manual/manual.pdf for more details about the software and installation etc.
|
|---|
| 276 |
|
|---|
| 277 | Under GNU/Linux and Mac OS X, Tomcat logs output to logs/catalina.out in the Tomcat directory (greenstone3/packages/tomcat)
|
|---|
| 278 |
|
|---|
| 279 | To prevent Tomcat showing directory listings, edit Tomcat's conf/web.xml file and set the value of the "listings" servlet parameter to false.
|
|---|
| 280 |
|
|---|
| 281 | To enable symlinks to files outside the webapp root directory, edit Tomcat's conf/Catalina/localhost/greenstone3.xml file, and set the allowLinking attribute in the Context element to true.
|
|---|
| 282 | (Note from Tomcat website: This flag MUST NOT be set to true on the Windows platform (or any other OS which does not have a case sensitive filesystem), as it will disable case sensitivity checks, allowing JSP source code disclosure, among other security problems.)
|
|---|
| 283 |
|
|---|
| 284 | The file web/WEB-INF/classes/global.properties is generated on install and contains some properties for the run time system.
|
|---|
| 285 |
|
|---|
