Accessibility

ColdFusion Release Notes

Installing and Deploying ColdFusion MX 7 on IBM WebSphere 5 Network Deployment

Contents

About this document

This document describes procedures required to install and deploy the Macromedia ColdFusion MX 7 J2EE configuration on IBM WebSphere 5.1 ND.

Before reading this document, you should be familiar with:

Conventions in this document

This document uses the following conventions to reference WebSphere and ColdFusion directories:

Directory Description
websphere_root Directory in which IBM WebSphere Application Server is installed; for example, C:\Program Files\WebSphere on Windows, and /opt/WebSphere on UNIX.
cf_webapp_root The directory to which the ColdFusion web application is deployed; for example:
  • On Windows -
    C:\Program Files\WebSphere\AppServer\installedApps\CellName\MacromediaColdFusionMX.ear\ cfusion.ear\cfusion.war
  • On UNIX -
    /opt/WebSphere/AppServer/installedApps/CellName/MacromediaColdFusionMX.ear cfusion.ear/cfusion.war
java_home Root directory of your Java 2 Software Development Kit (J2SDK); for example:
C:\j2sdk1.4.1

About ColdFusion and WAS ND

You can deploy the Macromedia ColdFusion MX 7 J2EE configuration as an application running on a Java 2 Enterprise Edition (J2EE) application server. This document describes how to deploy this configuration on IBM WebSphere Application Server (WAS) 5 Network Deployment (ND).

Deploying multiple application server clones on a single compuer is commonly referred to as vertical clustering. Vertical clustering leverages the computer's processing power to obtain a higher level of efficiency; however, if there is total computer failure, no application server instances are available. The applications deployed in a vertical cluster share the same file system.

Deploying the multiple application servers on multiple computers is commonly referred as horizontal clustering; it provides the highest level of failover and scaling.

The steps you perform to deploy ColdFusion MX 7 in a clustered environment are the same, regardless of clustering method, because the WebSphere Network Deployment Manager manages the cluster.

Note: Although these instructions are for use with the ColdFusion MX 7 Updater, they only describe a full installation deployment of WAS ND. This document does not describe how to update existing WAS ColdFusion deployments to WAS ND.

Deploying ColdFusion MX 7 on WebSphere ND

This section describes how to deploy ColdFusion MX on WebSphere 5 ND.

Note: These instructions assume that you have installed the J2EE configuration of ColdFusion MX 7 Updater.

