Accessibility
 
Home / Products / ColdFusion / Support
J2EE Support

Installing and Deploying ColdFusion MX 6.1 for IBM zSeries

The Macromedia ColdFusion MX Enterprise 6.1 J2EE configuration supports WebSphere Application Server 5 running on Linux on IBM zSeries and S/390 hardware.

Note: Support for ColdFusion MX Enterprise 6.1 running on an IBM mainframe is subject to special pricing and licensing requirements. For more information, see the ColdFusion MX zSeries product page.

This document contains the following sections:

About this document

Installing and deploying Macromedia ColdFusion MX 6.1

Enabling and configuring specific ColdFusion MX 6.1 functionality

Undeploying ColdFusion MX

About this document

This document describes the procedures for installing and deploying the Macromedia ColdFusion MX Enterprise 6.1 J2EE configuration on IBM WebSphere 5 running on IBM zSeries. It refers to overview information in Installing and Using ColdFusion MX, which is available on LiveDocs.

Note: When running on IBM zSeries, ColdFusion MX 6.1 does not include support for Verity and C++ CFXs.

Before continuing, you should read the ColdFusion MX 6.1 Release Notes. You should also read the first and third chapters of Installing and Using ColdFusion MX.

These instructions contain application server-specific instructions on installing a new copy of ColdFusion MX 6.1. For configuration information that is common to all J2EE servers, see "Enabling and Using ColdFusion MX Features on Your J2EE Server" before continuing.

Conventions in this document

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

  • websphere_root - The directory in which IBM WebSphere Application Server is installed; for example, /opt/WebSphere.
  • cf_root - The directory to which the ColdFusion web application is deployed; for example, /opt/WebSphere/AppServer/installedApps/MyHost/cfusion.ear/cfusion.war.
  • java_home - The root directory of your Java 2 software development kit (J2SDK).

Installing and deploying Macromedia ColdFusion MX 6.1

Before you can run ColdFusion applications, you must complete the following procedures to install and deploy ColdFusion MX 6.1 on IBM WebSphere:

  1. Installing the ColdFusion MX 6.1 files
  2. Deploying ColdFusion MX 6.1 on WebSphere
  3. Running the Configuration and Settings Migration Wizard

Note: This page describes how to install ColdFusion MX 6.1 directly from the cfusion.ear file. You can also install ColdFusion MX as a WAR file, but the process is more complex. To install using a WAR file, you must expand the cfusion.ear file into its constituent WAR files and deploy the cfusion.war file, specifying a context root in the WebSphere Administrative Console. If you do not deploy ColdFusion at the / context root, you must also deploy the rds.war file and specify /CFIDE as its context root.

Installing the ColdFusion MX 6.1 files

When installing on IBM zSeries, use the file coldfusion-61-zseries.jar, available on the Macromedia website.

Use the following procedure to install the ColdFusion MX EAR file and installation documentation.

To install ColdFusion MX 6.1 files:

  1. Ensure that your system environment meets the system requirements described in Installing and Using ColdFusion MX.
  2. Read the Release Notes for any late-breaking information or updates.
  3. Close any applications that are currently running on the computer to which you are deploying ColdFusion MX.
  4. Download the coldfusion-61-zseries.jar file from the Macromedia website.
  5. Set the working directory to the directory that contains the coldfusion-61-zseries.jar file.
  6. Enter one of the following commands, replacing java_home with the path to the bin directory for your JRE installation:

    In GUI mode (you must have XWindow Display configured):
    java_home/java -jar coldfusion-61-zseries.jar -i gui

    In console mode:
    java_home/java -jar coldfusion-61-zseries.jar -i console

  7. Follow the instructions in the installation program. Use the following information to complete certain sections of the installation program:
    • Before installing, determine the location of a working directory into which the ColdFusion MX EAR file should be installed.
    • The initial installer screen lets you select the language for the installer. This selection also determines the language for the online Help and installed documentation. ColdFusion MX support for IBM zSeries is limited to English.
    • On the License Agreement page, you must select I accept the terms of the License Agreement before you can click Next.
    • On the Install Type page, select Install new version of ColdFusion MX and enter a serial number. ColdFusion MX 6.1 trial and developer versions are not supported on IBM zSeries.
    • On the Install Configuration page, select J2EE configuration and make sure that EAR file is selected.
    • ColdFusion asks you for the directory in which to install the files. These files are required to deploy ColdFusion on WebSphere, but are not required afterward. Therefore, you can specify a staging area or temporary file location.
    • On the Context Root page, specify a name for the ColdFusion MX application context root. The context root is the first part of the URL for all requests sent to the application. The application server uses the context root to determine which web application must service an incoming request The default value is cfmx.
    • On the ColdFusion MX Administrator password page, enter the password to require for the ColdFusion MX Administrator.
    • Review the options in the Pre-Installation Summary section and accept them to complete the installation.

    When the installation is complete, the EAR file is placed in the specified location. Continue with the next section of the instructions, Deploying ColdFusion MX on WebSphere.

    Note: The installer creates the following log file: install_root/Macromedia_ColdFusion_MX_J2EE_InstallLog.log, where install_root is the directory that you specify when you install the ColdFusion MX files. If you contact Technical Support for installation support, you must send them this log file.

