openCRX is the leading open source CRM enterprise suite. openCRX is based on the openMDX application framework, an open source application framework based on the OMG's model driven architecture (MDA) standards, delivering maximum openness, standards compliance and a state-of-the-art component-based architecture.

This book describes the installation of openCRX for Apache Tomcat.

1.1 Who this book is for

The intended audience are openCRX administrators and system administrators who either want to install openCRX manually (for whatever reason) or want to install openCRX on platform not supported by our openCRX Server installer.

1.2 What do you need to understand this book

This book describes the manual installation of openCRX for Apache Tomcat. The book assumes that you are familiar with the Tomcat management and administration.

1.3 Tips, Warnings, etc.

We make use the following pictograms:

	Information provided as a “Tip” might be helpful for various reasons: time savings, risk reduction, etc.
	You should carefully read information marked with “Important”. Ignoring such information is typically not a good idea.
	Warnings should not be ignored (risk of data loss, etc.)

2 Prerequisites

As a first step select the openCRX version you want to install. Based on the published version compatibility information you can determine the appropriate versions of openMDX, Tomcat, and Java JDK:

http://www.opencrx.org/faq.htm#versioncompatibility

Write down the version numbers of the software packages you have chosen to install – this may be helpful in the future in case you require support or want to file a bug report:

openCRX v_______
openMDX v_______
Tomcat v_______
JDK v_______

2.1 JDK 5.0

Install the Sun Java JDK 5.0, available from the following site:

http://java.sun.com/javase/downloads/index_jdk5.jsp

If you deploy openCRX on Sun's JVM you might run into a problem that is mind-boggling (but specific to the Sun JVM). It's the dreaded

PermGen OutOfMemoryError

Lots of people have been struggling with this error (which is by the way not related to openCRX – any application could trigger it) and as of today we have not come across a solution other than to avoid Sun's JVM (JVMs by Oracle/BEA and IBM are – by construction – not prone to this error). Do a Google search if you want to convince yourself or drop us a line if you have a solution. But be aware that increasing the memory allocated for the permanent generation is a bogus solution – it will only postpone the problem:

It is not sufficient to have a Java Runtime Environment (JRE) only. The full-blown JDK is required to run openCRX.

Don't forget to set the environment variable JAVA_HOME. It should point to the installation directory of your JDK, e.g. D:\Java\jdk1.5.0 on Windows or /opt/Java/jdk1.5.0 on Linux.

2.2 Apache Ant

Download Ant 1.7 from http://ant.apache.org/bindownload.cgi

This guide is based on Ant v1.7.1:

http://apache.zone-h.org/ant/binaries/apache-ant-1.7.1-bin.zip (Windows)

http://apache.zone-h.org/ant/binaries/apache-ant-1.7.1-bin.tar.gz (Linux)

Install Apache Ant by expanding the downloaded file to a directory of your choice.

Don't forget to set the environment variables ANT_HOME and ANT_OPS as follows:

ANT_HOME should point to the installation directory of Ant, e.g. D:\apache-ant-1.7.1 on Windows or /opt/apache-ant-1.7.1 on Linux.
ANT_OPS should be set to -Xmx512m so that enough memory can be allocated to compile openCRX during the installation of the openCRX SDK.

2.3 Apache Tomcat

Download Tomcat 6.0.14 from http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.14/bin/

This guide is based on Tomcat v6.0.14:
http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.14/bin/apache-tomcat-6.0.14.zip (Windows)

http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.14/bin/apache-tomcat-6.0.14.tar.gz (Linux)

If you want to deploy openCRX on a Tomcat version different from Tomcat v6.0.14, you must build matching files catalina.jar and openmdx-tomcat.jar as follows:

