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

This book describes the installation of openCRX for the Jboss application server.

1.1 Who this book is for

The intended audience are openCRX administrators and application server system administrators.

1.2 What do you need to understand this book

This book describes the installation of openCRX for JBoss. The book assumes that you are familiar with JBoss deployment concepts 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, JBoss, and Java JDK/JRE:

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_______
JBoss v_______
JDK v_______

2.1 JDK 5.0

Install either the Sun Java JDK 5.0 or the BEA JRockit JDK 5.0 appropriate for your platform. The JDKs are available from the following sites:

Sun JDK 5.0:
http://java.sun.com/javase/downloads/index_jdk5.jsp

BEA JRockit JDK 5.0:
http://commerce.bea.com/products/weblogicjrockit/5.0/jr_50.jsp

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

2.2 JBoss

Download JBoss from http://labs.jboss.com/portal/jbossas/download

2.3 openmdx-kernel.jar

Download and install openCRX SDK – available from http://www.opencrx.org/sdk.htm
Once installed, you will find the file openmdx-kernel-jar in the directory <SDK_Install_Dir>\opencrx-2.0.0\opt\openmdx-2.0.0\jre-1.5\core\lib

2.4 openCRX EARs

Either you can build the EARs from scratch with the openCRX SDK, or you can get pre-built EARs as follows: Download and install openCRX Server – available from http://www.opencrx.org/server.htm
Once installed, you will find the pre-built openCRX EARs in the directory <Server_Install_Dir>\apache-tomcat-6\deployment-units

openCRX/core EAR:
opencrx-core-CRX.ear

openCRX/groupware EAR:
opencrx-groupware-CRX.ear

openCRX/store EAR:
opencrx-store-CRX.ear

Only opencrx-core-CRX.ear is required to run openCRX; the other EARs are optional and only required if you want to activate the contained functionality.

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 MySQL you must first install MySQL 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 a datasource configuration file. Sample data source configurations for various database management systems are contained in the openCRX SDK in the directory
<SDK_Install_Dir>\opencrx-2.0.0\core\src\connector\jboss-3

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 JBoss setup.

3 Installing openCRX for JBoss

In a first step you must install JBoss by extracting the delivered JBoss distribution to your program directory, e.g. d:\pgm\jboss-4.2.1.GA on Windows or /opt/jboss on Linux.

Make sure that you add JAVA_HOME to your system environment variables as JBoss needs the JDK to compile JSPs, e.g.
JAVA_HOME=D:\pgm\j2sdk1.5 on Windows or JAVA_HOME=/usr/java/j2sdk1.5 on Linux.

Next you must deploy openCRX to JBoss. You do this by copying several files to the JBoss deploy directory:

Copy the file openmdx-kernel.jar to the directory d:\pgm\jboss-4.2.1.GA\server\default\lib on Windows or /opt/jboss/server/default/lib on Linux.
Copy the appropriate database JDBC driver to the directory d:\pgm\jboss-4.2.1.GA\server\default\lib. The openCRX database installation manual describes how to download the drivers.
Copy the file opencrx-core-CRX.ear to the JBoss deploy directory d:\pgm\jboss-4.2.1.GA\server\default\deploy on Windows or /opt/jboss/server/default/deploy on Linux.

Do NOT deploy any other openCRX EARs (e.g. groupware) before having completed the setup based on the openCRX QuickStart guide.

Optionally, you can also open opencrx-core-CRX.ear with a ZIP utility and extract the content to the directory

d:\pgm\jboss-4.2.1.GA\server\default\deploy\opencrx-core-CRX-web.ear or /opt/jboss/server/default/deploy/opencrx-core-CRX-web-ear

If you want to edit the content of the file opencrx-core-CRX.war without the zip/unzip roundtrip you can also extract the content with a ZIP utility.

Install the datasource configuration file appropriate for your DB, e.g. copy the file jdbc-opencrx-CRX-mysql-ds.xml (if you use openCRX with MySQL) to the directory
d:\pgm\jboss-4.2.1.GA\server\default\deploy on Windows or /opt/jboss/server/default/deploy on Linux.

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.

Create the file server.log.properties with the following content in

d:\pgm\jboss-4.2.1.GA\server\default\on Windows or /opt/jboss/server/default/ on Linux

Listing 1: The file server.log.properties

ApplicationId = openCRX
LogFileExtension = log
LogFilePath = D:/pgm/jboss-4.2.1.GA/server/default/log/
LogLevel = warning
java.LoggingMechanism = SharedDatedFileLoggingMechanism

