Deploying ColdFusion 9 on JBoss Application Server



ColdFusion 9 supports JBoss with the following specifications:

  • JBoss 4.2/5.0.1 (uses Tomcat 6.0.x Server Container)

  • Sun JDK 1.5 and Sun JDK 1.6

  • Host OS - Windows 2003 server SP1, Solaris 10, and RH Linux 4AS/5 AS

ColdFusion 9 has not been tested using JBoss under the following conditions:
  1. JBoss using a servlet container other than Tomcat

  2. Operating systems that are not in the previous list

Note: If you are already using an application with context root of /, use a context root other than / for the cfusion-ear file. If you specified / when you installed ColdFusion, you can change it by opening the cfusion-ear/META-INF/application.xml file in a text editor and modifying the context-root element. After you deploy the cfusion-ear file, you access ColdFusion pages by specifying http://hostname:portnumber/contextroot/pagename.cfm.

If you are updating an existing deployment of ColdFusion, undeploy it for J2EE before you deploy ColdFusion 9.

When you deploy ColdFusion on an existing version of JBoss, expand the EAR file or WAR files manually before deployment.

This document uses the following conventions:

JBOSS_HOME
Directory where JBoss is installed, for example, C:\jboss-4.0.5SP1 in Windows or /usr/local/jboss-4.0.5.SP1 on UNIX

JBOSS_DEPLOY_DIR
Application deployment directory in JBoss, for example, C:\jboss-4.0.5SP1\server\default\deploy

CF_WEBAPP_ROOT
Directory where ColdFusion is deployed, for example: C:\jboss-4.0.5SP1\server\default\deploy\cfusion.ear\cfusion.war

TEMP_LOCATION
Temporary location where you extract the cfusion.ear file.