Deploying ColdFusion MX 6.1 on WebSphere

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

To deploy ColdFusion MX on WebSphere 5:

  1. Start the IBM WebSphere Application Server, if it is not running.
  2. Open the IBM WebSphere Administrative Console, if it is not running.
  3. Open the Applications > Install New Application page.
  4. The Preparing Application Install page appears. Enter the path to the EAR file that you installed in the Installing the ColdFusion MX files procedure; for example /opt/cfmx/cfusion.ear. 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 where WebSphere is running (that is, not from localhost), use the Server Path option, which enables directory browsing on the server file system.

  5. Accept the default values on the Preparing Application Install page, if appropriate for your WebSphere configuration. Click Next.
  6. Accept the default values in the Step 1: Provide Options to Perform the Installation panel of the Install New Application procedure, if appropriate for your WebSphere configuration. Click Next.

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

  7. In Step 2: Map Virtual Hosts for Web Modules, select the virtual host or hosts in which to install the ColdFusion MX application and Remote Development Services (RDS) support. RDS must be on the same virtual host and port as ColdFusion. Click Next.
  8. In Step 3: Map modules to Application Servers, if you have multiple application servers, select the application server in which to install the ColdFusion application and RDS support. Click Next.
  9. In Step 4: Summary, review the installation configuration and click Finish.
  10. When the "Application Macromedia ColdFusion MX installed successfully" message appears on the Installing page, click the Save to Master Configuration link, and click the Save button on the Save page to save your workspace. After clicking Save, wait until the home page reappears.
  11. If you are using the standard WebSphere JVM, Version 1.3.1, or any version other than 1.4.2, make sure the ColdFusion application is stopped, and replace cf_root/WEB-INF/cfusion/lib/tools.jar with the tools.jar from your JVM (normally websphere_root/AppServer/java/lib/tools.jar).
  12. Do the following to ensure that ColdFusion sandbox security secures Java access to files and network resources:
    1. Display the WebSphere Administrative Console Security > Global Security panel, and make sure the Enabled option and Enforce Java 2 Security option are both selected.
    2. If you made any changes in step a, save your configuration.
    3. Continue with the next step.
  13. If the Enabled option and Enforce Java 2 Security option are 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, /opt/WebSphere5/AppServer/java/jre/lib/security/java.policy):

      grant codeBase "<file:cf_root/WEB-INF/cfusion/lib/*>" {
      permission java.security.AllPermission;
      };
      grant codeBase "<file:cf_root/WEB-INF/lib/*>" {
      permission java.security.AllPermission;
      };
      

      Replace cf_root with your cf_root directory, for example, /opt/WebSphere/AppServer/installedApps/MyHost/cfusion.ear/cfusion.war.

    2. Restart the application server.
  14. Start the ColdFusion Application in the Enterprise Applications panel. Select the box next to Macromedia ColdFusion MX, and click Start. You might have to stop and restart the application server on which the ColdFusion application runs before you can start ColdFusion MX.
  15. Continue with the next section of the instructions, Running the Configuration and Settings Migration Wizard.

Running the Configuration and Settings Migration Wizard

After you deploy ColdFusion MX, you run the ColdFusion MX 6.1 Configuration and Settings Migration Wizard. To run the wizard in your browser, enter the URL for the ColdFusion MX Administrator. The URL has the following form:

http://host:[port]/cf_context_root/CFIDE/administrator

for example:

http://localhost:9080/cfmx/CFIDE/administrator