Adapt D:/pgm/jboss-4.2.1.GA to your environment!

Next you must set a few Java VM options which are required for the openMDX application framework.

On Windows add the following lines to d:\pgm\jboss-4.2.1.GA\bin\run.bat after the lines indicated below. Also uncomment and adapt the line

set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx800m

This gives more memory to the Java VM (and depending on your environment you may want to increase the value of the option Xmx).

Listing 2: Java VM options required for openMDX on Windows

rem Sun JVM memory allocation pool parameters. Uncomment and modify as appropriate.
set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx800m

rem Setup openMDX-specific properties
set JAVA_OPTS=%JAVA_OPTS% -Dorg.openmdx.compatibility.base.application.j2ee.domain=apps
set JAVA_OPTS=%JAVA_OPTS% -Dorg.openmdx.compatibility.base.application.j2ee.server=server1
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:\pgm\jboss-4.2.1.GA\server\default\server.log.properties

Adapt D:\pgm\jboss-4.2.1.GA\server\default\server.log.properties to your environment and make sure that there are no line breaks in the set commands. Each -D options is of the form -Dname=value and must be on a single line.

On Linux add the following lines to /opt/jboss/bin/run.conf towards the end of the file.

Listing 3: Java VM options required for openMDX on Linux

rem Setup openMDX-specific properties
JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx800m"
JAVA_OPTS="$JAVA_OPTS -Dorg.openmdx.compatibility.base.application.j2ee.domain=apps"
JAVA_OPTS="$JAVA_OPTS -Dorg.openmdx.compatibility.base.application.j2ee.server=server1"
JAVA_OPTS="$JAVA_OPTS -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol"
JAVA_OPTS="$JAVA_OPTS -Dorg.openmdx.log.config.filename=/opt/jboss/server/default/server.log.properties"

Adapt /opt/jboss/server/default/server.log.properties to your environment and make sure that there are no line breaks in the set commands. Each -D options is of the form -Dname=value and must be on a single line.

4 Configuring Security

As a final step you must activate security for the openCRX application. You can configure the file-based UsersRolesLoginModule and/or the database-based DatabaseServerLoginModule.

4.1 Configuring LoginModule

openCRX stores security information in the database tables OOCSE1_*, i.e.

OOCSE1_Authenticationcontext
OOCSE1_Credential
OOCSE1_Permission
OOCSE1_Policy
OOCSE1_Principal
OOCSE1_Privilege
OOCSE1_Realm
OOCSE1_Role
OOCSE1_Segment
OOCSE1_Subject

OOCSE1_Authenticationcontext_
OOCSE1_Credential_
OOCSE1_Permission_
OOCSE1_Policy_
OOCSE1_Principal_
OOCSE1_Privilege_
OOCSE1_Realm_
OOCSE1_Role_
OOCSE1_Segment_
OOCSE1_Subject_

JBoss can be enabled to access these tables by configuring a database login module. This way users can be managed in openCRX and are immediately available as JBoss logins.

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

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...

Activate JAAS based authentication by adding the following configuration entries for the openCRX servlet to the JBoss configuration file

d:\pgm\jboss-4.2.1.GA\server\default\conf\login_config.xml
(login-config.xml on Unix platforms)

Listing 4: JBoss configuration for JAAS based authentication

<application-policy name="opencrx-core-CRX">
<authentication>
<login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag="sufficient">
<module-option name="dsJndiName">java:/jdbc_opencrx_CRX</module-option>
<module-option name="principalsQuery">SELECT c.passwd FROM OOCSE1_PRINCIPAL p, OOCSE1_CREDENTIAL c WHERE (p.object_id LIKE 'principal/CRX/Root/Default/%') AND (p.credential = c.object_id) AND (p.name = ?)</module-option>
<module-option name="rolesQuery">SELECT r.name, 'Roles' FROM OOCSE1_PRINCIPAL_ pg, OOCSE1_PRINCIPAL p, OOCSE1_PRINCIPAL_ pn, OOCSE1_ROLE r WHERE (p.object_id = pn.object_id) AND (pn.is_member_of = pg.object_id) AND (pg.granted_role = r.object_id) AND (p.object_id LIKE 'principal/CRX/Root/Default/%') AND (p.name = ?)</module-option>
<module-option name="ignorePasswordCase">true</module-option>
<module-option name="hashCharset">UTF-8</module-option>
<module-option name="hashEncoding">base64</module-option>
<module-option name="hashAlgorithm">MD5</module-option>
</login-module>
<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="sufficient" >
<module-option name="usersProperties">users.properties</module-option>
<module-option name="rolesProperties">roles.properties</module-option>
</login-module>
</authentication>
</application-policy>

