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://www.jboss.org/products/jbossas/downloads
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.9.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 database 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.3SP1 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.3SP1\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.3SP1\server\default\lib.

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

Adapt D:/pgm/jboss-4.0.3SP1 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.3SP1\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.3SP1\server\default\server.log.properties
set JAVA_OPTS=%JAVA_OPTS% -Dmail.SSLSocketFactory.class=org.opencrx.ssl.DefaultSSLSocketFactory

Adapt D:\pgm\jboss-4.0.3SP1\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"
JAVA_OPTS="$JAVA_OPTS -Dmail.SSLSocketFactory.class=org.opencrx.ssl.DefaultSSLSocketFactory"

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_Policy, security_Principal, security_Credential, security_Subject and security_Role. 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.3SP1\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_rid = 'principal/CRX/Root/Default') AND (p.p$$credential__rid = c.object_rid) AND (p.p$$credential__oid = c.object_oid) AND (p.object_idx = 0) AND (p.object_oid = ?)</module-option>
      <module-option name="rolesQuery">SELECT pg.p$$granted_role__oid, 'Roles' FROM security_Principal pg, security_Principal p WHERE (pg.object_rid = p.p$$is_member_of__rid) AND (pg.object_oid = p.p$$is_member_of__oid) AND (p.object_rid = 'principal/CRX/Root/Default') AND (p.object_oid = ?)</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>

These settings enable both file-based authentication and database-based authentication.

If you use PostgreSQL you might have to use the following settings (column names containing $$ must be quoted).

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

Listing 5: JBoss configuration for JAAS based authentication w/ PostgreSQL

<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_rid = 'principal/CRX/Root/Default') AND (p."p$$credential__rid" = c.object_rid) AND (p."p$$credential__oid" = c.object_oid) AND (p.object_idx = 0) AND (p.object_oid = ?)</module-option>
      <module-option name="rolesQuery">SELECT pg."p$$granted_role__oid", 'Roles' FROM security_Principal pg, security_Principal p WHERE (pg.object_rid = p."p$$is_member_of__rid") AND (pg.object_oid = p."p$$is_member_of__oid") AND (p.object_rid = 'principal/CRX/Root/Default') AND (p.object_oid = ?)</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>

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

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

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

Listing 7: 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.3SP1\bin\run.bat. You should verify whether the start options match the ones described earlier:

Listing 8: JBoss console output

[16:48:51.58]D:\jboss-4.0.3SP1\bin>run
===============================================================================
.
JBoss Bootstrap Environment
.
JBOSS_HOME: D:\jboss-4.0.3SP1\bin\\..
.
JAVA: D:\jdk1.5.0\bin\java
.
JAVA_OPTS:
-Dprogram.name=run.bat -Xms128m -Xmx512m
-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.0.3SP1\server\default\server.log.properties
-Dmail.SSLSocketFactory.class=org.opencrx.ssl.DefaultSSLSocketFactory
.
CLASSPATH: D:\jdk1.5.0\lib\tools.jar;D:\jboss-4.0.3SP1\bin\\run.jar
.
===============================================================================
.
16:49:02,033 INFO [Server] Starting JBoss (MX MicroKernel)...
16:49:02,033 INFO [Server] Release ID: JBoss [Zion] 4.0.3SP1 (build: CVSTag=JBoss_4_0_3_SP1 date=200510231054)
16:49:02,049 INFO [Server] Home Dir: D:\jboss-4.0.3SP1
16:49:02,049 INFO [Server] Home URL: file:/D:/jboss-4.0.3SP1/
16:49:02,049 INFO [Server] Patch URL: null
16:49:02,049 INFO [Server] Server Name: default
16:49:02,049 INFO [Server] Server Home Dir: D:\jboss-4.0.3SP1\server\default
16:49:02,049 INFO [Server] Server Home URL: file:/D:/jboss-4.0.3SP1/server/default/
16:49:02,049 INFO [Server] Server Temp Dir: D:\jboss-4.0.3SP1\server\default\tmp
16:49:02,049 INFO [Server] Root Deployment Filename: jboss-service.xml
16:49:10,470 INFO [ServerInfo] Java version: 1.5.0_06,Sun Microsystems Inc.
16:49:10,470 INFO [ServerInfo] Java VM: Java HotSpot(TM) Client VM 1.5.0_06-b05,Sun Microsystems Inc.
16:49:10,470 INFO [ServerInfo] OS-System: Windows XP 5.1,x86
16:49:11,455 INFO [Server] Core system initialized
16:49:13,408 INFO [WebService] Using RMI server codebase: http://DPM70:8083/
16:49:13,424 INFO [Log4jService$URLWatchTimerTask] Configuring from URL: resource:log4j.xml
16:49:16,861 INFO [NamingService] Started jndi bootstrap jnpPort=1099, rmiPort=1098, backlog=50, bindAddress=/0.0.0.0,
                   Client SocketFactory=null, Server SocketFactory=org.jboss.net.sockets.DefaultSocketFactory@ad093076