download the desired Tomcat binary, e.g. apache-tomcat-6.0.18.zip (or apache-tomcat-6.0.18.tar.gz on Linux) and expand it to a directory of your choice, e.g. D:\apache-tomcat-6.0.18 on Windows or /opt/apache-tomcat-6.0.18 on Linux
download and install the openMDX SDK
copy the following files from the directory TOMCAT_HOME\lib to the openMDX SKD directory <SDK_Install_Dir>\openmdx-2.3.0\apache\jre-1.5\tomcat\lib (overwrite existing files):
catalina.jar, jasper.jar, jasper-el.jar, jasper-jdt.jar, jsp-api.jar, servlet-api.jar, tomcat-coyote.jar
copy the file tomcat-juli.jar from the directory TOMCAT_HOME\bin to the openMDX SKD directory <SDK_Install_Dir>\openmdx-2.3.0\apache\jre-1.5\tomcat\lib (overwrite the existing file)
open a shell an change to the directory <SDK_Install_Dir>\openmdx-2.3.0\tomcat
run ant clean and then run ant deliverables
the above will build the files catalina.jar and openmdx-tomcat.jar suitable for your Tomcat version in the directory <SDK_Install_Dir>\openmdx-2.3.0\tomcat-6\tomcat\lib

2.4 openCRX SDK

Download and install openCRX SDK: http://www.opencrx.org/sdk.htm

Installation instructions are also available from the above website.

If your platform is not supported by the openCRX SDK Installer, you can install the openCRX SDK on one of the supported platforms and then copy the required files to your target platform.

2.5 Database

Please note that you must set up the openCRX database as described in the respective openCRX database installation guide before you continue. For example, if you want to install openCRX for PostgreSQL you must first install PostgreSQL and the matching openCRX database definitions.

Database installation guides for the supported database management systems are available from http://www.opencrx.org/documents.htm

You will also need datasource configuration files. Sample data source configurations for various database management systems are contained in the openCRX SDK in the directory
<SDK_Install_Dir>\opencrx-2.3.0\core\src\connector\openmdx-2

Please remember that you will also need a JDBC driver appropriate for your database management system (please refer to the relevant DB installation guide for additional information).

Once you have successfully installed the database you are ready to continue with the Tomcat setup.

3 Installing openCRX for Tomcat

In a first step, install Apache Tomcat by expanding the downloaded file apache-tomcat-6.0.14.zip (or apache-tomcat-6.0.14.tar.gz respectively) to a directory of your choice, e.g. D:\apache-tomcat-6.0.14 on Windows or /opt/apache-tomcat-6.0.14 on Linux. For the remainder of this document we assume that TOMCAT_HOME points to the Tomcat installation directory, e.g. TOMCAT_HOME=D:\apache-tomcat-6.0.14

On Windows, avoid paths that contain blanks (e.g. the famous C:\Program File\...) as there are all kinds of pitfalls down the road...

Make sure that you added JAVA_HOME to your system environment variables as Tomcat needs the JDK to compile JSPs, e.g.
JAVA_HOME=D:\Java\jdk1.5.0 on Windows or JAVA_HOME=/opt/Java/jdk1.5.0 on Linux.

Next you must create several directories in the Tomcat directory structure:

create the directory TOMCAT_HOME\deployment-units
create the directory TOMCAT_HOME\staging-area
create the directory TOMCAT_HOME\conf\Catalina\localhost

Now we add the openMDX Lightweight Container to Tomcat by copying several files from the openCRX SDK to the Tomcat directory structure:

copy the file tomcat-juli.jar from the openCRX SDK installation directory <SDK_Install_Dir>\opencrx-2.3.0\opt\openmdx-2.3.0\jre-1.5\core\lib to the Tomcat directory TOMCAT_HOME\bin (overwrite the existing file)
copy the two files catalina.jar and openmdx-tomcat.jar from the openCRX SDK installation directory <SDK_Install_Dir>\opencrx-2.3.0\opt\openmdx-2.3.0\tomcat-6\tomcat\lib to the Tomcat directory TOMCAT_HOME\lib (overwrite the existing file catalina.jar)

Please note that the included files are version-specific, i.e. if you want to run openCRX on a Tomcat version different from Tomcat v6.0.14 you need to go back to chapter 2.3 Apache Tomcat and build matching files catalina.jar and openmdx-tomcat.jar.

Next we copy the openCRX deployment descriptors to the Tomcat directory structure and adapt them as required:

