Installation of eXist and the servlets for search

Oystein Reigem, AKSIS/WAB 2008-11-05

### = unresolved issues.

Installation in brief

eXist and the java servlets for search are meant to be run under Tomcat (or a similar application server). They are packed as two war files.

The war files reside at http://svn.talia.discovery-project.eu/talia/trunk/exist_search/installation/ .

Installation essentially consists of doing a few Tomcat settings, placing the two war files in the Tomcat webapps directory, where Tomcat will unpack them, and then make a few manual changes.

Installation instructions

Define roles and users in Tomcat

Define new roles, and a user, in the file tomcat-users.xml in Tomcat's conf directory:

- <role rolename="exist-feeder"/>

- <role rolename="exist-searcher"/>

- <user username="talia" password="xxxxxx" roles="exist-feeder,exist-searcher"/>

Make sure that the user name and password agree with those set in Talia's configuration file config/talia_core.yml. In the latter file the relevant parameters might be called exist_login and exist_password, but strictly they are login values for Tomcat, not for eXist. "talia" is a good name for the user, since it is the Talia programs that will use the user.

Tomcat presumably has a system administrator, with an entry like the following:

- <user username="capo" password="yyyyyy" roles="admin,manager"/>

If that person also runs tests and maintenance on the servlets, it is useful to extend the roles so all tasks can be done from the same user:

- <user username="capo" password="yyyyyy" roles="admin,manager,exist-feeder,exist-searcher"/>

Unpack the war files

Get the two war files from http://svn.talia.discovery-project.eu/talia/trunk/exist_search/installation/ .

Change the names of the war files if desired. It is recommended to change the name of the servlet application war file - mycommunity.war - to something that reflects the name of the community, e.g, nietzsche.war.

Edit Talia's configuration file config/talia_core.yml, so that Talia knows about the new servlet application name.

If several communities share the same server, it is recommended they each have their own copy of eXist. Then - to avoid a name conflict - also rename the eXist war, e.g, to nietzsche-exist.war.

More about renaming in ExistAndServletsInstallation_FileNames.

Stop Tomcat (might not be necessary).

Copy the war files to the webapps directory of Tomcat.

Start Tomcat; the war files will be unpacked.

Wait util they are fully unpacked.

At this point it is safest to move the war files somewhere else, so they will not be automatically unpacked by accident later, although this step can be skipped by the experienced administrator. If the files are moved, make sure to stop Tomcat first

Do some settings

eXist admin password

Start Tomcat again, unless it is already running.

Go to the home page of the installed eXist. Assume the applications were 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.)

Run the "Java Admin Client" for eXist. This tool can be found at the bottom of the left menu of the home page, from either of the items marked "Webstart Client" or "Launch".

Login with the default admin user and no password.

The client's main window appears. Click the icon with an image of some keys on it.

A user administration window appears. In the top of the window click and select the admin user. Further down fill in a password for the admin user (twice). Then click the Modify user button.

Close the client, start the client again, and log in to see if the new password really works.

Collection name

In eXist the community's data will by default be stored in a "collection" called mycollection. This name will not be visible to end users, but it is still recommended to change it into something community-specific, e.g, "nietzsche". If more than one community share not only the same server, but also the same eXist, it is necessary to have different names.

Important! The change must be done two places - first for the collection itself and then for another collection that contains the index definitions. Both collections are called mycollection.

Start the client unless it is already running. Log in.

The collection itself will immediately be visible in the client's upper part. Select it and do the change, with the File | Change Name menu choice.

To find that other collection with the index definitions, navigate in the client's upper part by doubleclicking the following entries in turn:

- system

- config

- db

Then change the name of the mycollection indexing collection the same way as above.

If more than one community share the same eXist, use the additional collections mycollection2, mycollection3.

Unused collections can be left; they cause no harm. Delete them if desired.

Stop Tomcat.

web.xml

Make sure Tomcat is not running.

Edit the webapps/mycommunity/WEB-INF/web.xml file. (Well, of course the directory name might now be something else than mycommunity.) Look up the <context-param> elements and carefully change the values of the <param-value> elements. There are comments in the file explaining what the parameters are.

Presumably the value of the tomcatHost parameter can be localhost, but this has not been completely tested.

Start Tomcat.

log4j.xml

Log4j.xml file is used for configure the logger for search serlvet.

Edit the webapps/mycommunity/WEB-INF/log4j.xml file and set File params to local log directory (for example: ${catalina.home}/webapps/<my community>/WEB-INF/log/search.log).

level params can be used for set log level (default level value is ERROR).

Test

(What is the best way to test the installation?) ###

Possible problems

org.apache.catalina.loader.WebappClassLoader validateJarFile
INFO: validateJarFile(/.../.../.../.../webapps/mycommunity/WEB-INF/lib/servlet-api.jar) - jar not loaded. See Servlet Spec 2.3, section 9.7.2. Offending class: javax/servlet/Servlet.class

If this error message appears (in the catalina.out Tomcat log file?###), try to remove/rename the file mentioned in the message (<Tomcat_directory>/webapps/mycommunity/WEB-INF/lib/servlet-api.jar).

In principle this file is not necessary because Tomcat has got its own copy of the file, in its own lib directory. But the developer found it necessary to have the file also in the servlet application's lib. However - there might be cases (newer versions of Tomcat?) where the file is both unnecessary and causing problems.

(Describe other problems?) ###