The settings above enable both file-based authentication and database-based authentication.

Next you need to create the files users.properties and roles.properties in the directory d:\pgm\jboss-4.2.1.GA\server\default\conf (Windows) or /opt/jboss/server/default/conf (Linux).

Listing 5: File users.properties with syntax user=password

admin-Root=rootSecret
admin-Standard=adminSecret
guest=guest

Listing 6: File roles.properties with syntax user.Roles=role1,role2

admin-Root.Roles=OpenCrxRoot
admin-Standard.Roles=OpenCrxAdministrator
guest.Roles=OpenCrxUser

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

5 Starting JBoss

You are now ready to start JBoss. Open a command shell and start d:\pgm\jboss-4.2.1.GA\bin\run.bat. You should verify whether the start options match the ones described earlier:

Listing 7: JBoss console output

===============================================================================
JBoss Bootstrap Environment
JBOSS_HOME: D:\jboss-4.2.1.GA
JAVA: D:\jdk1.5.0\bin\java
JAVA_OPTS: -Dprogram.name=run.bat -server -Xms128m -Xmx1024m -Dorg.openmdx.compatibility.base.application.j2ee.domain=apps -Dorg.openmdx.compatibility.base.application.j2ee.server=server1 -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol -Dorg.openmdx.log.config.filename=D:\jboss-4.2.
.GA\server\default\server.log.properties -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
CLASSPATH: D:\jdk1.5.0\lib\tools.jar;D:\jboss-4.2.1.GA\bin\run.jar
===============================================================================