copy the files
- opencrx-core-CRX.xml
- opencrx-ical-CRX.xml
- opencrx-imap-CRX.xml
- opencrx-rest-CRX.xml and
- opencrx-vcard-CRX.xml
from the openCRX SDK installation directory <SDK_Install_Dir>\opencrx-2.3.0\core\src\connector\tomcat-6 to the Tomcat directory TOMCAT_HOME\conf\Catalina\localhost
open the copied files (with the exception of openCRX-imap-CRX.xml, which does not require any changes) so that you can adapt the realm entry of your database; all XML files contain sample entries for all supported databases, i.e. make sure that only the entry for your database is active and all the other entries are commented out; for example, if you are going to use PostgreSQL, only the respective entry should be active - you must at least adapt the following parameters:
connectionURL, connectionName and connectionPassword

Verify all the relevant information for correctness, e.g. ensure that the connection url – in particular the database name – the user name, and the password match with your installation.

A simple copy/paste of our sample files will typically not work, i.e. it is expected that you will have to adapt some of the parameters.

Next we copy the datasource configuration files to the Tomcat directory structure and adapt them as required. Sample files for various database management systems are contained in the openCRX SDK in the directory
<SDK_Install_Dir>\opencrx-2.3.0\core\src\connector\openmdx-2:

copy the appropriate directory (e.g. postgresql-8.rar) to the Tomcat directory TOMCAT_HOME\deployment-units
open the file ra.xml in the subdirectory META-INF and adapt the relevant entries to your database; you must at least adapt the values of the following properties:
- ConnectionURL
- UserName and
- Password

Don't forget to copy the appropriate JDBC driver of your database management system to the Tomcat directory TOMCAT_HOME\lib. The openCRX database installation guide describes how to download the drivers.

Next we copy the openCRX enterprise archive to the Tomcat directory structure:

copy the file opencrx-core-CRX.ear from the directory <SDK_Install_Dir>\opencrx-2.3.0\jre-1.5\core\deployment-unit to to the Tomcat directory TOMCAT_HOME\deployment-units

We also need to configure openCRX logging:

copy the file slf4j-openmdx1.jar from the openCRX SDK installation directory <SDK_Install_Dir>\opencrx-2.3.0\opt\openmdx-2.3.0\jre-1.5\log\lib to the Tomcat directory TOMCAT_HOME\lib

create the file server.log.properties with the following content in the Tomcat installation directory TOMCAT_HOME:

Listing 1: The file server.log.properties

ApplicationId = openCRX
LogFileExtension = log
LogFilePath = D:/apache-tomcat-6.0.14/logs/
LogLevel = warning
java.LoggingMechanism = SharedDatedFileLoggingMechanism
LogFormat = ${logger}|${time}|${level}|${logsource}|${host}|${thread}|${class}|${method}|${line}|${summary}|${detail}

Adapt D:/apache-tomcat-6.0.14 to your environment.

Notice the slashes (“/”) in the path – they are forward slashes on all platforms!

Next we create a batch file to start Apache Tomcat with all the appropriate JVM options:

on Windows: create the file run.bat with the following content in the Tomcat directory TOMCAT_HOME\bin:

Listing 2: The file run.bat

RMDIR /S /Q D:\apache-tomcat-6.0.14\temp

MKDIR D:\apache-tomcat-6.0.14\temp

RMDIR /S /Q D:\apache-tomcat-6.0.14\work

MKDIR D:\apache-tomcat-6.0.14\work

RMDIR /S /Q D:\apache-tomcat-6.0.14\maildir

set JAVA_HOME=D:\Java\jdk1.5.0

set JAVA_OPTS=-Xmx800M

set JAVA_OPTS=%JAVA_OPTS% -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol

set JAVA_OPTS=%JAVA_OPTS% -Dorg.openmdx.log.config.filename=D:\apache-tomcat-6.0.14\server.log.properties

set JAVA_OPTS=%JAVA_OPTS% -Dorg.opencrx.maildir=D:\apache-tomcat-6.0.14\maildir

catalina.bat run

adapt D:\apache-tomcat-6.0.14 to your environment
adapt D:\Java\jdk1.5.0 to your environment
if you are using PostgreSQL and if you set up the database as proposed by us, you can also add the following JVM option for enhanced performance:
set JAVA_OPTS=%JAVA_OPTS% -Dorg.openmdx.persistence.jdbc.useLikeForOidMatching=false

on Linux: create the file run.sh with the following content in the Tomcat directory TOMCAT_HOME\bin:

