American Numismatic Society Documentation

xEAC is an XForms application that runs in the Apache Tomcat application, Orbeon. Tomcat runs in a Java environment on any operating system. xEAC is typically easier to deploy on Linux servers, especially those with package managers, such as Ubuntu or RedHat Fedora. The steps for deploying xEAC onto a server are outlined below. For specific step-by-step instructions (for example, for installing the Sun Java JDK and Apache Tomcat), please refer to documentation maintained by those developers, which is easy enough to find in a search engine.

These instructions will vary slightly from system to system, but by the same general guidelines for deploying Tomcat services apply to Windows, Linux, and Mac.

We will assume in the documentation that $TOMCAT_HOME is the location of the Tomcat installation on your server. If you install tomcat7 through the Synaptic Package Manager on Ubuntu, $TOMCAT_HOME will be /var/lib/tomcat7

See specific instructions for installing Tomcat. Note that Tomcat can now be deployed directly from the package manager of major Linux distributions, such as Ubuntu. The Orbeon XForms processor requires a significant amount of heap space devoted to Java (at least 1024MB), so please see instructions for configuring the virtual machine.

Download the latest free, open source Orbeon Community Edition (CE) zip file. Within the root folder in this zip file, you'll find orbeon.war. Extract orbeon.war and place in the Tomcat webapps folder.

Two minor configurations need to be applied to Orbeon.

• Allow symlinks within the Orbeon webapp directory structure:
  • Create orbeon.xml in $TOMCAT_HOME/conf/Catalina/localhost
  • Insert the following XML fragment (substituting “/var/lib/tomcat7” with $TOMCAT_HOME if necessary):

<Context path="/orbeon" docBase="/var/lib/tomcat7/webapps/orbeon" allowLinking="true"/>
 

• Set the plain theme:
  • Go to $TOMCAT_HOME/webapps/orbeon/WEB-INF/resources/config
  • Edit properties-local.xml.template, insert within <properties>:

<property as="xs:anyURI" name="oxf.epilogue.theme" value="oxf:/config/theme-plain.xsl"/>
 

• Save file. Rename properties-local.xml.template to properties-local.xml

Tomcat may need to be restarted for these changes to take effect.

Clone/fork/download the xEAC Github repository: https://github.com/ewg118/xEAC

You can put this anywhere in your filesystem. In my development, test, and production environments (in Linux operating systems), I clone projects to /usr/local/projects. Create a symlink at $TOMCAT_HOME/webapps/orbeon/WEB-INF/resources/apps/xeac which points to your installation.

Note: Be sure that the folder/symlink name is lower-case 'xeac'

xEAC depends upon eXist as the XML database, but this could be switched with another XML database which follows the same REST protocols. The eXist WAR file should be placed in Tomcat's webapps folder. Instructions for building exist.war can be found here. I highly recommend following the first set of instructions for building the WAR from the standard distribution.

Note: Be sure to rename the WAR file exist.war before placing into Tomcat's webapps folder

By default, eXist has an “admin” user with administrative privileges, and the password is blank. If you change the eXist server URL, username, or password, you can edit exist-config.xml, located in the xEAC installation folder. The default config is shown below:

<exist-config>
	<username>admin</username>
	<password/>
	<url>http://localhost:8080/exist/rest/db/</url>
</exist-config>

xEAC requires Apache Solr to power its public user interface. At the time of the publication of these instructions, the current version of Solr is 4.6. Within $TOMCAT_HOME/webapps/orbeon/WEB-INF/resources/apps/xeac, you will find a solr-home folder. Inside solr-home are two folders, 4.0 and 4.6, which refer to Solr versions. Each of these contains a conf. Conf includes all of the configuration files necessary for that particular version of Solr. The schema.xml file contains a list of fields necessary for text searching in xEAC, faceting browsing, mapping, and other such queries.

Important: In 4.6 (or different Solr version numbers), create a “data” folder and assign permissions which will grant the tomcat user write access. In Ubuntu running Tomcat7, you may simply change the owner to username tomcat7, group name tomcat7.

1. Download the latest version of Solr, e.g., http://www.apache.org/dist/lucene/solr/4.6.0/solr-4.6.0.tgz
2. Extract example/webapps/solr.war and put into $TOMCAT_HOME/webapps
3. Solr 4.3 and later: set up log4j logging, or else Solr will not start. See wiki. Pay attention to #3 especially. '-Dlog4j.configuration=/path/to/log4j.properties' may be inserted into JAVA_OPTS (in Ubuntu, edit /etc/default/tomcat7).

• Create solr.xml in $TOMCAT_HOME/conf/Catalina/localhost
• Insert the following XML fragment (substituting directory paths when necessary):

<Context docBase="/var/lib/tomcat7/webapps/solr.war" debug="0" crossContext="true" >
   <Environment name="solr/home" type="java.lang.String" value="/usr/local/projects/xeac/solr-home" override="true" />
</Context>

Within solr-home/ within the xeac project folder is solr.xml. This file contains multicore information. By default it includes the following snippet of XML:

<core name="xeac-published" instanceDir="4.6"/>

This instructs Solr to establish a core called “xeac-published” at the relative path “4.6”

Restart Tomcat, navigate to {servername}:8080/orbeon/xeac/admin/, refer to xEAC First Run