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.10.0-core.CRX.jre-1.4.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.0.5.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.0.5.GA\server\default\lib on Windows or /opt/jboss/server/default/lib on Linux.

If you are upgrading from any version older than openCRX v1.3.0 you must remove/delete the file openmdx-base.jar from the directory d:\pgm\jboss-4.0.5.GA\server\default\lib.

Copy the appropriate database JDBC driver to the directory d:\pgm\jboss-4.0.5.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.0.5.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.0.5.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.0.5.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.0.5.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.0.5.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.0.5.GA/server/default/log/
LogLevel = warning
java.LoggingMechanism = SharedDatedFileLoggingMechanism

Adapt D:/pgm/jboss-4.0.5.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.0.5.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.0.5.GA\server\default\server.log.properties

Adapt D:\pgm\jboss-4.0.5.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 security_*, i.e.

security_Credential security_Credential_N
security_Permission security_Permission_N
security_Policy security_Policy_N
security_Principal security_Principal_N
security_Privilege security_Privilege_N
security_Realm security_Realm_N
security_Role security_Role_N
security_Segment
security_Subject security_Subject_N

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.0.5.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 security_Principal p, security_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 security_Principal_N pg, security_Principal p, security_Principal_N pn, security_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></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.0.5.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.0.5.GA\bin\\..
JAVA: D:\jrockit-jdk1.5.0\bin\java
JAVA_OPTS: -Dprogram.name=run.bat -Xms200m -Xmx400m -server -Xss256k -Dorg.openmdx.compatibility.base.application.j2ee.domain=apps -Dorg.openmdx.compatibility.base.application.j
2ee.server=server1 -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol -Dorg.openmdx.log.config.filename=D:\jboss-4.0.5.GA\server\default\server.log.properties -Dsun.rmi.d
gc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
CLASSPATH: D:\jrockit-jdk1.5.0\lib\tools.jar;D:\jboss-4.0.5.GA\bin\\run.jar
===============================================================================