Listing 3: The file run.sh

#!/bin/sh

export CATALINA_HOME=/opt/apache-tomcat-6.0.14
export JAVA_HOME=/opt/Java/jdk1.5.0
export JAVA_OPTS="-Xmx800M -XX:MaxPermSize=128m -Dtomcat.server.port=8005 -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol -Dorg.openmdx.log.config.filename=$CATALINA_HOME/server.log.properties -Dorg.opencrx.maildir=$CATALINA_HOME/maildir"
cd $CATALINA_HOME
rm -Rf temp
mkdir temp
rm -Rf work
./bin/catalina.sh run

adapt /opt/apache-tomcat-6.0.14 to your environment
adapt /opt/Java/jdk1.5.0 to your environment
if you are using PostgreSQL and if you set up the database as proposed by us, you can also add the following JVM option for enhanced performance:
-Dorg.openmdx.persistence.jdbc.useLikeForOidMatching=false

Finally, we have to make a few changes to Tomcat's server.xml:

open the file TOMCAT_HOME\conf\server.xml
look for the connector definition <Connector port="8080" protocol="HTTP/1.1" and add the option URIEncoding="UTF-8" so that the connector definition looks as shown below:

Listing 4: Connector definition in server.xml

look for the engine definition <Engine name="Catalina" defaultHost="localhost" and change it as shown below:

Listing 5: Engine definition in server.xml

<Engine name="Catalina"
defaultHost="localhost"
className="org.openmdx.tomcat.application.container.ExtendedEngine">

deploymentDirectory="deployment-units"
stagingDirectory="staging-area"

in the end your server.xml will look as follows (all comments removed):

Listing 6: server.xml

<?xml version='1.0' encoding='utf-8'?>
<Server port="8005" shutdown="SHUTDOWN">
<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
<Listener className="org.apache.catalina.core.JasperListener" />
<Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />
<Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />

<GlobalNamingResources>
<Resource name="UserDatabase" auth="Container"
type="org.apache.catalina.UserDatabase"
description="User database that can be updated and saved"
factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
pathname="conf/tomcat-users.xml" />
</GlobalNamingResources>

<Service name="Catalina">
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
URIEncoding="UTF-8"
/>

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

<Engine
name="Catalina"
defaultHost="localhost"
className="org.openmdx.tomcat.application.container.ExtendedEngine">

deploymentDirectory="deployment-units"
stagingDirectory="staging-area"

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase"/>

<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
</Host>

</Engine>
</Service>
</Server>

4 Configuring Container Security

As a final step you must activate security for the openCRX application.

We recommend that you stay with the file-based authentication for all users until you have finished installing openCRX. You avoid situations where you have to trouble-shoot multiple issues at the same time...

Add users and roles to tomcat-users.xml:

open the file TOMCAT_HOME\conf\tomcat-users.xml and add users and roles as follows:

Listing 7: The file tomcat-users.xml

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
<role rolename="OpenCrxAdministrator"/>
<role rolename="OpenCrxUser"/>
<role rolename="OpenCrxRoot"/>
<role rolename="manager"/>
<user username="admin-Root" password="opencrx" roles="OpenCrxRoot"/>
<user username="admin-Standard" password="opencrx" roles="OpenCrxAdministrator,OpenCrxUser"/>
<user username="system" password="manager99" roles="manager"/>
<user username="guest" password="opencrx" roles="OpenCrxUser"/>
</tomcat-users>

adapt the passwords to your liking

It is strongly recommended that you stay with the file-based authentication for the user admin-Root. This simplifies the openCRX bootstrapping.

5 Starting Tomcat

You are now ready to start Tomcat. Open a command shell and start run.bat (or run.sh on Linux). You should verify whether the start options match the ones described earlier:

Listing 8: Tomcat console output

[13:45:15.54]D:\apache-tomcat-6.0.14\bin>run

[13:45:16.29]D:\apache-tomcat-6.0.14\bin>RMDIR /S /Q D:\apache-tomcat-6.0.14\temp

[13:45:16.29]D:\apache-tomcat-6.0.14\bin>MKDIR D:\apache-tomcat-6.0.14\temp

[13:45:16.29]D:\apache-tomcat-6.0.14\bin>RMDIR /S /Q D:\apache-tomcat-6.0.14\work

