Installing WERTiCore
====================

This document should help you get WERTiCore running with the demo 
determiners activity that highlights any tokens tagged DT by the OpenNLP 
tagger.  In order to avoid conflicts with the original WERTi firefox 
extension, the servlet and the firefox extension have been renamed to 
WERTiCore so that it's possible to have both extensions installed at the 
same time.

Instructions for building and deploying with eclipse are included at the 
end of this file.


Requirements
------------

* Tomcat (http://tomcat.apache.org/) (version 5 or higher)
* Maven (http://maven.apache.org/)
* See "Building" below for details on the remaining dependencies that will 
  be downloaded automatically by maven)


Settings Paths to Model Files
-----------------------------

The demo determiners activity requires several model files from OpenNLP.  
The models are included in the directory 'src/main/resources/models' or 
can be downloaded from the OpenNLP website:

    http://opennlp.sourceforge.net/models.html

Download the models for OpenNLP 1.5.

By default (see src/main/webapp/WERTi.properties), WERTi looks for these 
files in src/main/resources/models, where they are included with this 
distribution.


Building
--------

After the model files are in place, you can compile WERTi from the 
top-level directory with

    mvn package

Maven will automatically download a number of dependencies including:

* UIMA (http://uima.apache.org/)
  - uimaj-core-2.2.2-incubating.jar (2.2.2 is outdated and no longer available. Using 2.3.1 for now.)
* OpenNLP (http://opennlp.sourceforge.net/)
  - opennlp-tools-1.4.3.jar
  - maxent-2.5.2.jart
  - trove-1.0.2.jar
  - jwnl-1.3.3.jar
* log4j (http://logging.apache.org/log4j/)
  - log4j-2.12.4.jar
* GSON (http://code.google.com/p/google-gson/)
  - gson-1.4.jar
* jsoup (http://jsoup.org)
  - jsoup-1.2.1.jar
  - commons-lang-2.4.jar

If any of the maven repositories are unavailable, you can alternatively 
point maven to a local copy of a library as follows:

    mvn install:install-file \
	-DgroupId=opennlp \
	-DartifactId=opennlp-tools \
	-Dversion=1.4.3 \
	-Dfile=/path/to/opennlp-tools-1.4.3.jar \
	-Dpackaging=jar

The build process will:

- download any necessary libraries
- generate the UIMA types using JCasGen
- compile everything
- package an up-to-date version of the firefox add-on
- create the WAR file for deploying on the server


Deploying
---------

While WERTi may run on other servlet containers, it has so far only been 
tested with Tomcat 5.x and 6.x. There are several ways of deploying the 
application.


Deploying: Using the Maven Tomcat Plugin
----------------------------------------

Maven's tomcat plugin can deploy webapps on a local or remote tomcat 
server.

See the documentation for deploying:

    http://mojo.codehaus.org/tomcat-maven-plugin/deployment.html

and the usage and configuration documentation:

    http://mojo.codehaus.org/tomcat-maven-plugin/usage.html

on the official site.

An example maven command to redeploy the webapp on a local server:

    mvn -Dtomcat.username=user -Dtomcat.password=xxxx tomcat:redeploy

The tomcat user should have the manager role in the tomcat configuration 
file 'conf/tomcat-users.xml'.


Deploying: Using Symlinks
-------------------------

If WERTi is installed on your local system, then placing a symlink from 
'$CATALINA_BASE/webapps' to 'target/WERTi' is an easy way to deploy WERTi 
locally. You can use the 'mvn war:exploded' task to redeploy the 
application. Note that tomcat will require you to 'touch' WERTi's 
'web.xml' for it to notice a change and reload.


Using WERTi
-----------

After deploying WERTi on your local system, go to

    http://localhost:8080/WERTiCore
    
to verify that the server is running.  You should see a demo WERTi 
website.

Under Topics and Activities -> Determiners

    http://localhost:8080/WERTiCore/index.jsp?content=activity-help&activity=Dets
    
you should be able to enter a URL to see a demo of the determiners topic.

Next, try installing the firefox add-on from this page

    http://localhost:8080/WERTiCore/index.jsp?content=firefox-extension
    
You should be able to run any of the Determiner activities on any web page 
you can display in firefox.


Documentation
-------------

Javadocs and a complete API can be generated by calling the following command:

    mvn javadoc:javadoc

The docs will appear in 'target/site/apidocs'.


Logging
-------

The logging configuration is in 

    src/main/webapp/WEB-INF/classes/log4j.properties


Using Eclipse
-------------

Install the eclipse WTP tools. (http://www.eclipse.org/webtools/)

Install the m2eclipse plugin. (http://m2eclipse.sonatype.org/)

Create a new maven project from a POM file.  Select the file 'pom.xml' in 
the top level of WERTiCore to import the project.

After it's finished building the project for the first time, there will be 
many errors related to the UIMA types.  Refresh the project for it to find 
the types generated by JCasGen in werti.uima.types and 
werti.uima.types.annot and let it recompile everything.

Add a tomcat server.  Add WERTiCore to the server.  Start the server.  Go 
through the steps in "Using WERTi" above to check that everything is 
working.


Troubleshooting
---------------

See the troubleshooting section in 'docs/EXTENDING'.