13:32:04,568 INFO [Server] Starting JBoss (MX MicroKernel)...
13:32:04,568 INFO [Server] Release ID: JBoss [Trinity] 4.2.1.GA (build: SVNTag=JBoss_4_2_1_GA date=200707131605)
13:32:04,583 INFO [Server] Home Dir: D:\jboss-4.2.1.GA
13:32:04,583 INFO [Server] Home URL: file:/D:/jboss-4.2.1.GA/
13:32:04,583 INFO [Server] Patch URL: null
13:32:04,583 INFO [Server] Server Name: default
13:32:04,583 INFO [Server] Server Home Dir: D:\jboss-4.2.1.GA\server\default
13:32:04,583 INFO [Server] Server Home URL: file:/D:/jboss-4.2.1.GA/server/default/
13:32:04,583 INFO [Server] Server Log Dir: D:\jboss-4.2.1.GA\server\default\log
13:32:04,583 INFO [Server] Server Temp Dir: D:\jboss-4.2.1.GA\server\default\tmp
13:32:04,583 INFO [Server] Root Deployment Filename: jboss-service.xml
13:32:05,160 INFO [ServerInfo] Java version: 1.5.0_10,Sun Microsystems Inc.
13:32:05,160 INFO [ServerInfo] Java VM: Java HotSpot(TM) Server VM 1.5.0_10-b03,Sun Microsystems Inc.
13:32:05,160 INFO [ServerInfo] OS-System: Windows XP 5.1,x86
13:32:05,753 INFO [Server] Core system initialized
13:32:10,258 INFO [WebService] Using RMI server codebase: http://127.0.0.1:8083/
13:32:10,273 INFO [Log4jService$URLWatchTimerTask] Configuring from URL: resource:jboss-log4j.xml
.....
.....
13:32:24,506 INFO [testQueue] Bound to JNDI name: queue/testQueue
13:32:24,568 INFO [UILServerILService] JBossMQ UIL service available at : /127.0.0.1:8093
13:32:24,630 INFO [DLQ] Bound to JNDI name: queue/DLQ
13:32:24,833 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=jdbc_opencrx_CRX' to
JNDI name 'java:jdbc_opencrx_CRX'
13:32:24,927 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=ConnectionFactoryBinding,name=JmsXA' to
JNDI name 'java:JmsXA'
13:32:24,958 INFO [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-console.war/
13:32:27,499 INFO INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
13:33:15,309 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
13:33:15,325 INFO [Server] JBoss (MX MicroKernel) [4.2.1.GA (build: SVNTag=JBoss_4_2_1_GA date=200707131605)] Started in 1m:10s:726ms

Now you are ready to continue with the openCRX QuickStart Guide or you can Install openCRX as Windows Service.

6 Additional JBoss Settings

6.1 Automatically delete the Directories tmp and work

To ensure a clean and consistent startup environment it is recommended to delete the directories

d:\pgm\jboss-4.2.1.GA\server\default\tmp and
d:\pgm\jboss-4.2.1.GA\server\default\work (on Windows)

/opt/jboss/server/default/tmp and
/opt/jboss/server/default/work (on Linux).

before you (re)start JBoss.

Add some statements to the file run.bat (Windows) or run.sh (Linux) to automatically delete these directories upon starting JBoss.

On Windows, for example, you could add something along the lines of

RMDIR /S /Q D:\jboss-4.2.1.GA\server\default\tmp
RMDIR /S /Q D:\jboss-4.2.1.GA\server\default\work

to the beginning of run.bat

6.2 UTF-8 Support

For full UTF-8 support it is necessary to add/set the Tomcat option URIEncoding="UTF-8" in the file server.xml (details on the http connector reference page of the Apache-Jakarta-Project). Full UTF-8 support is for example required if you want to search for UTF-8 encoded characters.

6.3 Port Binding and Security

Newer versions of JBoss (4.2 and newer) bind to localhost only by default (it used to be global 0.0.0.0). You can get this same behavior by starting JBoss with -b 0.0.0.0.

If you look in the readme.html in your JBoss distribution there is a link with info on how to secure JBoss once you bind to 0.0.0.0. Alternatively, you can fiddle with the Tomcat options in the file server.xml.

7 openCRX as a Windows Service / Linux daemon

7.1 Install openCRX as a Windows Service

If you want to install JBoss / openCRX on a Windows platform as a Windows service you can do this by following instructions from the JBoss Wiki at http://wiki.jboss.org/wiki/Wiki.jsp?page=RunJBossAsAServiceOnWindows:

Download JBoss Web Server 2.0.1.GA from http://labs.jboss.com/jbossweb/downloads
Unzip jboss-native-2.0.1xxx.zip to your JBoss Directory
D:\pgm\jboss-4.2.1.GA\
Open a DOS shell, navigate to D:\pgm\jboss-4.2.1.GA\bin and then execute the command

service.bat install

Adapt d:\pgm\jboss-4.2.1.GA to your environment!

7.2 Install openCRX as daemon on Linux

This section (provided by Seah Hong Yee) is devoted to the automatic start up of jboss services during the startup phase of a server. It also simplifies manual jboss startup with the use a of System V init script. The following configuration has been tested on Mandrake Linux 10.1 and SuSe Linux Enterprise Server 9. Based on the particular distribution at hand there might be some minor differences in init scripts and configuration, but the following guide should work with RHEL, CentOS, WhiteBox and Fedora.

In the directory $JBOSS_HOME/bin there should be two init scripts:

jboss_init_redhat.sh
jboss_init_suse.sh

If you are using Mandrake/Mandriva, RHEL, CentOS, WhiteBox or Fedora:

Copy jboss_init_redhat.sh into /etc/init.d and rename it to jboss.
Edit the script and adapt the parameters: JBOSS_HOME and JAVAPTH
Although not strictly necessary, you might want to include an entry like:

Listing 8: Declare location of jdk

export PATH=/usr/java/j2sdk1.5.0_06/bin

(/usr/java/j2sdk1.5.0_06/ being your jdk path, adapt it to your environment)

At the top of the script there is an entry resembling the following one:

Listing 9: Declare startup sequence

# chkconfig: 3 87 20

The second set of digits represents the order sequence of the service startup. Make sure the number is larger than your database startup. Typically postgresql starts with the sequence number of 85, so I have my jboss startup with the sequence of 87

Type the commands

Listing 10: Add JBoss to config

# chkconfig --add jboss
# chkconfig jboss on

From now on jboss should startup automatically after reboot, or you can do it manually with service jboss restart.

If you are using Suse Linux:

Copy the jboss_init_suse.sh script into /etc/init.d and rename it to jboss.
Edit the script and adapt the following parameters: JBOSS_HOME and JAVAPTH
Although not strictly necessary, you might want to include an entry near the top of the script like:

Listing 11: Declare location of jdk

export PATH=/usr/java/j2sdk1.5.0_06/bin

(/usr/java/j2sdk1.5.0_06/ being your jdk path, adapt it to your environment)

Type the command “inserv jboss”
Go into directory /usr/sbin and create a symbolic link with
“ln -s /etc/init.d/jboss rcjboss”
Execute the command “chkconfig jboss on”
You should now be able to start jboss with the command “rcjboss start”

8 Next Steps

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