To deploy ColdFusion MX 7 on WebSphere 5 ND:

  1. Start the IBM WebSphere Application Server, if it is not running.
  2. Run the IBM WebSphere Administrative Console, if it is not running.
  3. Select Applications > Install New Application.
  4. When the Preparing for the Application Installation page appears, enter the path to the EAR file that you installed when you installed ColdFusion; for example, C:\CFusionMX7\cfusion.ear.
  5. Leave the Context Root box empty and click Next.

    Note: If you are running the Administrative console from a browser that is not on the same system on which WebSphere is running, that is, not from localhost, use the Server Path option, which enables directory browsing on the server file system.

  6. Accept the default values on the second Preparing for the Application Installation page, if appropriate for your WebSphere configuration, and then click Next.

    Note: WebSphere might display an Application Security Warnings page with a message at the bottom of the page that starts with "ADMA0080W: A template policy file without any permission set is included in the 1.2.x enterprise application." You can ignore this warning.

  7. Click Continue.
  8. When the Step 1: Provide Options to Perform the Installation panel of the Install New Application procedure appears, accept the default values, if appropriate for your WebSphere configuration, and then click Next.

    Note: You might want to change the application name in this step. The default name, Macromedia ColdFusion MX 7, is long and results in an application deployment directory name (cfusion.ear) that is long and includes spaces. However, these instructions use the default name.

  9. When the Step 2: Map Virtual Hosts for Web Modules panel appears, select the virtual host or hosts in which to install the ColdFusion MX 7 application and Remote Development Services (RDS) support, and then click Next.

    Note: RDS must be on the same virtual host and port as ColdFusion MX 7.

  10. When the Step 3: Map modules to Application Servers panel appears, select the WebSphere cluster in which to install the ColdFusion application and RDS support, and then click Next.
  11. When the Step 4: Summary panel appears, review the installation configuration, and then click Finish.
  12. When the Application Macromedia ColdFusion MX 7 Installed Successfully message appears on the Installing page, select Save to Master Configuration, and then select Save on the Save page to save your workspace.

    Note: If you changed the application name in step 7, the message uses your application name.

  13. Do the following to ensure that ColdFusion sandbox security secures Java access to files and network resources:
    1. On the WebSphere Administrative Console Security > Global Security panel, ensure that the Enforce Java 2 Security option is selected.
    2. If you made any changes in step a, save your configuration.
  14. If the Enforce Java 2 Security option is selected on the Security > Global Security panel (that is, you use the Java security policy manager), do the following:
    1. Add the following lines to the JVM's security policy file, java.policy (for example, C:\Program Files\WebSphere\AppServer\java\jre\lib\security\java.policy):

      grant {
      permission java.security.AllPermission;
      };

    2. Restart the application server.
  15. If you are using IBM Web Server, update the web-server plugin by performing the following steps:
    1. Select Cell > Environment > Update Web Server Plugin > View or download the current web server plugin configuration file.
    2. Ensure that the following entries exist:

      <UriGroup Name="<virtual_host>_<cluster_name>_URIs">
      <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/<CF_CONTEXT_ROOT>/*" />
      <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/CFIDE/*" />

    3. If the entries in step b do not exist, update the plugin-cfg.xml with the entries. The location of the plugin-cfg.xml is defined in the IBM HttpServer config file http.conf file in the WebSpherePluginConfig parameter.
  16. If it is not already running, start the ColdFusion Application in the WebSphere Administrative Console Applications > Enterprise Applications panel by selecting the box next to Macromedia ColdFusion MX 7 (or the application name that you specified when you deployed ColdFusion MX 7), and then selecting Start. You might have to stop and restart the application server on which the ColdFusion application runs before you can start ColdFusion MX 7.
  17. Start the ColdFusion MX Administrator, which runs the Configuration and Settings Migration Wizard.

Enabling and configuring specific ColdFusion MX functionality

For some ColdFusion MX 7 functionality to work properly, you must manually configure your application server. This section provides instructions for procedures that are specific to WebSphere 5, and includes the following:

Additional procedures are identical for all J2EE platforms and are documented in Chapter 5, "Configuring Your System" in Installing and Using ColdFusion MX.

Configuring ColdFusion MX 7

Ensure that the following settings and practices are in place before using WAS ND:

  • Event Gateway - Ensure that the startup mode of the Socket gateway instances is set to manual. In particular, do not set it to Automatic when using a vertical cluster. Select one of the instances in the vertical cluster and start the Socket gateway on that instance manually.
  • Session Replication - Either avoid ColdFusion-specific data types or serialize them to WDDX and store them in session scope as strings.
  • ColdFusion MX Administrator:
    • In a vertical cluster environment, avoid concurrent changes to the same service.
    • In a horizontal cluster environment, each server has its own ColdFusion MX Administrator. You must make changes once per server.
    • In a vertical cluster environment, the ColdFusion MX Administrator scheduled tasks are scheduled on all servers.
  • Verity Server - Only one Verity Search Server can run on each server computer.

    Note: ColdFusion MX Verity licensing does not allow a ColdFusion cfsearch tag to search multiple Verity Search Server computers. For a horizontal cluster to interact with a central Verity Search Server, you must purchase K2 Enterprise from Verity.

  • Compilation - Use precompiled classes and ensure that the Trusted Cache setting is enabled.

Enabling features with operating system-specific binaries

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)

These features work on Windows, Linux, and Solaris only.

Use the 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 on Windows, and the cf_webapp_root/WEB-INF/cfusion/lib directory on UNIX.

To configure operating system-specific binary support on Windows:

  1. Make a backup copy of the setupCmdLine.bat file, located in the websphere_root\AppServer\bin directory.
  2. Open the original file for editing and add the following on a single line before the line that starts with SET WAS_CLASSPATH:

    SET CFMX_APPS_PATH=cf_webapp_root\WEB-INF\cfusion\lib

  3. Replace cf_webapp_root with the path to your web application directory; for example, enter the following:

    SET CFMX_APPS_PATH=%WAS_HOME%\installedApps\%WAS_CELL%\ MacromediaColdFusionMX.ear\cfusion.ear\cfusion.war\WEB-INF\cfusion\lib

  4. Add the CFMX_APPS_PATH variable to the WAS_CLASSPATH by appending the following text to the path statement:

    ;%CFMX_APPS_PATH%

    The WAS_CLASSPATH line should look similar to the following:

    SET WAS_CLASSPATH=%WAS_HOME%/properties;%WAS_HOME%/lib/bootstrap.jar;
    %WAS_HOME%/lib/j2ee.jar;%WAS_HOME%/lib/lmproxy.jar;%WAS_HOME%/lib/urlprotocols.jar;%CFMX_APPS_PATH%

  5. Save the file.
  6. Add the full path to the cf_webapp_root\WEB-INF\cfusion\lib directory to the WAS_PATH variable in the setupCmdLine.bat file. The WAS_PATH line should look similar to the following:

    SET WAS_PATH=%WAS_HOME%\bin;%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;%PATH%; C:\Program Files\IBM\WebSphere MQ\bin;C:\Program Files\IBM\WebSphere
    MQ\java\bin;C:/Program Files/IBM/WebSphere MQ/WEMPS\bin;%WAS_HOME%\
    installedApps\%WAS_CELL%\ MacromediaColdFusionMX.ear\cfusion.ear\cfusion.war\WEB-INF\cfusion\lib

  7. Save the file and restart your WebSphere Application Server.

To configure operating system-specific binary support on Solaris and Linux:

  1. Make a backup copy of the startServer.sh file, located in the websphere_root/AppServer/bin directory.
  2. Note: The path specifications in these instructions assume that you deployed ColdFusion using the standard application name (Macromedia ColdFusion MX 7) and did not rename the application.

  3. Open the original file for editing, and in the PLATFORM case block, just above the LD_LIBRARY_PATH line, add the following entry on a single, long line:

    On Solaris:

    CFMX_APPS_PATH=cf_webapp_root/WEB-INF/cfusion/lib

    where cf_webapp_root is the path to your web application root directory; for example:
    CFMX_APPS_PATH="$WAS_HOME"/installedApps/"$WAS_CELL"/
    MacromediaColdFusionMX.ear/cfusion.ear/cfusion.war/WEB-INF/cfusion/lib

    On Linux:

    CFMX_APPS_PATH=cf_webapp_root/WEB-INF/cfusion/lib

    where cf_webapp_root is the path to your web application root directory; for example:
    CFMX_APPS_PATH="$WAS_HOME"/installedApps/"$WAS_CELL"/ MacromediaColdFusionMX.ear/cfusion.ear/cfusion.war/WEB-INF/cfusion/lib

  4. Append the CFMX_APPS_PATH environment variable to the LD_LIBRARY_PATH entry. The resulting line should be similar to the following:

    LD_LIBRARY_PATH="$WAS_LIBPATH":$LD_LIBRARY_PATH:$CFMX_APPS_PATH

  5. Save the file and restart your WebSphere Application Server.

Enabling access to COM objects (Windows only)

This section describes how to enable Component Object Model (COM) support on Windows after installing ColdFusion MX 7. COM support is required to use the cfreport tag with Crystal Reports. It is not required for the ColdFusion Report Builder or any reports that you create with the ColdFusion reporting feature.

To enable COM support:

  1. In the WebSphere Administrative Console, open the Node Name > Servers > Application Servers panel.
  2. Select the application server for your ColdFusion MX 7 application, and then select the Process Definition link in the Additional Properties box of the Configuration tab.
  3. Select the Java Virtual Machine link in the Process Definition Additional Properties panel and add the following line to the Generic JVM Arguments entry:

    -DJINTEGRA_NATIVE_MODE -DJINTEGRA_PREFETCH_ENUMS

  4. Click OK.
  5. Save your configuration file.
  6. Make a backup copy of the setupCmdLine.bat file, located in the websphere_root\AppServer\bin directory.
  7. Open the original file for editing and add the following on a single line:

    SET PATH=%PATH%;cf_webapp_root\WEB-INF\cfusion\jintegra\bin;cf_webapp_root\WEB-INF\
    cfusion\jintegra\bin\international

    where cf_webapp_root is the path to your web application root directory, for example:

    SET PATH=%PATH%;%WAS_HOME%\installedApps\%WAS_CELL%\ MacromediaColdFusionMX.ear\cfusion.ear\cfusion.war\WEB-INF\cfusion\jintegra\bin;%WAS_HOME%\installedApps\
    %WAS_CELL%\MacromediaColdFusionMX.ear\cfusion.ear\cfusion.war\WEB-INF\cfusion\
    jintegra\bin\international

  8. Save the file and restart your computer.

In some cases, you might also have to do the following to register the Microsoft Type viewer:

  1. Open a console window and go to cf_webapp_root\WEB-INF\cfusion\lib.
  2. Register TypeViewer.dll by issuing the following command:

    regsvr32 TypeViewer.dll

Enabling charting and graphing (UNIX)

This section describes how to configure your application server to use ColdFusion MX 7 charting and graphing on AIX, Linux, and Solaris systems. This step is not required to enable charting and graphing on Windows.

For instructions on enabling charting on servers that use JVM 1.3.x, see cf_webapp_root\WEB-INF\cfusion\charting\java1.3\readme.txt.

To enable charting and graphing:

  1. Open the WebSphere Administrative Console.
  2. In the left navigation bar, select Node_name > Servers > Application Servers.
  3. Select your J2EE application server; for example, Server1.
  4. On the Configuration tab of the Application server page, select Process Definition in the Additional Properties box.
  5. On the Process Definition page, select Java Virtual Machine in the Additional Properties box.
  6. If you are running ColdFusion MX 7 on a system without a monitor, do the following:
    1. In the Additional Properties box at the bottom of the page, select Custom Properties.
    2. On the Custom Properties page, select New and add a system property, completing the fields as follows:

      Name java.awt.headless
      Value true

    3. Click OK to return to the Java Virtual Machine page.
  7. Click OK.

Disabling RDS

For security reasons, Macromedia recommends that you disable RDS on a production server. If you enable RDS when you install ColdFusion MX 7, you can disable it at a later time, as the following instructions describe.

Note: If you disable RDS, the following ColdFusion MX 7 features do not work: the Browse Server button in the ColdFusion MX Administrator (for example, on the ColdFusion Mappings page), and the Query Builder and charting in the ColdFusion Report Builder.

To disable RDS:

  1. Disable the ColdFusion MX 7 web module RDS Servlet. Doing so ensures that ColdFusion MX 7 cannot respond to any RDS requests.
  2. If your ColdFusion MX 7 application context root is not /, disable or undeploy the RDS redirector web module.

Disabling the RDS Servlet

To disable the RDS Servlet:

  1. Stop ColdFusion.
  2. In the WebSphere Administrative Console, select the Applications > Enterprise Applications panel, select the Macromedia ColdFusion MX application, and then click Stop.
  3. Do the following in both the cf_webapp_root\WEB-INF\web.xml and the websphere_root\AppServer\config\cells\NodeName\applications\cf_application_name.ear\ deployments\cf_application_name\cfusion.war\WEB-INF\web.xml files (or the equivalent paths in UNIX). For example, change the following files:

    C:\Program Files\WebSphere\AppServer\installedApps\MYNODE\cfusion.ear\cfusion.war\WEB-INF\web.xml

    C:\Program Files\WebSphere\AppServer\config\cells\MYNODE\applications\cfusion.ear\deployments\Macromedia ColdFusion MX\cfusion.war\
    WEB-INF\web.xmll

    1. Back up the ColdFusion web module web.xml file.
    2. Open the original web.xml file for editing.
    3. Comment out the RDS Servlet definition, as follows:

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

      Note: Some of the text in the servlet definition might vary.

    4. Comment out the RDS Servlet mapping, as the following example shows:
      <!--
        <servlet-mapping id="macromedia_mapping_9">
          <servlet-name>RDSServlet</servlet-name>
          <url-pattern>/CFIDE/main/ide.cfm</url-pattern>
        </servlet-mapping>
      -->

      Note: The servlet-mapping id value might vary.

    5. Save the file.
  4. Restart the ColdFusion MX 7 application.

Disabling the RDS redirector

If you installed ColdFusion MX 7 at a context root other than /, use the following procedure to disable the RDS redirector web module without undeploying it.

Note: If you disable or undeploy the RDS redirector and do not disable the RDS servlet, RDS services are still available using the ColdFusion MX 7 application context root; however, tools that use RDS and require a context root of /, such as Macromedia Dreamweaver and previous versions of HomeSite, do not work.

To disable the RDS web module:

  1. In the WebSphere Administrative Console, select cell_name > Applications > Enterprise Applications.
  2. Stop the Macromedia ColdFusion MX 7 application if it is running.
  3. Select Macromedia ColdFusion MX 7 Application to display the Configuration page, and then select the Local Topology tab.
  4. Expand the Macromedia_ColdFusion_MX entry in the Applications tree, expand the Web Module folder, and then select rds.war to display the rds.war configuration page.
  5. Select Target Mappings in the Additional Properties box, and select your application server; for example, Server1.
  6. On the Configuration page General Properties box, clear the Enabled check box, and click OK.
  7. Select Save to Master Configuration at the top of the Target Mappings page, and then click Save on the Save page to save your workspace.
  8. When the configuration has been saved and the main Administrative Console page appears, stop and restart the application server.
  9. Start the ColdFusion Application, if necessary.

You can re-enable the RDS web module by repeating this procedure and selecting the Enabled check box.

Limitations and Troubleshooting

The following sections describe limitations and issues that are specific to ColdFusion MX 7 on WebSphere.

If you encounter problems with your ColdFusion MX 7 installation that are not described in this section, see the "Troubleshooting" chapter in Installing and Using ColdFusion MX. In addition, see the ColdFusion MX 7 Release Notes and the ColdFusion Technical Support website.

Issue: Pages with double-byte characters are blank

If you use IBM JVM 1.4.x on UNIX or Linux and the CFML page is encoded in a character encoding that does not match the Java default file encoding (which is determined by the local setting), the page appears blank on the user's browser.

You use the CFML cfprocessingdirective tag's pageEncoding attribute to identify the page encoding.

To avoid this issue, do one of the following:

  • Write the CFML page using the Java default file encoding.
  • Write the CFML page using UTF-8 and with a byte order mark (BOM).
  • Add the following entry to the JVM configuration:

    -Dibm.stream.nio=true

Issue: The enctype attribute causes errors with multi-byte characters in form data

If you set the enctype attribute of the cfform tag or HTML form tag, multiple-byte characters in values submitted by the form are not received in the action page Form scope variable. This problem only affects characters with multiple-byte representations, such as double-byte characters in the Chinese Big5 encoding. Single-byte characters in the string (such as Roman alphabet characters in the Big5 encoding) are received correctly. This issue is independent of the operating system locale.

To avoid this issue, remove the enctype parameter from the cfform or form tag.

Undeploying ColdFusion MX 7

This section describes how to undeploy ColdFusion MX 7 from IBM WebSphere Application Server.

To undeploy ColdFusion MX:

  1. (Windows only) If the ODBC services are installed, remove the services by browsing to the cf_webapp_root\WEB_INF\cfusion\db\SequeLink Setup directory and running the RemoveSequeLink.bat file.
  2. Open the WebSphere Administrative Console.
  3. Select the Cell > Applications > Enterprise Applications page. If the ColdFusion application status is Started, select the check box next to the Macromedia ColdFusion MX 7 option and click Stop.
  4. When the ColdFusion application server has stopped, select the check box next to the Macromedia ColdFusion MX 7 option again, and then select Uninstall.

    WebSphere uninstalls the ColdFusion application.

  5. Save the new configuration.
  6. When the Save panel appears, click Save.
  7. Stop the WebSphere Application Server.
  8. If WebSphere did not delete the cf_webapp_root directory, delete it. You might have to restart your computer before you can delete the files.
  9. If you installed the Verity Search Service or the Report Builder on Windows, use Add or Remove Programs to uninstall these programs.
  10. If you installed the Verity Search Service on Linux or Solaris, run verity-uninstall.sh, which is located in the directory where you installed Verity.

Top Support Topics

 

More ColdFusion Topics

Choose a category to see more topics.

Request Support

 

Additional ColdFusion Resources

 

ColdFusion Downloads

 

Outside Resources

 

Feedback

 

Community