Deploy ColdFusion on JBoss

  1. To ensure that ColdFusion can deploy on JBoss 4.2/JBoss 5.01, perform the following steps instead of following the standard instructions in the cf-j2ee-readme.txt file:

    1. Keep periods in the directory names, instead of renaming them with dashes, for example, \deploy\cfusion.ear\cfusion.war.

    2. Do not make the updates to application.xml.

  2. Set JAVA_HOME to the appropriate JDK.

  3. Install ColdFusion by using the J2EE deployment option and selecting to create an EAR file (the default).

    The installation program creates the cfusion.ear file in the install directory.

  4. Extract the cfusion.ear file into a TEMP_LOCATION\cfusion.ear folder. This step creates cfusion.war and rds.war files and a META-INF folder in the cfusion.ear folder.

  5. In the cfusion.ear folder, extract the cfusion.war and rds.war files into folders named cfusion and rds, respectively.

  6. Delete the compressed cfusion.war and rds.war files.

  7. Rename the cfusion and rds folders to cfusion.war and rds.war, respectively.

  8. Stop JBoss if it is running.

  9. Copy or move the TEMP_LOCATION\cfusion.ear folder into the JBOSS_DEPLOY_DIR folder

    The resulting directory structure should appear as follows:

    JBoss 4.2.0 or JBoss 5.01 
          server 
             default 
                deploy 
                   cfusion.ear 
                      cfusion.war 
                      META-INF 
                      rds.war
  10. (Windows) Edit the JBOSS_HOME\bin\run.bat file by doing the following:

    1. If not present, add the JVM (-Xmx512m) parameter to JAVA_OPTS.

    2. Ensure that the permanent generation heap size is set by adding -XX:MaxPermSize=128m to JAVA_OPTS.

      Without this parameter, the JVM can generate a java.lang.OutOfMemoryError error. For more information, see (http://wiki.jboss.org/wiki/Wiki.jsp?page=PermanentGeneration).

    3. Ensure that the jars available in WEB-INF/flex/jars are in the classpath.

    4. Save the run.bat file.

    5. Start the server by running the JBOSS_HOME\bin\run.bat file.

    Note: If you use Apache Derby database, add the following in run.bat: JAVA_OPTS=%JAVA_OPTS% -Djboss.platform.mbeanserver. This is to ensure that Apache Derby do not start a JMX management server that might conflict with JBoss.
  11. (Linux) Edit the JBOSS_HOME/bin/run.conf file by doing the following:

    1. In JAVA_OPTS, change -Xmx128m. to -Xmx512m.

    2. Add -XX:MaxPermSize=128m to JAVA_OPTS.

    3. Save the run.conf file.

    4. Start the server by running the JBOSS_HOME/bin/run.sh file.

      To enable features with operating system-specific binaries, configure ColdFusion. This step is required to support the following features that use binaries that are specific to your operating system:

      • CFX tags written in C++

      • Microsoft Access driver with Unicode support (Windows only)

        Use the following procedure for your operating system to configure the search paths to find the required binary files. These files are located in the CF_WEBAPP_ROOT\WEB-INF\cfusion\lib directory.

    Note: If you use Apache Derby database, add the following in run.bat: JAVA_OPTS="$JAVA_OPTS -Djboss.platform.mbeanserver". This is to ensure that Apache Derby do not start a JMX management server that might conflict with JBoss.

Configure operating system-specific binary support for Windows

  1. Ensure that JBoss Server is stopped.

  2. Edit JBOSS_HOME\bin\run.bat by adding the following:

    set CF_LIB_PATH=JBOSS_DEPLOY_DIR\cfusion.ear\cfusion.war\WEB-INF\cfusion\lib 
    set PATH=%PATH%;%CF_LIB_PATH%
  3. Edit the run.bat file that is located in the JBOSS_DEPLOY_DIR by doing the following:

     Locate the following text:
    @echo off 
    rem ----------------------------------------------- 
    rem JBoss Bootstrap Script for Win32 
    rem -----------------------------------------------
  4. Below this text, insert three lines and paste.

    set CF_LIB_PATH=JBOSS_DEPLOY_DIR\cfusion.ear\cfusion.war\WEB-INF\cfusion\lib 
    set PATH=%PATH%;%CF_LIB_PATH%
  5. Save the file and start the server.

    Note: You must copy the version of tools.jar that the application server uses to the cfusion/lib directory.

Configure operating system-specific binary support for Linux

  1. Ensure that JBoss Server is stopped.

  2. Edit JBOSS_HOME/bin/run.sh by adding the following:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:CF_WEBAPP_ROOT/WEB-INF/cfusion/lib
  3. Save the file and start the server.

Enable COM support (Windows only)

  1. Ensure that JBoss Server is stopped.

  2. Edit JBOSS_HOME\bin\run.bat by adding the following:

    set CF_LIB_PATH=%CF_LIB_PATH%;CF_WEBAPP_ROOT\WEB-INF\cfusion\jintegra\bin;CF_WEBAPP_ROOT\WEB-INF\cfusion\jintegra\bin\international
  3. Save the file and start the server.

Enable communication with Flex

When ColdFusion is configured to use RMI for LiveCycle Data Services ES, ColdFusion listens on port 1099 by default. However JBoss typically starts listening on this port before ColdFusion does; as a result, an exception is thrown. To configure ColdFusion to use a different RMI port, on the Java and JVM page of the ColdFusion Administrator, specify the following in the JVM arguments text area:

-Dcoldfusion.rmiport=nnnn

Replace nnn with the value of an unused port. If you try to connect from a LiveCycle Data Services ES server that is running in another JVM server to ColdFusion over RMI, the Flex server must start with the same JVM argument.

Disable RDS

  1. Stop ColdFusion.

  2. Edit JBOSS_DEPLOY_DIR\cfusion.ear\cfusion.war\WEB-INF\web.xml by commenting out the following:

    <!-- <servlet id="macromedia_servlet_8789">  
        <servlet-name>RDSServlet</servlet-name>  
        <display-name>RDS Servlet</display-name>  
        <servlet-class>coldfusion.bootstrap.BootstrapServlet</servlet-class>  
        <init-param id="InitParam_103401311065856789">  
            <param-name>servlet.class</param-name>  
            <param-value>coldfusion.rds.RdsFrontEndServlet</param-value> 
        </init-param>  
    </servlet> --> 
    <!-- <servlet-mapping id="macromedia_mapping_9">  
        <servlet-name>RDSServlet</servlet-name>  
        <url-pattern>/CFIDE/main/ide.cfm</url-pattern>  
    </servlet-mapping> -->
  3. Save the file and start ColdFusion.

Prevent security-based errors

If you notice security-based errors when JBOSS is starting (errors that mention Java and security), edit the run.bat file as follows:

  1. Go to the line that contains the -Xmx512m parameter.

  2. Change the text: -Dprogram.name=%PROGNAME% to be -Dcoldfusion.disablejsafe=true %JAVA_OPTS%.

    These security errors occur because some versions of JBOSS cannot handle additional encryption software that ColdFusion uses for higher security standards. Some features, such as EJB3, require JDK 1.5.