When you first access the Administrator, ColdFusion runs the Configuration and Settings Migration Wizard. Provide the wizard with the following information:

  • Enter the Administrator password you specified when you installed ColdFusion MX files.
  • Specify the RDS password. To maximize security, disable RDS on production servers. For information on disabling RDS, see Disabling RDS.
  • Specify whether to install example applications and supporting files (including data sources) for the ColdFusion MX Getting Started tutorial. For security reasons, Macromedia recommends that you do not install example applications on production servers.
  • The System Configuration page might tell you that you must do additional configuration steps to enable full ColdFusion MX functionality. You do not need to make these changes when you run the wizard; click Next. For information on the additional configuration steps you must take to enable all available ColdFusion MX features, see Enabling and configuring specific ColdFusion MX functionality

When the wizard displays the Finish page, click OK to open the ColdFusion MX Administrator. When the Administrator opens, you can configure ColdFusion features. Running the Administrator confirms that the installation procedure was successful. However, you must perform the tasks described in the Enabling and configuring specific ColdFusion MX functionality section before complete ColdFusion MX functionality is available.

Enabling and configuring specific ColdFusion MX 6.1 functionality

For some ColdFusion MX functionality to work properly, you must manually configure your application server.

This section provides instructions for procedures that are specific to WebSphere 5. It describes what to do for the following functionality:

Additional procedures are identical for all J2EE platforms and are documented in Enabling and Using ColdFusion MX Features on Your J2EE Server.

Enabling charting and graphing

This section describes how to configure your application server to use ColdFusion MX charting and graphing (cfchart, cfchartdata, and cfchartseries tags).

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, click the Process Definition link in the Additional Properties box.
  5. On the Process Definition page, click the Java Virtual Machine link in the Additional Properties box.
  6. In the Additional Properties box at the bottom of the page, click the Custom Properties link.
  7. On the Custom Properties page, click New and add a system property, completing the fields as follows:

    Name java.awt.graphicsenv

    Value com.gp.java2d.ExGraphicsEnvironment

    Note: For JDK 1.4.1 and later versions, specify com.gp.java2d.ExHeadlessGraphicsEnvironment
    instead of com.gp.java2d.ExGraphicsEnvironment.

  8. Click OK to return to the Java Virtual Machine page.
  9. In the General Properties box of the Java Virtual Machine page, type the following in the Boot Classpath field:

    cf_root/WEB-INF/cfusion/lib/webchartsJava2D.jar

  10. Click OK. Then click the Save link to save your configuration.

Disabling RDS

For security reasons, Macromedia recommends that you disable RDS on a production server.

Note: If you disable RDS, the Browse Server button does not work in the ColdFusion MX Administrator (for example, on the ColdFusion Mappings page).

To disable RDS:

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

Disabling the RDS Servlet

To disable the RDS Servlet:

  1. Back up the ColdFusion web module web.xml file.

    By default, this file is in the cf_root/WEB-INF directory.

  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>Apache-Axis 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_5">>
    <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.

RDS is disabled on the ColdFusion MX server.

Disabling the RDS redirector

Use the following procedure to disable the RDS redirector web module.

To disable the RDS web module:

  1. In the WebSphere Administrative Console, select node_name > Applications > Enterprise Applications.
  2. Stop the Macromedia ColdFusion MX application if it is running.
  3. Click the Macromedia ColdFusion MX Application link to display the Configuration page, and then select the Local Topology tab.
  4. Expand the Macromedia_ColdFusion_MX entry in the Applications tree. Then expand the Web Module folder, and click the rds.war link to display the rds.war configuration page.
  5. Click the Target Mappings link in the Additional Properties box, and click the link to your application server; for example, Server1.
  6. On the Configuration page General Properties box, clear the Enabled check box, and click OK.
  7. Click the Save to Master Configuration link at the top of the Target Mappings page, and click the Save button 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.

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

Undeploying ColdFusion MX 6.1

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

To undeploy ColdFusion MX:

  1. Open the WebSphere Administrative Console.
  2. Open the node_name > Applications > Enterprise Applications page. If the ColdFusion application status is Started, select the check box next to the Macromedia ColdFusion MX entry, and click Stop.
  3. When the ColdFusion application server has stopped, select the check box next to the Macromedia ColdFusion MX entry again, and click Uninstall. WebSphere uninstalls the ColdFusion application.
  4. Save the new configuration by clicking the save link in the messages box. The Save panel appears. Click Save.
  5. Stop the WebSphere Application Server.
  6. If WebSphere did not delete the cf_root directory, delete it. You might have to restart your computer before you can delete the files.