source: gs3-extensions/fedora/trunk/src/README@ 26434

Last change on this file since 26434 was 26434, checked in by ak19, 8 years ago

While getting GS3-with-Fedora collections to work on Puka discovered more issues. 1. Several additional files needed to become template files with placeholder values for the GS3 tomcat server and port, fedora password and index write lock timeout value. Other files needed further modifications (particularly fedora.fcfg.in and gsearch's fgsconfig-basic.properties) to make sure server and port values weren't fixed to localhost and 8383 defaults. 2. The build.xml had to be updated to make changes to these new and modified files during the installation process. 3. There's now a new target in build.xml: uninstall-fedora. 4. README file update with all this information, as well as corrections and clarifications.

File size: 28.5 KB
Line 
1********************************************************************************************************************
2 CONTENTS
3********************************************************************************************************************
4
5A. To install your GS3 Fedora extension from fedora3-gs3ext.tar.gz
6 Uninstalling Fedora
7
8B. How to manually build fedora collections
9 Deleting a Fedora GS3 collection
10
11C. The customisations that have been made for the extension
12
13D. How to manually set up Fedora 3.6.1 with Fedora GSearch 2.5 from scratch
14 Installing Fedora
15 Installing Fedora GSearch
16 Debugging
17
18
19Version:
20Greenstone 3.05
21Fedora 3.6.1
22Fedora GSearch 2.5
23
24Web services pages once installed (by default GS3 is set to use localhost:8383):
25http://localhost:8383/fedora/services
26http://localhost:8383/fedoragsearch/services
27
28-- ak19, 2012
29
30
31
32********************************************************************************************************************
33 A. To install your Fedora extension for Greenstone 3 from the fedora3-gs3ext.tar.gz distribution file
34********************************************************************************************************************
35
36(Tested to work on Linux machines.)
37
380. You will need Greenstone 3.05 or a fresh checkout from SVN, already installed.
39You need a fresh x-term, one where the GS3 environment hasn't already been set up in.
40
411. Download the Fedora Extension for Greenstone 3: http://trac.greenstone.org/browser/gs3-extensions/fedora/trunk/fedora3-gs3ext.tar.gz
42
432. Save into your Greenstone3/ext folder
44
453. Untar and decompress it:
46 $ tar -xvzf fedora3-gs3ext.tar.gz
47
48This will create a fedora3 folder in your Greenstone3/ext folder.
49
504. Go to your Greenstone3 toplevel folder and now finally set up the GS3 environment:
51 $ source gs3-setup.sh
52
53This will now also have set up the fedora extension environment, such as FEDORA_HOME, FEDORA_VERSION and a PATH variable adjusted for Fedora.
54
555. Open Greenstone3/build.properties and find the section:
56
57 ##These need to be uncommented if using Fedora and Fedora GSearch with Greenstone's tomcat
58 fedora.home=#${basedir}/ext/fedora3
59 #fedora.maxpermsize=-XX:MaxPermSize=128m
60 #fedora.password=pounamu
61 #index.writelock.timeout=10000
62
63Uncomment all these properties and change the value for the fedora password if necessary:
64
65 ##These need to be uncommented if using Fedora and Fedora GSearch with Greenstone's tomcat
66 fedora.home=${basedir}/ext/fedora3
67 fedora.maxpermsize=-XX:MaxPermSize=128m
68 fedora.password=pounamu
69 index.writelock.timeout=10000
70
716. Use a terminal to go into this folder:
72 $ cd Greenstone3/ext/fedora3
73
747. If you type `ant` in the x-term, it will print the Usage message which will display the list of commands available and the order in which to execute them for proper installation. It's a 5 step process (explained in detail further below):
75
76 $ ant -Dgsdl3.home=<type-full-path-to-your-gs3> start-fedora-install
77
78 $ ant start
79
80 $ ant -Dgsdl3src.home=<type-full-path-to-your-gs3> continue-fedora-install
81
82 $ ant stop
83
84 $ ant -Dgsdl3src.home=<type-full-path-to-your-gs3> finish-fedora-install
85
86
87That's it.
88Now you can start tomcat again and visit http://localhost:8383/fedora and http://localhost:8383/fedoragsearch/rest to check the pages display.
89
908. You can start creating Greenstone Fedora collections with FLI. Run FLI from the GS3 toplevel folder by typing:
91 $ ./gli/fli.sh
92
93
949. Once you've tested everything is working, you may want to set logging level of Fedora GSearch to log ERRORs rather than all DEBUG statements. See the Debugging section in this file.
95
96
97DETAILS ON STEP 7:
98a. From your Greenstone3/ext/fedora3 folder, run:
99 $ ant -Dgsdl3.home=<type-full-path-to-your-gs3> start-fedora-install
100
101This step prepares the fedora and gsearch war files for deployment (by customising template files) and moves them into Greenstone 3's tomcat.
102
103b. Start tomcat by going into your GS3 toplevel folder and running:
104 $ ant start
105
106This step gets Greenstone's tomcat to deploy the fedora and fedoragsearch war files.
107You may want to check your Greenstone library is working by visiting http://localhost:8383/greenstone3 in your browser
108
109c. Go back into Greenstone3/ext/fedora3 and run:
110 $ ant -Dgsdl3src.home=<type-full-path-to-your-gs3> continue-fedora-install
111
112This target configures fedora-gsearch now that it has been deployed. It runs a fedora-gsearch ant build file to customise properties files that are internal to fedora-gsearch.
113
114d. Stop tomcat by going back into your GS3 toplevel folder and running:
115 $ ant stop
116
117You may want to check java instances running tomcat have indeed stopped:
118 $ ps aux | grep tomcat
119
120You will need to kill the process if any tomcat is still running at this stage (this can happen if you accidentally start tomcat several times in succession without stopping it).
121 $ kill -9 <process-id>
122
123e. Now that tomcat has stopped, go back into Greenstone3/ext/fedora3 and run:
124 ant -Dgsdl3src.home=<Full-Path-To-GS3> finish-fedora-install
125
126This will clean up the extension's war files in tomcat/packages/webapps now that they have already been deployed. (Do not perform this final step when tomcat is still running, else your fedora extension webapps will become undeployed.)
127
128
129
130When installation is completed, there will be a fedora3 folder in Greenstone3/ext, which you should not delete, since the Fedora Digital objects will be stored here, and the FedoraGSearch index will be created here.
131
132Further, the Fedora extension installation process would have made tomcat deploy several webapps in packages/tomcat/webapps. The resulting folders are:
133- fedora
134- fedora-demo
135- fedoragsearch
136- fop
137- imagemanip
138- saxon
139
140(Note that the installation process will have removed the Fedora extension war files it put into packages/tomcat/webapps during installation.)
141
142
143
144*****************************************
145UNINSTALLING FEDORA
146*****************************************
147
1481. Make sure tomcat is stopped.
149
1502. Go to /GS3/ext/fedora3 and run:
151 ant uninstall-fedora
152
153The above will remove
154- the deployed webapps (fedora, fedoragsearch, fedora-demo, fop, imagemanip and saxon.war)
155- as well as the ext/fedora3 folder itself.
156
157
158
159********************************************************************************************************************
160 B. Manual building of fedora collections
161********************************************************************************************************************
162
163You can use FLI to create, build and preview Fedora collections using Greenstone.
164
165The same can be done manually by calling the g2f perl scripts from the command line.
166
1671. Fedora needs to be running, so ensure the Greenstone tomcat is running:
168 ant start
169
1702. Set up the GS3 environment:
171 source gs3-setup.bash
172
1733. Create a new collection with mkcol.pl.
174 mkcol.pl -site localsite <COLNAME>
175
176(Deprecated: mkcol.pl -gs3mode -collectdir /<GS3>/web/sites/localsite/collect <COLNAME>)
177
1784. Run import and build to ingest the new collection. Make sure to use the correct host and port, as specified in your /<GS3>/build.properties file.
179
180- First put the documents you want into the import directory of your new collection.
181
182- g2f-import.pl -hostname localhost -port 8383 -password pounamu -removeold -collectdir /<GS3>/web/sites/localsite/collect <COLNAME>
183(password may be optional at this stage, by include it for convenience)
184
185- g2f-buildcol.pl -hostname localhost -port 8383 -password pounamu -removeold -collectdir /<GS3>/web/sites/localsite/collect <COLNAME>
186
187
188NOTE: The buildcol step would have created an index folder in the new fedora collection folder with a buildConfig.xml file in it containing the following:
189
190<buildConfig>
191 <metadataList/>
192 <serviceRackList>
193 <serviceRack name="FedoraServiceProxy" />
194 </serviceRackList>
195</buildConfig>
196
197
1985. If building the GS3 demo collection as a fedora collection:
199
200- use FLI to transfer dls to dc metadata upon Gathering the documents.
201- then before building, turn on the description_tags in the HTMLPlugin.
202Or manually add to the etc/collectionConfig.xml of the demo collection:
203
204 <plugin name="HTMLPlugin">
205 <option name="-description_tags"/>
206 </plugin>
207
208
209IMPORTANT NOTE: Fedora GSearch for some reason doesn't like the images in the default GS3 demo collection and is unable to index the documents because of them.
210If using the default GS3 demo collection, all the images -- both png and jpg alike -- need to first be resaved as their respective file types.
211Use Imagemagick to resave the many pngs, by going into each document's subfolder of the import folder and running:
212 mogrify -format png *.png
213
214Also open each folder's jpg document cover image in GIMP and resave under the same name (at 100% quality).
215
2166. If you ran FLI, exit it. It should stop the Greenstone server.
217
218With fedora installed, it's always good to check that the java process that launched tomcat has indeed stopped:
219 ps aux | grep "tomcat"
220
221(Since things will fail if multiple instances of this same tomcat are running, kill any java processes that are referring to tomcat.)
222
223
2247. Restart the GS3 server.
225 ant start
226
2278. Alternatively, to activate the collection, first visit the web page
228http://<host>:<port>/greenstone3/library?a=s&sa=a&st=collection&sn=<COLNAME>
229
2309. Then visit the collection from the Greenstone collections page
231
232
233*****************************************
234DELETING A FEDORA GS3 COLLECTION
235*****************************************
236
237Deleting a fedora GS3 collection requires the collection's documents and the collection file to be purged from the Fedora repository and removed from the Fedora Gsearch index. (In the case of a normal GS3 collection, just the GS3 collection's directory will be deleted.) There's now a script to delete a Greenstone Fedora collection which will take care of these additional steps if you are manually managing your collections. (FLI calls this script when a collection is deleted from FLI.)
238
239
240Deleting a Fedora GS3 collection is accomplished with the following 2 steps:
241
2421. Run the g2f-deletecol.pl script over the collection to be deleted:
243 g2f-deletecol.pl -hostname localhost -port 8383 -password pounamu -collectdir /<GS3>/web/sites/localsite/collect <COLNAME>
244
245(Note: no -removeold flag, otherwise the command is similar to the g2f-import.pl and g2f-buildcol.pl scripts)
246
2472. Manually delete the Greenstone collection directory from the filesystem
248
249
250To run this manually,
251- first remove the pids from the GSearch index:
252/<GS3>/packages/tomcat/webapps/fedoragsearch/client>/<GS3>/packages/tomcat/webapps/fedoragsearch/client/runRESTClient.sh localhost:8383 updateIndex deletePID <DOC-PID e.g. greenstone:fedora1-HASH010313b14474bc72b296b15f>
253
254It will ask for the fedoragsearch username and password, which by default are fedoraAdmin and pounamu, respectively.
255
256- then purge the necessary documents (pids) from the fedora repository:
257/<GS3>/ext/fedora3/client/bin>./fedora-purge.sh localhost:8383 fedoraAdmin pounamu <DOC-PID e.g. greenstone:fedora1-HASHe14e36cba08bd41c663237> http "purging"
258
259- You can check it's all been deleted by visiting http://localhost:8383/fedora/search
260and searching for:
261
262greenstone:*
263or greenstone:<colname>*
264
265Visit http://localhost:8383/fedoragsearch/rest?operation=browseIndex
266and browse the PID field
267
268You can also visit http://localhost:8383/fedoragsearch/rest?operation=gfindObjects
269then you can search for a query term by prefixing the index field to it, e.g ds.fulltext:computers
270
271
272
273********************************************************************************************************************
274 C. The customisations that have been made for the extension
275********************************************************************************************************************
276
277This section is of use when Fedora or GSearch is updated or if you want to update the fedora3-gs3ext.tar.gz distribution file with further customisations.
278
279The first version of the Fedora extension for Greenstone uses Fedora 3.6.1 and the GSearch 2.5 (which goes with Fedora 3.6.1).
280
281Some template files were added to Fedora and Fedora Gsearch's distribution files in order to customise these for installing them within a Greenstone 3 installation. These files are committed to SVN (without directory structure) at http://trac.greenstone.org/browser/gs3-extensions/fedora/trunk/src/fedora-files and http://trac.greenstone.org/browser/gs3-extensions/fedora/trunk/src/fedoragsearch-files
282
283They can be edited there if and when necessary, but they would then need to be included in the extension's distribution file fedora3-gs3ext.tar.gz to update its own existing copies.
284
285That's because these template files are included in the Fedora Extension for GS3 (fedora3-gs3ext.tar.gz). The extension's build.xml modifies these template files when installing the Fedora Extension into Greenstone 3. The template files contain placeholder strings that get updated when ant targets are run over the build.xml file.
286
287
2881. The customisation files for Fedora 3.6.1 are:
289
290- ./install/install.properties.in
291- ./install/server.xml.in
292- ./server/config/spring/akubra-llstore.xml.in
293- ./server/config/spring/web/web.properties.in
294- ./server/config/fedora.fcfg.in
295- ./server/config/fedora-users.xml.in
296
297
298(The following also need to refer to the servername and custom Greenstone tomcat port
299- ./client/bin/fedora-ingest-demos.bat.in
300- ./client/bin/fedora-ingest-demos.sh.in)
301
302
303All these files get converted to filenames without the ".in" suffix upon installation, and placeholder strings in these template files get replaced. The replacements are on the strings
304- @GSDL3SRCHOME@
305- @FEDORA_HOME@ (set to gsdl3srchome/ext/fedora3)
306- @tomcatserver@
307- @tomcatport@
308- @tomcatshutdownport@
309- @fedorapassw@
310- @indexwritelocktimeout@
311
312Except for the first, which needs to be set when running the Fedora extension's ant targets, all the remaining ones can be specified in Greenstone 3's toplevel build.properties.
313
314
3152. The customisation files for Fedora GSearch 2.6 are located in the "adjust_war_files" subfolder of fedora3-gs3ext.tar.gz file. This custom folder contains the official unpacked fedoragsearch folder, but with the following customisation files:
316
317- adjust_war_files/fedoragsearch/WEB-INF/web.xml
318- adjust_war_files/fedoragsearch/FgsConfig/fgsconfig-basic.properties.in
319- adjust_war_files/fedoragsearch/FgsConfig/FgsConfigIndexTemplate/Lucene/foxmlToLucene.xslt
320- adjust_war_files/fedoragsearch/FgsConfig/FgsConfigIndexTemplate/Lucene/foxmlToLuceneGenerated.xslt
321- adjust_war_files/fedoragsearch/FgsConfig/FgsConfigIndexTemplate/Lucene/index.properties
322- adjust_war_files/fedoragsearch/client/runRESTClient.sh
323- adjust_war_files/fedoragsearch/client/runSOAPClient.sh
324- adjust_war_files/fedoragsearch/client/runSOAPClient.bat
325
326
327All these files will get copied into the same locations within <GS3>/packages/tomcat/webapps/fedoragsearch. The file fgsconfig-basic.properties.in will get copied as fgsconfig-basic.properties but with the previously-listed placeholder strings replaced.
328
329
3303. There's also the fedora.xml.in inside the "adjust_war_files" folder of the unpacked extension. This template file will be copied over as <GS3>/packages/tomcat/conf/Catalina/localhost/fedora.xml during the extension installation process, also with placeholder strings replaced.
331
332
333DETAILS TO STEP 2 (Fedora GSearch customisation files):
334
335a. The changes to web.xml are that the authorisation filters are commented out:
336
337<!--
338 <filter-mapping>
339 <filter-name>EnforceAuthnFilter</filter-name>
340 <servlet-name>AxisServlet</servlet-name>
341 </filter-mapping>
342 <filter-mapping>
343 <filter-name>EnforceAuthnFilter</filter-name>
344 <servlet-name>GenericSearchREST</servlet-name>
345 </filter-mapping>
346 <filter-mapping>
347 <filter-name>EnforceAuthnFilter</filter-name>
348 <url-pattern>/index.html</url-pattern>
349 </filter-mapping>
350 <filter-mapping>
351 <filter-name>EnforceAuthnFilter</filter-name>
352 <url-pattern>/rest</url-pattern>
353 </filter-mapping>
354-->
355
356
357b. The 3 client scripts runRESTClient.bat, runRESTClient.sh and runSOAPClient.sh have been modified to be runnable from any directory, as they will be called by GS3's g2f perl scripts.
358
359- The bash files have been made executable on extraction of the GS3 Fedora extension and the following has been added to the top of the files:
360
361 # Need to run this script from its own directory instead of whichever directory it may be called from
362 thisdir="`dirname \"$0\"`"
363 thisdir="`cd \"$thisdir\" && pwd`"
364 cd "$thisdir"
365
366
367- Additions to the bat scripts are at the top and bottom:
368
369 @echo off
370
371 ::pushd "%CD%"
372 set startdir=%CD%
373 CD /D "%~dp0"
374
375 ...
376
377 :: popd
378 cd "%startdir%"
379 set startdir=
380
381
382c. The changes to fedoragsearch/FgsConfig/FgsConfigIndexTemplate/Lucene's foxmlToLucene.xslt and foxmlToLuceneGenerated.xslt are identical. The following xslt has been added:
383
384- Add the following namespaces to the namespace declarations at the top:
385 xmlns:ex="http://www.greenstone.org/namespace/fake/ex"
386 xmlns:dls="http://www.greenstone.org/namespace/fake/dls"
387
388- Add custom indexing for EX and DLS datastreams below the comment on datastreams:
389
390 <!-- a datastream is fetched, if its mimetype
391 can be handled, the text becomes the value of the field.
392 This is the version using PDFBox,
393 below is the new version using Apache Tika. -->
394
395 <xsl:for-each select="foxml:datastream[starts-with(@ID,'EX')]/foxml:datastreamVersion[last()]/foxml:xmlContent/ex:ex/ex:metadata">
396 <IndexField index="TOKENIZED" store="YES" termVector="YES">
397 <xsl:attribute name="IFname">
398 <xsl:value-of select="concat('ex.', @name)"/>
399 </xsl:attribute>
400 <xsl:value-of select="text()"/>
401 </IndexField>
402 </xsl:for-each>
403
404 <xsl:for-each select="foxml:datastream[starts-with(@ID,'DLS')]/foxml:datastreamVersion[last()]/foxml:xmlContent/dls:dls/dls:metadata">
405 <IndexField index="TOKENIZED" store="YES" termVector="YES">
406 <xsl:attribute name="IFname">
407 <xsl:value-of select="concat('dls.', @name)"/>
408 </xsl:attribute>
409 <xsl:value-of select="text()"/>
410 </IndexField>
411 </xsl:for-each>
412
413- Near the end of the XSLT files, just after index for the "foxml.all.text" field, allow just the full text of the documents to be indexed by adding an index for the ds.fulltext field:
414
415 <IndexField IFname="ds.fulltext" index="TOKENIZED" store="YES" termVector="YES">
416 <xsl:for-each select="//foxml:datastream[@CONTROL_GROUP='M' or @CONTROL_GROUP='E' or @CONTROL_GROUP='R']">
417 <xsl:value-of select="exts:getDatastreamText($PID, $REPOSITORYNAME, @ID, $FEDORASOAP, $FEDORAUSER, $FEDORAPASS, $TRUSTSTOREPATH, $TRUSTSTOREPASS)"/>
418 <xsl:text> </xsl:text>
419 </xsl:for-each>
420 </IndexField>
421
422
423Further datastreams and metadata sets can be indexed by adding similar namespace declarations and xml elements to these 2 XSLT files.
424If the changes are not meant to apply for all Greenstone users, individual Greenstone users can add fields for indexing by making such changes to just the file fedoragsearch/FgsConfig/FgsConfigIndexTemplate/Lucene/foxmlToLuceneGenerated.xslt
425
426
427d. By default, Lucene's lock obtain timeout is set to 0 in its properties file, which is not acceptable for all but the smallest documents. The lock timeout can be customised in build.properties and by default is set to 10000 (or 1000), which can be adjusted before starting the Fedora extension installation process.
428
429The installation process will write out this property into GSearch's FgsConfig/FgsConfigIndexTemplate/Lucene/index.properties:
430 fgsindex.defaultWriteLockTimeout = 10000
431
432(Another relevant place to change it would be ./FgsConfig/configDemoOnLucene/fgsconfigFinal/index/FgsIndex/index.properties)
433
434When fedoragsearch then gets deployed, this value will be propagated into:
435 <GS3>/packages/tomcat/webapps/fedoragsearch/WEB-INF/classes/fgsconfigFinal/index/FgsIndex/index.properties
436
437
438
439********************************************************************************************************************
440 D. To manually set up Fedora with Fedora GSearch 2.5 from scratch
441********************************************************************************************************************
442
443When installing Fedora, you can choose to install it outside Greenstone, and also instruct it to use its own tomcat. However, in the following instructions, Fedora's installation location (FEDORA_HOME) is still taken to be /GS3/ext/fedora3, since it's assumed Fedora is be installed to use Greenstone's tomcat.
444
445The Fedora GSearch war file will need to be unpacked in the tomcat/webapps folder of whichever tomcat Fedora is using. In the following, this is still Greenstone's tomcat.
446
447In whichever location Fedora is installed, that's where Fedora will store its digital objects and their datastreams, and that's where Fedora GSearch will create its GSearch index.
448
449
450********************************
451INSTALLING FEDORA
452********************************
4531. Set FEDORA_HOME=/<GS3>/ext/fedora3 in .profile (emacs ~/.profile)
454source ~/.profile
455
4562. Run fedora installer:
457 java -jar fcrepo-installer-3.6.1.jar
458
459Install by specifying to use the existing tomcat (existingTomcat), and provide the Greenstone3 tomcat stop and start ports (usually 8383 and 8305).
460Then set the existingTomcat to the Greenstone3 one: /<GS3>/packages/tomcat
461Turn on messaging, as this is necessary for Fedora GSearch.
462
463- Installation options:
464
465custom
466FEDORA_HOME
467pwd: pounamu
468host: <full-tomcat.server-host-name>
469def server context: fedora
470default false for user authentication for APIA-A
471false for SSL availability
472existingTomcat
473path to tomcat: </full-path-to-GS3>/packages/tomcat
474tomcat listen port: 8383
475tomcat shutdown port:8305
476derby:included
477upstream HTTP authentication: (default) false
478FeSL AuthZ: (default) false
479XACML policy enforcement enabled: false
480Low Level Storage: (default) akubra-fs
481Resource Index: true
482Enable Messaging: true
483Messaging Provider URI: [default is vm:(broker:(tcp://localhost:61616))]
484Deploy local services and demos: (default) true
485
486
487- The Fedora installation options used are to be found (after installation) in fedora3/install/install.properties:
488
489#Install Options
490#Fri Sep 21 15:29:29 NZST 2012
491ri.enabled=true
492messaging.enabled=false
493apia.auth.required=false
494database.jdbcDriverClass=org.apache.derby.jdbc.EmbeddedDriver
495upstream.auth.enabled=false
496ssl.available=false
497database.jdbcURL=jdbc\:derby\:/<GS3>/ext/fedora3/derby/fedora3;create\=true
498database.password=fedoraAdmin
499database.username=fedoraAdmin
500fesl.authz.enabled=false
501tomcat.shutdown.port=8305
502deploy.local.services=true
503xacml.enabled=false
504tomcat.http.port=8383
505fedora.serverHost=<full-tomcat.server-host-name>
506database=included
507database.driver=included
508fedora.serverContext=fedora
509llstore.type=akubra-fs
510tomcat.home=/<GS3>/packages/tomcat
511fedora.home=/<GS3>/ext/fedora3
512install.type=custom
513servlet.engine=existingTomcat
514fedora.admin.pass=pounamu
515
516
517- If trying to turn a custom installation into one for distribution, you would need to modify the following 4 files by inserting placeholder strings where applicable for the tomcatserver name, tomcat listen port and shutdown port, fedorapassword, GSLD3SRCHOME and FEDORA_HOME:
518
519fedora3/install/install.properties
520fedora3/server/config/spring/akubra-llstore.xml
521fedora3/server/config/fedora.fcfg
522fedora3/server/config/fedora-users.xml
523
524Then you would rename these files with the suffix .in
525
526
5273. Just to confirm there are no differences between the server.xml fedora has generated for fedora, and the server.xml of GS3's tomcat, run a diff:
528
529 diff -w /<GS3>/packages/tomcat/conf/server.xml </GS3/ext/>fedora3/install/server.xml
530
5314. Copy the fedora war files from fedora3/install into packages/tomcat/webapps
532fedora.war, fedora-demo.war, fop.war, imagemanip.war, saxon.war
533
5345. Copy the jar files xalan.jar, serializer.jar (and xsltc.jar) from Greenstone3's web/WEB-INF/lib into Greenstone3's packages/tomcat/lib so that fedora has access to the xalan version of the TransformerFactoryImpl class.
535
536There's also a xalan.jar in /<GS3>/packages/tomcat/webapps/fop/WEB-INF/lib
537So this can be copied into /<GS3>/packages/tomcat/lib/. instead of the Greenstone version.
538
5396. Create the file /<GS3>/packages/tomcat/conf/Catalina/localhost/fedora.xml
540containing:
541
542<?xml version="1.0" encoding="UTF-8"?>
543<Context>
544 <Parameter name="fedora.home" value="/<GS3>/ext/fedora3" />
545</Context>
546
547
5487. Before running the Greenstone server, make a copy of the fedora3 folder. Because once you start up tomcat, and visit the fedora home page, it will create a lot of files customised to the location of the current installation.
549
5508. Visit http://localhost:8383/greenstone3 and
551 http://localhost:8383/fedora
552
553to confirm both work.
554
555
556********************************
557INSTALLING FEDORA GSEARCH
558********************************
5591. Download Fedora GSearch 2.5
560
5612. Stop tomcat. Copy the fedoragsearch.war files into /<GS3>/packages/tomcat/webapps
562
563If Fedora was not installed with messaging turned on, then turn it on in now /<GS3>/ext/fedora3/server/config/fedora.fcfg:
564
565 <module role="org.fcrepo.server.messaging.Messaging" class="org.fcrepo.server.messaging.MessagingModule">
566 <comment>Fedora's Java Messaging Service (JMS) Module</comment>
567 <param name="enabled" value="true"/>
568 ...
569
5703. Update the following properties in /<GS3>/packages/tomcat/webapps/fedoragsearch/FgsConfig/fgsconfig-basic.properties
571
572gsearchBase=http://<tomcat.server>:8383
573gsearchUser=fedoraAdmin
574gsearchPass=<fedora.password>
575local.FEDORA_HOME=/<GS3>/ext/fedora3
576finalConfigPath=/<GS3>/packages/tomcat/webapps/fedoragsearch/WEB-INF/classes
577
578fedoraBase=http://<tomcat.server>:8383
579fedoraPass=<fedora.password>
580
5814. Add the edited foxmlToLucene.xslt & foxmlToLuceneGenerated.xslt files to /<GS3>/packages/tomcat/webapps/fedoragsearch/FgsConfig/FgsConfigIndexTemplate/Lucene
582
5835. Add the edited runRESTClient.sh (and runSOAPClient.sh, runRESTClient.bat) to /<GS3>/packages/tomcat/webapps/fedoragsearch/client
584And give them execute permissions, unless they already have it.
585
5866. In a text editor, open up /<GS3>/packages/tomcat/webapps/fedoragsearch/WEB-INF/web.xml
587and comment out the authentication filters (one or two of these is probably all that is necessary):
588
589<!--
590 <filter-mapping>
591 <filter-name>EnforceAuthnFilter</filter-name>
592 <servlet-name>AxisServlet</servlet-name>
593 </filter-mapping>
594 <filter-mapping>
595 <filter-name>EnforceAuthnFilter</filter-name>
596 <servlet-name>GenericSearchREST</servlet-name>
597 </filter-mapping>
598 <filter-mapping>
599 <filter-name>EnforceAuthnFilter</filter-name>
600 <url-pattern>/index.html</url-pattern>
601 </filter-mapping>
602 <filter-mapping>
603 <filter-name>EnforceAuthnFilter</filter-name>
604 <url-pattern>/rest</url-pattern>
605 </filter-mapping>
606-->
607
608Maybe what I really need to comment out is:
609 <filter>
610 <filter-name>EnforceAuthnFilter</filter-name>
611 <filter-class>org.fcrepo.server.security.servletfilters.FilterEnforceAuthn</filter-class>
612 </filter>
613
6147. Open GSearch's FgsConfig/FgsConfigIndexTemplate/Lucene/index.properties and adjust the lock timeout property to 1000 or 10000 ms:
615 fgsindex.defaultWriteLockTimeout = 10000
616
6178. Start tomcat to have it deploy fedoragsearch.
618This will unpack fedoragsearch.
619
6209. With tomcat running, configure fedoragsearch, which will adjust various config files. You will need to go into the deployed fedoragsearch webapps folder's FgsConfig folder first to be able to run the configuration target:
621
622 <GS3>/packages/tomcat/webapps/fedoragsearch/FgsConfig>ant -f fgsconfig-basic.xml
623
62419. With tomcat still running, run updateIndex once to create the empty index for the first time (by running the runRESTClient.sh script with the command: "host:port updateIndex createEmpty [indexName]")
625
626 ./<GS3>/packages/tomcat/webapps/fedoragsearch/client/runRESTClient.sh localhost:8383 updateIndex createEmpty FgsIndex
627
62811. Check fedoragsearch has been properly installed by visiting:
629http://localhost:8383/fedoragsearch/rest
630
63112. If you wish to remove the various war files from GS3's tomcat webapps folder, you will need to stop tomcat first before deleting the war files, because doing so when tomcat is running will undeploy those webapps.
632
633
634********************************
635DEBUGGING
636********************************
637
638Logs to consult when debugging:
639
6401. Check /<GS3>/packages/tomcat/logs/catalina.out
641
6422. </GS3/ext/>fedora3/server/logs/fedora.log for Fedora error logging.
643
6443. To turn on FedoraGSearch's logging of debug statements (Huge files, can reach 500 Mb in a day if rebuilding the demo collection. So you may want to switch this off when not debugging by setting the debug level to INFO):
645
646- /<GS3>/packages/tomcat/webapps/fedoragsearch/WEB-INF/classes/log4j.xml is already set to output DEBUG statements and higher logging levels
647- So open </GS3/ext/>fedora3/server/logs/fedoragsearch.daily.log to look at debug messages in case fedoragsearch doesn't work as expected.
648
649
650********************************************************************************************************************
Note: See TracBrowser for help on using the repository browser.