source: trunk/gsdl3/README.txt@ 10671

Last change on this file since 10671 was 10671, checked in by kjdon, 18 years ago

changed notes about loading the sample database for external mysql

  • Property svn:keywords set to Author Date Id Revision
File size: 13.0 KB
Line 
1Greenstone 3 (GSDL3)
2Copyright (C) 2003 New Zealand Digital Libraries, University Of Waikato
3GSDL3 comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt
4This is free software, and you are welcome to redistribute it
5
6Installing Greenstone from a binary distribution (Linux):
7---------------------------------------------------------
8
9Download the gsdl3-x.xx-linux executable file, and run it. Follow the instructions given.
10
11Installing Greenstone from a binary distribution (Windows):
12-----------------------------------------------------------
13
14Download the gsdl3-x.xx-win32.exe executable file, and double click on it.
15Follow the instructions given.
16
17
18Installing Greenstone from a CVS checkout (Linux and Windows):
19--------------------------------------------------------------
20
21Checkout the code:
22
23cvs -d :pserver:[email protected]:2402/usr/local/global-cvs/gsdl-src co gsdl3
24
25Build and install:
26
27Greenstone is built and installed using Ant (Apache's Java based build tool,
28http://ant.apache.org). You will need a Java Development
29Environment (1.4 or higher, we recommend Sun Java), and Ant installed to use Greenstone. You can download Ant from http://ant.apache.org/bindownload.cgi.
30
31Set the environment variable JAVA_HOME to be the root of your Java installation.
32Set the environment variable ANT_HOME to be the root of you Ant installation.
33Make sure the cvs and ant executables are on your Path.
34
35In the gsdl3 directory, you can run 'ant' which will give you a help message.
36Running 'ant -projecthelp' gives a list of the targets that you can run - these
37do various things like compile the source code, startup the server etc.
38
39For a first time install, run 'ant prepare install'.
40
41The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
42
43Greenstone uses the Tomcat servlet container. If you already have Tomcat running, you can set the tomcat.installed.path property to the base directory of your Tomcat installation, and Greenstone will not download its own Tomcat.
44It is intended that the same thing will be available for mysql, but this has not been implemented yet.
45
46Greenstone 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. If you do not want to use Greenstone 2 style collection building at all, set the gsdl2.installed.path to any non-empty string.
47
48 The prepare target will ask you if you accept the properties before starting.
49To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
50ant -Dproperties.accepted=yes prepare install
51
52To log the output in build.log, run
53ant -Dproperties.accepted=yes -logfile build.log prepare install
54
55The prepare target will download additional code, so you need to be online to run it. install can be run offline.
56
57Under 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.)
58
59Common install/update targets.
60-------------------------------
611. Install for the first time:
62cvs co gsdl3
63cd gsdl3
64ant prepare install
65
662. Install for the first time, offline:
67[online]
68cvs co gsdl3
69cd gsdl3
70ant prepare
71[offline]
72ant install
73
743. Install for the first time, cvs done outside of Ant (if you have problems running cvs commands from Ant):
75cvs co [-P] gsdl3
76cd gsdl3
77cvs update -P (run this if you haven't done the checkout with the -P option)
78cd packages
79cvs co mgpp
80cd ..
81[if you want greenstone 2 building:
82cvs co -P gli
83cvs co -P gs2build
84]
85[if you are on windows
86cvs co winbin
87]
88ant -Dnocvs.mode=yes prepare install (prepare needs to be online, install can be done offline)
89
904. Updating your Greenstone installation from cvs (and reconfigure/recompile):
91cd gsdl3
92ant update
93
945. Updating your Greenstone installation, offline:
95cd gsdl3
96[online]
97ant cvsupdate
98[offline]
99ant -Dnocvs.mode=yes update
100
1016. Updating your Greenstone installation, cvs outside of Ant:
102cd gsdl3
103cvs update -l
104cvs update -dP bin comms docs lib resources src winutil packages
105cd web (or the path-to-tomcat/webapps/gsdl3 if have installed greenstone as a webapp in Tomcat, see Using External Tomcat section)
106cvs update -dP
107cd gsdl3
108[ if you have greenstone 2 building:
109cvs update -dP gli
110cvs checkout -P gs2build
111Note that the gs2build one uses checkout not update.
112]
113ant -Dnocvs.mode=yes update
114
115The main targets for installation/update are:
116configure, configure-c++, clean, compile.
117Any 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.
118
119If 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 localhost:8080/gsdl3/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.
120
121Running Greenstone:
122-------------------
123
124To startup the local 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.
125These will only start/stop local servers (ones installed by Greenstone). You will need to manually start/stop external Tomcat/mysql.
126
127On Windows, if you have installed a binary version, you can also start Greenstone by selecting Greenstone 3 Digital Library from the Start menu.
128
129Greenstone will be available in a browser at "http://localhost:8080/gsdl3".
130
131You can change the port number by changing the tomcat.port property in build.properties, then running 'ant configure'.
132
133
134Using SOAP (Linux and Windows):
135-------------------------------
136
137Greenstone 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.
138
139To set up a SOAP server on a new site, run
140ant soap-deploy-site
141This 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.
142
143For a non-interactive version, run
144ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site
145
146Building Collections:
147-----------------------
148
149You can build collections using either Greenstone 2 style building, or native Greenstone 3 style.
150
151Greenstone 2:
152
153You need to have Perl installed and on your PATH.
154run 'ant gli", or cd to gsdl3/gli and run gli4gs3.sh/bat. This is a graphical tool for building collections.
155
156Greenstone 3:
157
158In the gsdl3 directory, run: 'source gs3-setup.sh' (linux) or 'gs3-setup' (windows).
159To create a new collection, run 'gs3-mkcol.sh/bat <sitename> <collname>'
160Put documents in the import directory (gsdl3/web/sites/<sitename>/collect/<collname>/import), edit the collection configuration file (gsdl3/web/sites/<sitename>/collect/<collname>/etc/collectionConfig.xml), and run 'gs3-build.sh <sitename> <collname>'
161Rename the building directory to index (in gsdl3/web/sites/<sitename>/collect/<collname>) and reload the collection in Tomcat (?a=s&sa=a&st=collection&sn=<collname>), or restart Tomcat.
162
163See the manual for more details about both styles of collection building.
164
165Other Notes:
166---------------
167
168See gsdl3/docs/manual/manual.pdf for more details about the software and installation etc.
169
170Under Linux, Tomcat logs output in gsdl3/comms/jakarta/tomcat/logs/catalina.out.
171
172To 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.
173
174ant can't seem to do cvs using authenticated cvs on windows:
175there were some classes missing - www.ibiblio.org/maven/jsch/jars/jsch-0.1.17.jar
176many ssh processes seemed to be started up - all waiting in the background for password??
177So should only use anonymous cvs.
178
179Using External Tomcat:
180------------------------
181
182If you want to use an existing Tomcat, set the path to its base directory
183in build.properties (tomcat.installed.path) (on windows need to use double backslashes in paths '\\'). Then run 'ant prepare install'. If you have already done an install (e.g. using a local Tomcat), you don't need to do it again.
184
185 You will need to modify the Tomcat setup slightly.
186
1871. Tell Tomcat about the Greenstone web app. There are two ways to do this.
188
189A. Add in the Greenstone context to Tomcat's server.xml (In the Host name="localhost".. element)
190
191<Context path="/gsdl3" docBase="path-to-gsdl3/web" debug="1"
192reloadable="true"><Resources allowLinking='true'/></Context>
193
194B. Alternatively, you can move (and rename) the gsdl3/web directory to tomcat/webapps/gsdl3 (i.e. the resulting directories will be like
195tomcat/webapps/gsdl3/WEB-INF, no web directory). This should be done after running the initial 'ant prepare install'.
196You will need to set the web.home property in the build.properties file
197i.e.
198web.home=${tomcat.installed.path}/webapps/gsdl3
199And then run 'ant configure-web' to reset gsdl3home.
200
2012. Set up the JNI libraries and Java wrappers.
202JNI 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.
203The wrappers need to be loaded by this too.
204To 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).
205
206These JNI bits are located by default in the lib/jni directory. There are two ways to get them into Tomcat:
207A: Keep all the Greenstone stuff inside the gsdl3 directory, and just modify the environment that Tomcat runs in
208
209Set LD_LIBRARY_PATH (linux) or PATH (windows) to include the gsdl3/lib/jni directory.
210Add all the jar files in gsdl3/lib/jni directory to the CLASSPATH, then edit tomcats setclasspath.sh/bat to use the system CLASSPATH.
211(in setclasspath.bat, change
212set CLASSPATH=%JAVA_HOME%\lib\tools.jar
213to
214set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CLASSPATH%
215
216in setclasspath.sh, change
217# Set standard CLASSPATH
218if [ "$1" = "debug" -o "$1" = "javac" ] ; then
219 CLASSPATH="$JAVA_HOME"/lib/tools.jar
220fi
221
222to
223# Set standard CLASSPATH
224if [ "$1" = "debug" -o "$1" = "javac" ] ; then
225 CLASSPATH="$JAVA_HOME"/lib/tools.jar:"$CLASSPATH"
226fi
227
228
229B: Copy the files into Tomcat installation:
230Move the gsdl3/lib/jni jar files into tomcat's shared/lib directory.
231Move the gsdl3/lib/jni library files (.so for linux, .dll for windows) into shared/classes, and set LD_LIBARARY_PATH (linux) or PATH (windows) to include this directory.
232This has the advantage that you can use this for other webapps without modifying the Tomcat environment.
233
234Once all these changes have been made, you will need to restart the Tomcat server for them to take effect.
235
236Using External mysql server
237------------------------------
238
239Set the mysql.installed.path property in build.xml to be non-empty (its not actually used) before installation.
240
241You will need to add the two greenstone users: gsdl3reader and gsdl3admin. The reader user is only used for accessing the database, the admin user can be used for modification.
242
243Run mysql as the root user.
244
245Commands to add the two users:
246GRANT SELECT,INSERT,DELETE,UPDATE,DROP,CREATE ON *.* TO gsdl3admin@localhost identified by 'admin-password';
247GRANT SELECT ON *.* TO gsdl3reader@localhost identified by 'reader-password';
248
249You will need to edit the gsdl3/web/WEB-INF/classes/global.properties file and set the two passwords that you used in here:
250mysql.admin.password and mysql.reader.password
251The mysql.tcp.port property specified here should be set to the port that your mysql is running on. (default 3306).
252
253You should also load up the database for the gs3mgdemo collection:
254create database localsite_gs3mgdemo;
255
256Close mysql, then run
257mysql localsite_gs3mgdemo < <path-to-gsdl3>/web/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql
258
259(Note that if you have installed the Greenstone web directory into Tomcats webapps dir, then this command will be
260mysql localsite_gs3mgdemo < <path-to-tomcat>/webapps/gsdl3/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql )
261
262You may need to run this using '--user=root -p'
263
264Notes for Mac OS
265------------------
266
267Set JAVA_HOME to be /Library/Java/Home
Note: See TracBrowser for help on using the repository browser.