Oystein Reigem, AKSIS/WAB 2008-11-05
Re installation of eXist and the servlets for search
How to change to a newer (different) version of eXist
When there is a need or wish to upgrade to a newer version of eXist (or in general to change to a different version of eXist), one should prepare an eXist war file for that version, and make the new war file available for future installing. (The preparation of a new eXist war file is something that should be handled centrally, and not at community level.)
To replace a community's eXist with a newer one, one should remove their current eXist, install the new one, and of course run the feeding process anew, because the new eXist will have an empty database (collection).
In brief the procedure for preparing a new eXist war file is the following:
- Download and install the relevant version of eXist from SourceForge.
- Make some changes and settings.
- Package this configured eXist as a war file.
Here are more details:
Download eXist
Download eXist as a war file from http://exist.sourceforge.net/index.html#download. The site will have other versions than the war file, but using the war version is the tried and tested way.
Install eXist
Install the eXist war fil like any other war file under Tomcat.
Change eXist's configuration files
Make sure Tomcat is not running.
Change eXist's configuration file configuration.xml, in eXist's main directory: Locate the <watchdog> element and increase the value of the output-size-limit attribute from 10000 to 1000000. (The value is the maximum size of a result, measured in DOM nodes.) Stop press! The value -1 (unlimited) might also be used, but has not been tested.
Possibly change eXist's configuration file conf.xml, in eXist's WEB-INF directory: Locate the <indexer> element and check the value of the preserve-whitespace-mixed-content attribute. The value should be "yes" and not "no". (The setting of this funnily-named attribute influences the indexing and search where words cross element boundaries, e.g, dis<em>cov</em>ery. "yes" makes eXist see such a word as one word (discovery) and not several ones (dis cov ery).)
Define collections
Start Tomcat.
In general an eXist database is organised as a hierarchy of "collections", similar to a directory structure. In our case we want a simple, flat structure, with collections at root level.
By default there is one collection defined already, albeit a special one - the system collection. There might also be other collections there by default.
Normally each community will have their own copy of eXist, and therefore need only one collection in their eXist. But sometimes more than one community will share the same copy of eXist. Therefore make five collections named mycollection, mycollection2, mycollection3, mycollection4 and mycollection5, to have enough collections for this case.
To define collections run the "Java Admin Client" for eXist. This tool can be found at the bottom of the left menu of the installed eXist's home page, from either of the items marked "Webstart Client" or "Launch".
About the location of the home page: Assume eXist was installed on a server with domain example.net, that Tomcat runs on port 8080, and that eXist was unpacked to directory exist-1.2.0. Then the URL of the home page is http://example.net:8080/exist-1.2.0/index.xml. (Note the xml extension.)
Login with the default admin user and no password.
Don't define any password. The password will be set much later, after eXist has been installed at the community's server.
The client's main window has an upper, graphical part, where the default collections show. Use the lower, command-based part of the client to define a new collection named mycollection. Do this with the command
mkcol mycollection (Enter)
Notice that the client's name for the root of the collection hierarchy is exist:db/.
Repeat for collections mycollection2, mycollection3, mycollection4 and mycollection5.
Define indexing for the collections
Do this also with the client.
Indexes for a collection are defined in a special xml document, stored in a special place in the collection hierarchy. For the mycollection collection this place is
exist:/db/system/config/db/mycollection
Make this path with a combination of mkcol and cd commands in the lower part of the client. Be precise or the indexing will not work. As an alternative for cd commands (double)click in the upper part of the client.
Finally insert a document collection.xconf with indexing specifications at this place. The specifications are found in the file http://svn.talia.discovery-project.eu/talia/trunk/exist_search/tomcat/exist/indexing/collection.xconf.
There are two ways to insert the document:
- Use a put command from the lower part of the client.
- Use the File | Make Empty Document menu choice.
To use the first alternative first make sure that the collection.xconf file is available from the file system where eXist resides, say, at /home/somebody/collection.xconf. Then use the command
put /home/somebody/collection.xconf
To use the second alternative, make a copy of the contents of the collection.xconf file, use File | Make Empty Document to make a document, paste the contents in, and store under the name collection.xconf. Be precise with the name or the indexing will not work.
Repeat for collections mycollection2, mycollection3, mycollection4 and mycollection5.
Package as war file
Package the configured eXist as a war file. As discussed elsewhere the name used should perhaps reflect the version of eXist, which it will do already, unless the name was changed since downloading from SourceForge.