17:22:33,446 INFO [Server] Starting JBoss (MX MicroKernel)...
17:22:33,509 INFO [Server] Release ID: JBoss [Zion] 4.0.5.GA (build: CVSTag=Branch_4_0 date=200610162339)
17:22:33,509 INFO [Server] Home Dir: D:\jboss-4.0.5.GA
17:22:33,509 INFO [Server] Home URL: file:/D:/jboss-4.0.5.GA/
17:22:33,509 INFO [Server] Patch URL: null
17:22:33,509 INFO [Server] Server Name: default
17:22:33,509 INFO [Server] Server Home Dir: D:\jboss-4.0.5.GA\server\default
17:22:33,509 INFO [Server] Server Home URL: file:/D:/jboss-4.0.5.GA/server/default/
17:22:33,509 INFO [Server] Server Log Dir: D:\jboss-4.0.5.GA\server\default\log
17:22:33,509 INFO [Server] Server Temp Dir: D:\jboss-4.0.5.GA\server\default\tmp
17:22:33,509 INFO [Server] Root Deployment Filename: jboss-service.xml
17:22:35,712 INFO [ServerInfo] Java version: 1.5.0_06,BEA Systems, Inc.
17:22:35,712 INFO [ServerInfo] Java VM: BEA JRockit(R) R26.4.0-63-63688-1.5.0_06-20060626-2259-win-ia32,BEA Systems, Inc.
17:22:35,712 INFO [ServerInfo] OS-System: Windows XP 5.1,x86
17:22:36,962 INFO [Server] Core system initialized
17:22:39,931 INFO [WebService] Using RMI server codebase: http://DPM65:8083/
17:22:39,978 INFO [Log4jService$URLWatchTimerTask] Configuring from URL: resource:log4j.xml
17:22:44,853 INFO [ServiceEndpointManager] WebServices: jbossws-1.0.3.SP1 (date=200609291417)
17:22:45,946 INFO [Embedded] Catalina naming disabled
17:22:45,993 INFO [ClusterRuleSetFactory] Unable to find a cluster rule set in the classpath. Will load the default rule set.
17:22:45,993 INFO [ClusterRuleSetFactory] Unable to find a cluster rule set in the classpath. Will load the default rule set.
17:22:46,275 INFO [Http11AprProtocol] Initializing Coyote HTTP/1.1 on http-0.0.0.0-8080
17:22:46,275 INFO [Catalina] Initialization processed in 282 ms
17:22:46,275 INFO [StandardService] Starting service jboss.web
17:22:46,275 INFO [StandardEngine] Starting Servlet Engine: Apache Tomcat/5.5.20
17:22:46,290 INFO [StandardHost] XML validation disabled
17:22:46,306 INFO [Catalina] Server startup in 31 ms
/.../
17:22:52,337 INFO [WrapperDataSourceService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=jdbc_opencrx_CRX' to JNDI name
'java:jdbc_opencrx_CRX'
17:22:52,400 INFO [WrapperDataSourceService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=jdbc_vemag' to JNDI name
'java:jdbc_vemag'
17:22:52,462 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=ConnectionFactoryBinding,name=JmsXA' to JNDI name
'java:JmsXA'
17:22:52,540 INFO [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-console.war/
17:22:52,618 INFO [EARDeployer] Init J2EE application: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-App.ear/
17:23:00,759 INFO [EjbModule] Deploying opencrx_core_CRX_gateway_mandatory
17:23:00,868 INFO [EjbModule] Deploying opencrx_core_CRX_gateway_noOrNew
17:23:01,025 INFO [EjbModule] Deploying opencrx_core_CRX_kernel_mandatory
17:23:01,056 INFO [EjbModule] Deploying opencrx_core_CRX_security_mandatory
17:23:01,103 INFO [EjbModule] Deploying opencrx_core_CRX_ui_supports
17:23:01,150 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_gateway_mandatory' to jndi
'org.opencrx.core.CRX.local.mandatory.gateway'
17:23:01,165 INFO [ProxyFactory] Bound EJB Home 'opencrx_core_CRX_gateway_mandatory' to jndi 'org.opencrx.core.CRX.mandatory.gateway'
17:23:01,165 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_gateway_noOrNew' to jndi
'org.opencrx.core.CRX.local.noOrNew.gateway'
17:23:01,165 INFO [ProxyFactory] Bound EJB Home 'opencrx_core_CRX_gateway_noOrNew' to jndi 'org.opencrx.core.CRX.noOrNew.gateway'
17:23:01,165 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-App.ear/gateway.jar
17:23:01,212 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_kernel_mandatory' to jndi
'org.opencrx.core.CRX.local.mandatory.kernel'
17:23:01,212 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-App.ear/kernel.jar
17:23:01,228 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_security_mandatory' to jndi
'org.opencrx.core.CRX.local.mandatory.security'
17:23:01,228 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-App.ear/security.jar
17:23:01,243 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_ui_supports' to jndi 'org.opencrx.core.CRX.local.supports.ui'
17:23:01,243 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-App.ear/ui.jar
17:23:01,243 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX-gateway/client-gateway, warUrl=.../tmp/deploy/tmp57986client-gateway-
exp.war/
17:23:01,368 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX-gateway/server-gateway, warUrl=.../tmp/deploy/tmp57987server-gateway-
exp.war/
17:23:01,446 INFO [EARDeployer] Started J2EE application: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-App.ear/
17:23:01,446 INFO [EARDeployer] Init J2EE application: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-Web.ear/
17:23:04,931 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX, warUrl=.../deploy/opencrx-core-CRX-Web.ear/opencrx-core-CRX.war/
17:23:05,650 INFO [EARDeployer] Started J2EE application: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-Web.ear/
17:23:05,728 INFO [Http11AprProtocol] Starting Coyote HTTP/1.1 on http-0.0.0.0-8080
17:23:05,759 INFO [Server] JBoss (MX MicroKernel) [4.0.5.GA (build: CVSTag=Branch_4_0 date=200610162339)] Started in 32s:141ms

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 (zipped) 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.

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 as follows:

Download JavaService from http://www.opencrx.org/downloads/JavaService-bin-1.2.0.zip
Copy JavaService.exe to
D:\pgm\jboss-4.0.5.GA\server\default\JBossDefault.exe
Execute the following command (everything on a single line, i.e. no line breaks!):

Listing 8: Installing JBoss as a Windows Service

JBossDefault.exe -install JBossDefault d:\pgm\j2sdk1.5\jre\bin\server\jvm.dll -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:\pgm\jboss-4.0.5.GA\server\default\server.log.properties -Dprogram.name=run.bat -Djava.class.path=d:\pgm\j2sdk1.5\lib\tools.jar;D:\pgm\jboss-4.0.5.GA\bin\run.jar -Xms128m -Xmx500m -start org.jboss.Main

Adapt d:\pgm\j2sdk1.5 and D:\pgm\jboss-4.0.5.GA to your environment!

The above must be entered on a single line, i.e. no line breaks: JBossDefault.exe –install … org.jboss.Main

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.