16:49:20,720 INFO [Embedded] Catalina naming disabled
16:49:21,080 INFO [Http11Protocol] Initializing Coyote HTTP/1.1 on http-0.0.0.0-8080
16:49:21,080 INFO [Catalina] Initialization processed in 328 ms
16:49:21,080 INFO [StandardService] Starting service jboss.web
16:49:21,080 INFO [StandardEngine] Starting Servlet Engine: Apache Tomcat/5.5
16:49:21,111 INFO [StandardHost] XML validation disabled
16:49:21,127 INFO [Catalina] Server startup in 47 ms
16:49:21,236 INFO [TomcatDeployer] deploy, ctxPath=/invoker, warUrl=.../deploy/http-invoker.sar/invoker.war/
16:49:22,205 INFO [WebappLoader] Dual registration of jndi stream handler: factory already defined
16:49:23,002 INFO [TomcatDeployer] deploy, ctxPath=/ws4ee, warUrl=.../tmp/deploy/tmp16350jboss-ws4ee-exp.war/
16:49:23,111 INFO [TomcatDeployer] deploy, ctxPath=/, warUrl=.../deploy/jbossweb-tomcat55.sar/ROOT.war/
16:49:23,252 INFO [TomcatDeployer] deploy, ctxPath=/jbossmq-httpil, warUrl=.../deploy/jms/jbossmq-httpil.sar/jbossmq-httpil.war/
16:49:25,174 INFO [TomcatDeployer] deploy, ctxPath=/web-console, warUrl=.../deploy/management/console-mgr.sar/web-console.war/
16:49:25,970 INFO [MailService] Mail Service bound to java:/Mail
16:49:26,252 INFO [RARDeployment] Required license terms exist, view META-INF/ra.xml in .../deploy/jboss-ha-local-jdbc.rar
16:49:26,330 INFO [RARDeployment] Required license terms exist, view META-INF/ra.xml in .../deploy/jboss-ha-xa-jdbc.rar
16:49:26,408 INFO [RARDeployment] Required license terms exist, view META-INF/ra.xml in .../deploy/jboss-local-jdbc.rar
16:49:26,502 INFO [RARDeployment] Required license terms exist, view META-INF/ra.xml in .../deploy/jboss-xa-jdbc.rar
16:49:26,564 INFO [RARDeployment] Required license terms exist, view META-INF/ra.xml in .../deploy/jms/jms-ra.rar
16:49:26,627 INFO [RARDeployment] Required license terms exist, view META-INF/ra.xml in .../deploy/mail-ra.rar
16:49:27,252 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,
                   name=DefaultDS' to JNDI name 'java:DefaultDS'
16:49:27,533 INFO [A] Bound to JNDI name: queue/A
16:49:27,533 INFO [B] Bound to JNDI name: queue/B
16:49:27,533 INFO [C] Bound to JNDI name: queue/C
16:49:27,533 INFO [D] Bound to JNDI name: queue/D
16:49:27,533 INFO [ex] Bound to JNDI name: queue/ex
16:49:27,549 INFO [testTopic] Bound to JNDI name: topic/testTopic
16:49:27,549 INFO [securedTopic] Bound to JNDI name: topic/securedTopic
16:49:27,549 INFO [testDurableTopic] Bound to JNDI name: topic/testDurableTopic
16:49:27,549 INFO [testQueue] Bound to JNDI name: queue/testQueue
16:49:27,595 INFO [UILServerILService] JBossMQ UIL service available at : /0.0.0.0:8093
16:49:27,674 INFO [DLQ] Bound to JNDI name: queue/DLQ
16:49:27,752 INFO [ConnectionFactoryBindingService] Bound ConnectionManager
                   'jboss.jca:service=DataSourceBinding,name=jdbc_opencrx_CRX' to JNDI name 'java:jdbc_opencrx_CRX'
