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_______

Next you need to download the following software packages:

Download JBoss from http://labs.jboss.com/portal/jbossas/download
Download openMDX from http://sourceforge.net/project/showfiles.php?group_id=75132
Download openCRX from here http://www.opencrx.org/downloads.htm
You must download the opencrx-core distribution (e.g. opencrx-1.11.0-core.CRX.jre-1.5.zip).

Please note that installation of the appropriate Java Platform is not covered by this manual (i.e. it is assumed that the appropriate JDK is already installed on your system).

More information about Java is available from http://java.sun.com/

JDK 1.5 is available from http://java.sun.com/j2se/1.5.0/download.jsp

Please note that you also must install the 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. A list of all the database installation guides is available at http://www.opencrx.org/documents.htm

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 or any other Posix OS.

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

JAVA_HOME is required by JBoss in order to compile JSPs.

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 contained in the openMDX distribution 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-App.ear contained in the openCRX distribution (please refer to the core/README for instructions on how to assemble this 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

Copy the file opencrx-core-CRX-web.ear contained in the openCRX distribution (please refer to the core/README for instructions on how to assemble this 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.

You can also open opencrx-core-CRX-web.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, e.g. copy the file jdbc-opencrx-CRX-mysql-ds.xml (if you use openCRX with MySQL) contained in the file opencrx-core.jboss-3-connector.zip of the openCRX distribution to the directory d:\pgm\jboss-4.2.1.GA\server\default\deploy on Windows or /opt/jboss/server/default/deploy on Linux.

Verify that database name, user, and password match with your installation.
Create the file server.log.properties in the directory

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

with the following content:

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 the line

set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m

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

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 -Xmx512m"
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 either configure the file-based UsersRolesLoginModule or the database-based DatabaseServerLoginModule.

4.1 Configuring LoginModule

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

OOCSE1_Credential
OOCSE1_Permission
OOCSE1_Policy
OOCSE1_Principal
OOCSE1_Privilege
OOCSE1_Realm
OOCSE1_Role
OOCSE1_Segment
OOCSE1_Subject

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.0.5.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 [EARDeployer] Init J2EE application: file:/D:/jboss-4.2.1.GA/server/default/deploy/opencrx-core-CRX-App.ear
13:32:52,971 INFO [EjbModule] Deploying opencrx_core_CRX_gateway_mandatory
13:32:53,017 INFO [EjbModule] Deploying opencrx_core_CRX_gateway_noOrNew
13:32:53,298 INFO [EjbModule] Deploying opencrx_core_CRX_kernel_mandatory
13:32:53,360 INFO [EjbModule] Deploying opencrx_core_CRX_security_mandatory
13:32:53,454 INFO [EjbModule] Deploying opencrx_core_CRX_ui_supports
13:32:53,501 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_gateway_mandatory' to jndi
'org.opencrx.core.CRX.local.mandatory.gateway'
13:32:53,532 INFO [ProxyFactory] Bound EJB Home 'opencrx_core_CRX_gateway_mandatory' to jndi 'org.opencrx.core.CRX.mandatory.gateway'
13:32:53,547 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_gateway_noOrNew' to
jndi 'org.opencrx.core.CRX.local.noOrNew.gateway'
13:32:53,547 INFO [ProxyFactory] Bound EJB Home 'opencrx_core_CRX_gateway_noOrNew' to jndi 'org.opencrx.core.CRX.noOrNew.gateway'
13:32:53,547 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.2.1.GA/server/default/tmp/deploy/tmp31572opencrx-core-CRX-App.ear-contents/gateway.jar
13:32:53,625 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_kernel_mandatory' to
jndi 'org.opencrx.core.CRX.local.mandatory.kernel'
13:32:53,625 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.2.1.GA/server/default/tmp/deploy/tmp31572opencrx-core-CRX-App.ear-contents/kernel.jar
13:32:53,657 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_security_mandatory' to
jndi 'org.opencrx.core.CRX.local.mandatory.security'
13:32:53,657 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.2.1.GA/server/default/tmp/deploy/tmp31572opencrx-core-CRX-App.ear-contents/security.jar
13:32:53,703 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_ui_supports' to jndi 'org.opencrx.core.CRX.local.supports.ui'
13:32:53,703 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.2.1.GA/server/default/tmp/deploy/tmp31572opencrx-core-CRX-App.ear-contents/ui.jar
13:32:53,766 INFO [EARDeployer] Started J2EE application: file:/D:/jboss-4.2.1.GA/server/default/deploy/opencrx-core-CRX-App.ear
13:32:53,766 INFO [EARDeployer] Init J2EE application: file:/D:/jboss-4.2.1.GA/server/default/deploy/opencrx-core-CRX-Web.ear/
13:33:13,548 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX-gateway/client-gateway,
warUrl=.../tmp/deploy/tmp31573client-gateway-exp.war/
13:33:13,688 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX, warUrl=.../deploy/opencrx-core-CRX-Web.ear/opencrx-core-CRX.war/
13:33:14,499 INFO [[/opencrx-core-CRX]] [CompressingFilter/1.6.4] CompressingFilter has initialized
13:33:14,608 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX-gateway/server-gateway,
warUrl=.../tmp/deploy/tmp31590server-gateway-exp.war/
13:33:14,966 INFO [EARDeployer] Started J2EE application: file:/D:/jboss-4.2.1.GA/server/default/deploy/opencrx-core-CRX-Web.ear/
13:33:15,294 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 Performance

Make sure that your servlet container / application server sends compressed pages to browsers; with JBoss, for example, add/set the Tomcat option compression="on" in the file server.xml (details on the http connector reference page of the Apache-Jakarta-Project) - compressed pages are much smaller than uncompressed pages (typically by a factor of 10), thereby reducing the load on your network and improving the experience of users connected to the openCRX server with "less than optimal" bandwidth specs.
Based on our observations, you can speed up the deployment of openCRX on JBoss substantially by expanding the EARs (factor of 2).

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 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 following command:

Listing 8: Installing JBoss as a Windows Service

service.bat install

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

8 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 the jboss_init_redhat.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 like:

Listing 9: 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 10: 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 11: 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 12: 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”

9 Next Steps

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