[13:45:16.48]D:\apache-tomcat-6.0.14\bin>MKDIR D:\apache-tomcat-6.0.14\work

[13:45:16.48]D:\apache-tomcat-6.0.14\bin>RMDIR /S /Q D:\apache-tomcat-6.0.14\maildir
The system cannot find the file specified.

[13:45:16.48]D:\apache-tomcat-6.0.14\bin>set JAVA_HOME=D:\Java\jdk1.5.0

[13:45:16.51]D:\apache-tomcat-6.0.14\bin>set JAVA_OPTS=-Xmx800M
-Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol
-Dorg.openmdx.log.config.filename=D:\apache-tomcat-6.0.14\server.log.properties
-Dorg.opencrx.maildir=D:\apache-tomcat-6.0.14\maildir
-Dorg.openmdx.persistence.jdbc.useLikeForOidMatching=false

[13:45:16.53]D:\apache-tomcat-6.0.14\bin>catalina.bat run
Using CATALINA_BASE: D:\apache-tomcat-6.0.14
Using CATALINA_HOME: D:\apache-tomcat-6.0.14
Using CATALINA_TMPDIR: D:\apache-tomcat-6.0.14\temp
Using JRE_HOME: D:\Java\jdk1.5.0
Dec 19, 2008 1:45:17 PM org.apache.catalina.core.AprLifecycleListener init
INFO: The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the
java.library.path: D:\Java\jdk1.5.0\bin
Dec 19, 2008 1:45:17 PM org.apache.coyote.http11.Http11Protocol init
INFO: Initializing Coyote HTTP/1.1 on http-8080
Dec 19, 2008 1:45:17 PM org.apache.catalina.startup.Catalina load
INFO: Initialization processed in 470 ms
Dec 19, 2008 1:45:17 PM org.apache.catalina.core.StandardService start
INFO: Starting service Catalina
Dec 19, 2008 1:45:17 PM org.openmdx.tomcat.application.container.ExtendedEngine start
INFO: Starting embedded EJB container for engine 'Catalina': openMDX Lightweight Container/2.3.0
Dec 19, 2008 1:45:17 PM org.openmdx.tomcat.application.container.ExtendedEngine start
INFO: Process 0 pending resource adapter deployments from 'D:\apache-tomcat-6.0.14\staging-area'
Dec 19, 2008 1:45:17 PM org.openmdx.tomcat.application.container.ExtendedEngine start
INFO: Process 0 pending enterprise applications deplpyments from 'D:\apache-tomcat-6.0.14\staging-area'
Dec 19, 2008 1:45:17 PM org.openmdx.tomcat.application.container.ExtendedEngine start
INFO: Start 1 resource adapters from 'D:\apache-tomcat-6.0.14\deployment-units'
Dec 19, 2008 1:45:17 PM org.openmdx.tomcat.application.container.ExtendedEngine log
INFO: Resource adapter 'file:/D:/apache-tomcat-6.0.14/deployment-units/postgresql-8.rar/' was successfully deployed
Dec 19, 2008 1:45:17 PM org.openmdx.tomcat.application.container.ExtendedEngine start
INFO: Start 1 enterprise applications from 'D:\apache-tomcat-6.0.14\deployment-units'
Dec 19, 2008 1:45:37 PM org.openmdx.tomcat.application.container.ExtendedEngine log
INFO: Enterprise application 'file:/D:/apache-tomcat-6.0.14/deployment-units/opencrx-core-CRX.ear' was successfully deployed
Dec 19, 2008 1:45:38 PM org.apache.catalina.core.StandardEngine start
INFO: Starting Servlet Engine: Apache Tomcat/6.0.14
Dec 19, 2008 1:45:44 PM org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8080
Dec 19, 2008 1:45:44 PM org.apache.jk.common.ChannelSocket init
INFO: JK: ajp13 listening on /0.0.0.0:8009
Dec 19, 2008 1:45:44 PM org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/31 config=null
Dec 19, 2008 1:45:44 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 27385 ms

Now you are ready to continue with the openCRX QuickStart Guide.

6 Next Steps

Now that you have successfully deployed openCRX on your application server you can continue with the openCRX QuickStart guide.