16:49:27,892 INFO [ConnectionFactoryBindingService] Bound ConnectionManager
                   'jboss.jca:service=ConnectionFactoryBinding,name=JmsXA' to JNDI name 'java:JmsXA'
16:49:27,939 INFO [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-console.war/
16:49:28,064 INFO [EARDeployer] Init J2EE application: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-App.ear/
16:49:36,127 INFO [EjbModule] Deploying opencrx_core_CRX_gateway_mandatory
16:49:36,189 INFO [EjbModule] Deploying opencrx_core_CRX_gateway_noOrNew
16:49:36,314 INFO [EjbModule] Deploying opencrx_core_CRX_kernel_mandatory
16:49:36,361 INFO [EjbModule] Deploying opencrx_core_CRX_security_mandatory
16:49:36,408 INFO [EjbModule] Deploying opencrx_core_CRX_ui_never
16:49:36,455 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_gateway_mandatory' to
                   jndi 'org.opencrx.core.CRX.local.mandatory.gateway'
16:49:36,486 INFO [ProxyFactory] Bound EJB Home 'opencrx_core_CRX_gateway_mandatory' to
                   jndi 'org.opencrx.core.CRX.mandatory.gateway'
16:49:36,502 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_gateway_noOrNew' to
                   jndi 'org.opencrx.core.CRX.local.noOrNew.gateway'
16:49:36,517 INFO [ProxyFactory] Bound EJB Home 'opencrx_core_CRX_gateway_noOrNew' to jndi 'org.opencrx.core.CRX.noOrNew.gateway'
16:49:36,517 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-App.ear/gateway.jar
16:49:36,549 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_kernel_mandatory' to
                   jndi 'org.opencrx.core.CRX.local.mandatory.kernel'
16:49:36,549 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-App.ear/kernel.jar
16:49:36,580 INFO [BaseLocalProxyFactory] Bound EJB LocalHome 'opencrx_core_CRX_security_mandatory' to
                   jndi 'org.opencrx.core.CRX.local.mandatory.security'
16:49:36,580 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-App.ear/security.jar
16:49:36,611 INFO [ProxyFactory] Bound EJB Home 'opencrx_core_CRX_ui_never' to jndi 'org.opencrx.core.CRX.never.ui'
16:49:36,611 INFO [EJBDeployer] Deployed: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-App.ear/ui.jar
16:49:36,627 INFO [EARDeployer] Started J2EE application: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-App.ear/
16:49:36,627 INFO [EARDeployer] Init J2EE application: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-web.ear/
16:49:42,361 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX/client-gateway,
                   warUrl=.../tmp/deploy/tmp16429client-gateway-exp.war/
16:49:42,470 INFO [TomcatDeployer] deploy, ctxPath=/opencrx-core-CRX,
                   warUrl=.../deploy/opencrx-core-CRX-web.ear/opencrx-core-CRX.war/
16:49:43,611 INFO [EARDeployer] Started J2EE application: file:/D:/jboss-4.0.3SP1/server/default/deploy/opencrx-core-CRX-web.ear/
16:49:43,689 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-0.0.0.0-8080
16:49:43,783 INFO [ChannelSocket] JK: ajp13 listening on /0.0.0.0:8009
16:49:43,799 INFO [JkMain] Jk running ID=0 time=0/79 config=null
16:49:43,799 INFO [Server] JBoss (MX MicroKernel) [4.0.3SP1 (build: CVSTag=JBoss_4_0_3_SP1 date=200510231054)] Started in 41s:750ms

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.3SP1\server\default\JBossDefault.exe
Execute the following command (everything on a single line, i.e. no line breaks!):

Listing 9: 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.3SP1\server\default\server.log.properties -Dmail.SSLSocketFactory.class=org.opencrx.ssl.DefaultSSLSocketFactory -Dprogram.name=run.bat -Djava.class.path=d:\pgm\j2sdk1.5\lib\tools.jar;D:\pgm\jboss-4.0.3SP1\bin\run.jar -Xms128m -Xmx500m -start org.jboss.Main

Adapt d:\pgm\j2sdk1.5 and D:\pgm\jboss-4.0.3SP1 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 10: 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 11: 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 12: 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 13: 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.