root/main/branches/64_bit_Greenstone/greenstone3/README.txt @ 24007

Revision 24007, 13.7 KB (checked in by sjm84, 8 years ago)

Updating this branch to match the latest Greenstone3 changes

  • Property svn:keywords set to Author Date Id Revision
Line 
1Greenstone 3 (GSDL3)
2Copyright (C) 2003 New Zealand Digital Libraries, University Of Waikato
3Greenstone3 comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt
4This is free software, and you are welcome to redistribute it
5
6Installing Greenstone
7---------------------------------------------------------
8
9Download the appropriate installer from sourceforge.net/projects/greenstone3 and run it.
10
11See 'Installing from a Source Distribution' section below for extra notes about installing from Source.
12
13See the README-SVN.txt file for extra notes about installing directly from SVN.
14
15Greenstone 3 requires Java and Ant to run. These will be installed during a
16Greenstone binary installation.
17
18Running Greenstone:
19---------------------------------------------------------
20
21To start up Greenstone, select Greenstone3 Digital Library from the Start menu
22(Windows), or run gs3-server.sh/bat. This launches a small server program
23which starts up Tomcat and launches a browser. A small window pops up which
24allows you to change some settings for your library and restart the Tomcat
25server. Closing this program will stop Tomcat running.
26
27Alternatively, you can start Tomcat directly through using Ant. 'ant start',
28'ant restart' and 'ant stop' starts, restarts and shuts down Tomcat,
29respectively. This will only start/stop a local server (one installed by
30Greenstone). You will need to manually start/stop an external Tomcat
31(see below for notes about using a version of Tomcat external to Greenstone).
32
33You will need to run 'gs3-setup' (Windows) or 'source gs3-setup.sh' (Linux/Mac)
34before running ant targets.
35
36Once the Tomcat server is running, Greenstone will be available in a browser
37at "http://localhost:8080/greenstone3" (or whatever port you specified
38during the installation process).
39You can change the port number using File->Settings in the server program, or
40by changing the 'tomcat.port' property in build.properties, then running
41'ant configure'.
42
43Building Collections:
44----------------------------------------------------------
45
46You need to have Perl installed and on your PATH. Perl is included as part of
47the Windows binary distribution.
48
49You can build collections using the Greenstone Librarian Interface (GLI).
50To start GLI, select it from the Start Menu (Windows), run 'ant gli' from the
51greenstone3 directory, or cd to greenstone3/gli and run gli.sh/bat.
52
53Once you have created and built a collection, you can see it by clicking 'Preview collection' on the Build panel.
54
55Java/Tomcat Notes
56--------------------------------------------------------
57
58Binary releases of Greenstone are compiled with Java 1.5 and come with JRE 1.5 and Tomcat 6. Tomcat 6 does not work with Java 1.4.
59
60To recompile the source from a binary release:
61* Download the source code component and unpack into Greenstone3 directory.
62* You will need to install a JDK, 1.5 or later.
63* Rename the packages/jre folder to something else (eg jre.old)
64* Set JAVA_HOME environment to be the root of your Java installation.
65* run 'ant install'
66
67If you wish to use Java 1.4:
68* Do all the above steps but before running ant install,
69* delete packages/tomcat/.flagfile and run 'ant prepare-tomcat' to get Tomcat 5.
70
71Greenstone 3 from SVN will download Tomcat 5 if you are using Java 1.4, otherwise will download Tomcat 6.
72
73Greenstone Admin
74------------------------------------------------------
75
76The Greenstone admin tool is currently under development.
77
78Using SOAP:
79-------------------------------------------------------
80
81Greenstone comes with Apache Axis installed as part of the Greenstone web
82application. However, no SOAP services are deployed by default.
83
84To deploy a SOAP server for localsite, run 'ant deploy-localsite'. You should
85now be able to see all localsite's collections through the gateway servlet.
86(http://localhost:8080/greenstone3/gateway)
87
88To set up a SOAP server on a new site, run
89ant soap-deploy-site
90This will prompt you for the sitename (the directory name), and the site uri
91- this should be a unique identifier for the site's web service.
92
93For a non-interactive version, run
94ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site
95
96The service is accessible at
97http://localhost:8080/greenstone3/services/<siteuri>
98
99(or http://<computer-web-address>:<port>/greenstone3/services/<siteuri>)
100
101Note: Deploying a SOAP service for any site other than localsite requires
102the Greenstone source code to be installed. This is not installed by default
103for a binary distribution. To get the source code, re-run the installer,
104select custom install and deselect everything except the source code.
105
106Using External Tomcat:
107---------------------------------------------------
108
109If you want to use an existing Tomcat, set the path to its base directory
110in build.properties (tomcat.installed.path). Also set the tomcat.port
111property to be the port you are running Tomcat on, and change tomcat.server
112if the web address is not localhost. Then run 'ant configure'.
113
114 You will need to modify the Tomcat setup slightly.
115
1161. Tell Tomcat about the Greenstone web app. There are two ways to do this.
117
118A. Copy the file greenstone3/resources/tomcat/greenstone3.xml into Tomcat's
119conf/Catalina/localhost directory. You'll need to edit the file and
120replace @gsdl3webhome@ with the full path to the web directory of your
121greenstone 3 installation. Any path separator is fine here ('/', '\\', '\').
122
123B. Alternatively, you can move (and rename) the greenstone3/web directory to
124tomcat/webapps/greenstone3 (i.e. the resulting directories will be like
125tomcat/webapps/greenstone3/WEB-INF, no web directory). This should be done
126after running the initial 'ant install'.
127
128You will need to set the web.home property in the build.properties file
129i.e.
130web.home=${tomcat.installed.path}/webapps/greenstone3
131And then run 'ant configure' to reset gsdl3home.
132
1332. Set up the JNI libraries and Java wrappers.
134JNI libraries and their Java wrappers cannot go into the web app. The
135libraries need to be loaded by the same class loader as their wrappers. The
136libraries need to be in java.library.path, and I think get loaded by the
137system class loader.
138The wrappers need to be loaded by this too.
139
140These JNI bits are located by default in the lib/jni directory. There are
141two ways to get them into Tomcat:
142A: Keep all the Greenstone stuff inside the greenstone3 directory, and just
143modify the environment that Tomcat runs in
144
145Set LD_LIBRARY_PATH (GNU/Linux), DYLD_LIBRARY_PATH (Mac OS X) or PATH/Path
146(windows) to include the  greenstone3/lib/jni directory.
147Add all the jar files in greenstone3/lib/jni directory to the CLASSPATH,
148then edit tomcats setclasspath.sh/bat to use the system CLASSPATH.
149(in setclasspath.bat, change
150set CLASSPATH=%JAVA_HOME%\lib\tools.jar
151to
152set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CLASSPATH%
153
154in setclasspath.sh, change
155# Set standard CLASSPATH
156if [ "$1" = "debug" -o "$1" = "javac" ] ; then
157  CLASSPATH="$JAVA_HOME"/lib/tools.jar
158fi
159
160to
161# Set standard CLASSPATH
162if [ "$1" = "debug" -o "$1" = "javac" ] ; then
163  CLASSPATH="$JAVA_HOME"/lib/tools.jar:"$CLASSPATH"
164fi
165
166
167B: Copy the files into Tomcat installation:
168Move the greenstone3/lib/jni jar files into tomcat's shared/lib directory.
169Move the greenstone3/lib/jni library files (.so for GNU/Linux, .jnilib for
170Mac OS X .dll for Windows) into shared/classes, and set LD_LIBARARY_PATH
171(GNU/Linux), DYLD_LIBRARY_PATH (Mac OS X) or PATH/Path (Windows) to include
172this directory.
173 This has the advantage that you can use this for other webapps without
174modifying the Tomcat environment.
175
176Once all these changes have been made, you will need to restart the Tomcat
177server for them to take effect.
178
179
180Notes for Mac OS
181------------------------------------------------
182
183Set JAVA_HOME to be /Library/Java/Home
184
185Notes for Windows
186-----------------------------------------------
187
188You can set environment variables by going to
189Control Panel->System->Advanced->Environment Variables.
190
191Installing from a Source Distribution
192----------------------------------------------
193
194Download the greenstone-3.xx-src.tar.gz package from
195sourceforge.net/projects/greenstone3, and unpack it.
196
197In the greenstone3 directory, edit the build.properties file and run
198ant install
199
200Tomcat will be installed as part of the prepare process. To stop this set the
201tomcat.installed.path to be the root of an existing Tomcat installation.
202
203* Solaris notes:
204** Make sure /usr/local/bin is in your PATH ahead of /usr/bin etc.
205** Add /usr/local/lib to LD_LIBARY_PATH
206** 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:
207in greenstone3/gs2build directory: run 'source setup.bash' (Or if you have greenstone 2 already installed, run 'source setup.bash' in your greenstone 2 installation)
208in greenstone3/web/sites/localsite/collect/gs2mgdemo/index/text directories, run 'txt2db gs2mgdemo.bdb < database.txt'
209in greenstone3/web/sites/localsite/collect/gs2mgppdemo/index/text directories, run 'txt2db gs2mgppdemo.bdb < database.txt'
210** 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).
211** Set CC=gcc environment variable if you don't have cc, before running ant install.
212
213* Windows notes:
214** You need to have Visual Studio installed to compile the C/C++ code. Set the path to the setup file in build.properties (compile.windows.c++.setup).
215
216Configuring your installation:
217--------------------------------------------------------
218
219The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
220Note, either forward slash '/' or double backslash '\\' can be used as path separators in the build.properties file, but not single backslash '\'.
221
222Greenstone 3 comes with Tomcat bundled in. 
223
224If 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.
225
226Mac 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.
227
228The install target will ask you if you accept the properties before starting.
229To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
230ant -Dproperties.accepted=yes install
231
232To log the output in build.log, run
233ant -Dproperties.accepted=yes -logfile build.log  install
234
235Recompiling
236-------------------------------------------------------
237To recompile your Greenstone3 installation, in the top level greenstone3 directory, run:
238
239ant clean (use distclean instead if you want to regenerate the C++ Makefiles)
240ant configure
241ant configure-c++
242ant compile
243
244The compile target does Java and C/C++ compilation. On Windows, you need to set the compile.windows.c++.setup property to be your Visual Studio setup batch file.
245
246Any 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.
247
248
249Notes on Versions of Third Party packages
250-----------------------------------------------
251
252Tomcat:
253
254apache-tomcat-5.5.12.zip: latest production quality release as of October, 2005.
255apache-tomcat-5.5.12-compat.zip: Tomcat 5 requires Java 1.5. If using Java 1.4, need to use this compatibility module.
256
257website: http://tomcat.apache.org/
258download: http://tomcat.apache.org/download-55.cgi
259
260Axis:
261
262Apache Web Services Project, SOAP implementation. Axis is a follow on project to Apache SOAP
263
264axis-bin-1_2_1.zip: latest stable release as of October, 2005
265website: http://ws.apache.org/axis/
266download: http://www.apache.org/dyn/closer.cgi/ws/axis/1_2_1
267
268All available from www.greenstone.org/gs3files if not available at their respective websites.
269
270Other Notes:
271-------------------------------------------------
272
273See greenstone3/docs/manual/manual.pdf for more details about the software and installation etc.
274
275Output is logged to web/logs. usage.log is a usage log, while greenstone.log is the error/message log. To change the level of logging, edit the web/WEB-INF/classes/log4j.properties file, and change the log4j.disable and log4j.rootCategory properties. Valid values are TRACE, DEBUG, INFO, WARN, ERROR and FATAL.
276
277To prevent Tomcat showing directory listings, edit Tomcat's conf/web.xml file and set the value of the "listings" servlet parameter to false.
278
279To 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.
280(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.)
281
282The file web/WEB-INF/classes/global.properties is generated on install and contains some properties for the run time system.
283
Note: See TracBrowser for help on using the browser.