Accessibility
 
Home / Products / ColdFusion / Support
J2EE Support

Installing ColdFusion MX for J2EE on Mac OS X

Note: With the release of ColdFusion MX 6.1, Macromedia has merged the ColdFusion MX for J2EE edition with ColdFusion MX Enterprise. As a result, the features specific to ColdFusion MX for J2EE are now available with ColdFusion MX Enterprise.


Contents

Overview
Installing, deploying, and configuring ColdFusion MX on JRun 4
Installing, deploying, and configuring ColdFusion MX on Tomcat
Other issues


Overview

This document provides instructions on installing, deploying, and configuring the Developer Edition of ColdFusion MX for J2EE on Mac OS X using either of the following application servers:

The document refers to overview information in the Installing and Using ColdFusion MX for J2EE book, which is copied to the install directory and is also available in the cf_root/cfdocs directory and on LiveDocs.

Note: You must have installed JRun 4 or Tomcat (version 4.1.12 or higher) before installing ColdFusion MX.

The remainder of this document describes ColdFusion MX WAR file deployment and configuration on JRun 4 and Tomcat 4.1.x. Before continuing, you should read the ColdFusion MX for J2EE Release Notes. You should also read at least the first chapter of Installing and Using ColdFusion MX for J2EE.

The Mac OS X operating system is built on top of BSD UNIX. If you haven't used UNIX before, please note the following major differences:

  • The Macintosh Finder hides many common UNIX system directories, such as /opt and /etc.
  • Directories that are hidden to Finder (and other UNIX functionality) can only be accessed through the command line interface. To start the command line interface (also called a command window or command shell), open Finder, go to the Applications > Utilities folder, and double-click on Terminal.

ColdFusion MX, JRun, and Tomcat are all built in Java and require access to the Java 2 Software Development Kit (also called the J2SDK or JDK). Most Macintosh computers running OS X include a JDK and a number of aliases that point to it. For example, you might have a JDK in /System/Library/Frameworks/JavaVM.framework/Versions/1.3.1, referenced by an alias named /Library/Java/Home/. To determine the location of the JDK on your Macintosh, open a command window and type the following command:

locate java | grep bin

Note: Java is case-sensitive.

Conventions in this document

This document uses the following conventions to reference JRun, Tomcat, and ColdFusion directories:

  • cfmx_install_directory - The directory that contains the files extracted by the ColdFusion MX for J2EE installer; for example, /Applications/CFMXJ2ee.
  • jrun_root - The directory that contains JRun; for example, /Applications/jrun4.
  • tomcat_root - The directory that contains Tomcat; for example, /Applications/Jakarta-4.1.18.
  • cf_root - The directory into which you deployed ColdFusion MX; for example, /Applications/jrun4/servers/default/cfusion.

Note: These instructions assume that you are using the web servers that are built into JRun 4 and Tomcat. For information on accessing ColdFusion MX pages through the Apache web server, see Other issues, later in this document.


Back to Contents

 

Installing, deploying, and configuring ColdFusion MX on Mac OS X with JRun 4

To install ColdFusion MX for J2EE on Mac OS X using JRun 4, do the following:

1.
If you have not already done so, install JRun 4. You can purchase JRun or download the Developer version (for the Developer version, select JRun 4 Developer Edition for Mac OS X from the drop-down list box). If you do not intend to install ColdFusion MX on the default JRun server, create a new JRun server to which you will deploy ColdFusion MX.
2. Download the ColdFusion MX for J2EE installer from the Macromedia website (select JRun - Mac OS X from the ColdFusion MX for J2EE drop-down list box).

The download file is named coldfusion-j2ee-java.jar. If your browser renames it to index.cgi or some other name, rename the file to coldfusion-j2ee-java.jar.
3.
Run the ColdFusion MX for J2EE install procedure by double-clicking the coldfusion-j2ee-java.jar file.
Alternatively, you can perform the following procedure to run the coldfusion-j2ee-java.jar installer from a command line:
  1. Open a Terminal window (Applications/Utilities/Terminal).
  2. Use the cd command to navigate to the directory where you downloaded the ColdFusion MX installer.
  3. Use either of the following commands to run the coldfusion-j2ee-java.jar installer. You might have to prefix the java command with the path (or alias) to your JDK bin directory (for example, /Library/Java/Home/bin/java or /System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Commands/java, although you can also specify /usr/java).
    • Graphical installation: java -jar coldfusion-j2ee-java.jar -i gui
    • Text-mode installation: java -jar coldfusion-j2ee-java.jar -i console
4.

Answer the questions and select an install directory. Make a note of this directory; you will need to know it later. When prompted to select EAR file or WAR file, select WAR file.

Note: The default target for the ColdFusion MX installer is the /opt directory, which is not visible through the Macintosh Finder. You might want to change the installation directory to one that is visible through Finder; for example, /Applications/CFMXJ2ee.

5.

If the JRun server to which you are deploying ColdFusion MX is running, stop it. You can stop a JRun server through the JRun Launcher, the JRun Management Console (JMC), or the command line. In most cases, you should use the JRun Launcher, which you run by opening a Terminal window, navigating to the jrun_root/bin directory, and typing ./jrun.

6.
Create a new directory named cfusion under your JRun server instance. This directory will become the web application root (also called context root) into which ColdFusion MX is deployed; for example, if you are installing ColdFusion MX in the default JRun server, the directory might be /Applications/jrun4/servers/default/cfusion.
7.
Create a new directory named CFIDE (all uppercase) under your server instance. This directory will become the web application root into which RDS is deployed; for example, /Applications/jrun4/servers/default/CFIDE.
8.

If you haven't done so already, open a Terminal window (Applications/Utilities/Terminal), navigate to the cfusion directory, and use the jar utility to uncompress the cfusion.war file:

cd jrun_root/jrun4/servers/server_name/cfusion
jar -xvf cfmx_install_directory/cfusion.war

Note: In these instructions, replace jrun_root with the directory in which you installed JRun 4; for example, /Applications/jrun4. Replace server_name with the name of the server to which you are deploying ColdFusion MX; for example, if you installed ColdFusion MX in the default JRun server, specify default.

9.

Navigate to the CFIDE directory and use the jar utility to uncompress the rds.war file:

cd jrun_root/jrun4/servers/server_name/CFIDE (or cd ../CFIDE)
jar -xvf cfmx_install_directory/rds.war

10.
Start the JRun server and monitor startup messages to ensure that ColdFusion MX for J2EE deployed properly. Start the JRun server using the JRun Launcher or by typing jrun_root/bin/jrun start server_name in a command window.
11.

Start the ColdFusion MX Administrator by opening a browser and going to http://hostname:portnumber/cfusion/CFIDE/administrator (for example, http://127.0.0.1:8100/cfusion/CFIDE/administrator). The startup wizard executes the first time you open the Administrator. For more information on the startup wizard, see the Installing and Using ColdFusion MX for J2EE book.

Note: The startup wizard is a pop-up window. To make sure that the wizard appears, disable any software options that prevent your web browser from displaying pop-up windows.

12. Code and test ColdFusion MX CFM pages. Store these pages under the cfusion web application root, as described in the "Using ColdFusion MX Applications
with J2EE Application Servers
" chapter of the Installing and Using ColdFusion MX for J2EE book. You typically access these pages through the built-in JRun web server and use a URL of the form http://hostname:portnumber/cfusion/filename.cfm, as follows:
  • hostname - The machine name, IP address, localhost, or 127.0.0.1.
  • portnumber - The port number of the JRun web server for the JRun server running ColdFusion MX. For example, the default JRun server's web server uses port 8100. If you are not using the default JRun server, you can determine the web server port used by the JRun server by opening the JMC and viewing the home page.
  • filename - The directory path and file to display. The path is relative to the cfusion directory.

For example, to display a CFM file located at /Applications/jrun4/servers/default/cfusion/eisapp/index.cfm, you could specify the URL as http://127.0.0.1:8100/cfusion/eisapp/index.cfm.


Back to Contents

 

Installing, deploying, and configuring ColdFusion MX on Mac OS X with Tomcat 4.1.12 or later

You deploy ColdFusion MX for J2EE on Tomcat using WAR files in conjunction with Tomcat autodeploy.

To install ColdFusion MX for J2EE on Mac OS X using Tomcat, do the following:

1.
If you have not already done so, install Apache Tomcat.
2. Download the ColdFusion MX for J2EE installer from the Macromedia website (select JRun - Mac OS X from the ColdFusion MX for J2EE drop-down list box).

The download file is named coldfusion-j2ee-java.jar. If your browser renames it to index.cgi or some other name, rename the file to coldfusion-j2ee-java.jar.
3.
Run the ColdFusion MX for J2EE install procedure by double-clicking the coldfusion-j2ee-java.jar file.
Alternatively, you can perform the following procedure to run the coldfusion-j2ee-java.jar installer from a command line:
  1. Open a Terminal window (Applications/Utilities/Terminal).
  2. Use the cd command to navigate to the directory where you downloaded the ColdFusion MX installer.
  3. Use either of the following commands to run the coldfusion-j2ee-java.jar installer. You might have to prefix the java command with the path (or alias) to your JDK bin directory (for example, /Library/Java/Home/bin/java or /System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Commands/java, although you can also specify /usr/java).
    • Graphical installation: java -jar coldfusion-j2ee-java.jar -i gui
    • Text-mode installation: java -jar coldfusion-j2ee-java.jar -i console
4.

Answer the questions and select an install directory. Make a note of this directory; you will need to know it later. When prompted to select EAR file or WAR file, select WAR file.

Note: The default target for the ColdFusion MX installer is the /opt directory, which is not visible through the Macintosh Finder. You might want to change the installation directory to one that is visible through Finder; for example, /Applications/CFMXJ2ee.

5.
Stop the Tomcat server to which you will deploy ColdFusion MX. For instructions on stopping the server, see your Tomcat documentation. You typically stop Tomcat by opening a Terminal window, navigating to the tomcat_root/bin directory, and typing the ./shutdown command.
6.
Copy cfusion.war and rds.war to the webapps directory.
7.
Rename rds.war to CFIDE.war (all uppercase).
8.

Start Tomcat server. Tomcat automatically detects the presence of cfusion.war and CFIDE.war, autodeploys them, and creates expanded cfusion and CFIDE subdirectories. The expanded cfusion directory is the web application root (also called context root) for ColdFusion pages; for example, if you are installing ColdFusion MX in the default JRun server, the directory might be /Applications/Jakarta-4.1.18/webapps/cfusion. The expanded CFIDE directory is the web application root for RDS.

For instructions on starting the server, see your Tomcat documentation. You typically start Tomcat by opening a Terminal window, navigating to the tomcat_root/bin directory, and typing the ./startup command.

9.

Stop Tomcat server.

10.

Rename tomcat_root/webapps/cfusion/WEB-INF/cfusion/lib/tools.jar to something else (for example, tools.old).

11.

Create a shell script to establish the JVM options used when starting up Tomcat. Name this file setenv.sh and save it in the tomcat_root/bin directory.

At Tomcat startup, the catalina.sh file automatically calls this file. This file must set JVM options to enable Sandbox Security, cfchart, and CORBA support (CORBA is optional).

# Establish variables. May differ on your installation.
# JAVA_HOME specifies the Java JDK root directory.

# Macintosh OS X maintains a number of aliases for this directory.
JAVA_HOME="/Library/Java/Home"
# CF_HOME specifies the directory to which ColdFusion MX is deployed.
CF_HOME="/Applications/Tomcat/webapps/cfusion"
CF_WEB_INF=$CF_HOME/WEB-INF

# Establish JVM options
CF_SECURITY_JVM_OPTIONS="-Djava.security.manager -Djava.security.policy=$CF_WEB_INF/cfusion/lib/coldfusion.policy -Djava.security.auth.policy=$CF_WEB_INF/cfusion/lib/neo_jaas.policy"
# Set JVM options for CORBA. Use if vbjorb.jar is not in your JRE's
# lib/ext directory.
If used, append $CF_CORBA_JVM_OPTIONS to CF_JVM_OPTIONS
# CF_CORBA_JVM_OPTIONS=-Xbootclasspath/a:"$CF_WEB_INF/lib/vbjorb.jar"
CF_JVM_OPTIONS="$CF_SECURITY_JVM_OPTIONS"

JAVA_OPTS="$CF_JVM_OPTIONS -Xms128m -Xmx256m"

12.

If you deployed the RDS application, you must also set the crossContext attribute to true for the CFIDE web application. You can do this through the Tomcat Administrator or by manually editing the tomcat_install_directory/conf/server.xml file.

To set the crossContext attribute through the Tomcat Administrator, perform the following steps:

  1. Restart Tomcat.
  2. Open the Tomcat Administrator in a browser (http://servername:8080/admin). If you've never used the Administrator, open the tomcat_root/conf/tomcat-users.xml file in a text editor and define a user in the admin role.
  3. Go to Tomcat Server > Service (Tomcat-Standalone) > Host (localhost).
  4. Click on Context (/CFIDE).
  5. Set the Cross Context property to true.
  6. Click Save.
  7. Click Commit Changes.

To set the crossContext attribute by editing the server.xml file, perform the following steps:

  1. Open the tomcat_root/conf/server.xml file in a text editor.
  2. Add the following line under the Engine element:

    <Context className="org.apache.catalina.core.StandardContext"
    cachingAllowed="true" charsetMapperClass="org.apache.catalina.util.CharsetMapper"
    cookies="true" crossContext="true" debug="0" displayName="CFMX RDS Application"
    docBase="tomcat_root/webapps/CFIDE" mapperClass="org.apache.catalina.core.StandardContextMapper"
    path="/CFIDE" privileged="false" reloadable="false" swallowOutput="false"
    useNaming="true" wrapperClass="org.apache.catalina.core.StandardWrapper">
    </Context>

  3. Save and close the server.xml file.
13.

Restart the Tomcat server and monitor startup messages to ensure that all configurations were applied successfully.

14.

Start the ColdFusion MX Administrator by opening a browser and going to http://hostname:portnumber/cfusion/CFIDE/administrator (for example, http://127.0.0.1:8080/cfusion/CFIDE/administrator). The startup wizard executes the first time you open the Administrator. For more information on the startup wizard, see the Installing and Using ColdFusion MX for J2EE book.

Note: The startup wizard is a pop-up window. To make sure that the wizard appears, disable any software options that prevent your web browser from displaying pop-up windows.

15.

Code and test ColdFusion MX CFM pages. Store these pages in the cfusion web application root, as described in the "Using ColdFusion MX Applications
with J2EE Application Servers
" chapter of the Installing and Using ColdFusion MX for J2EE book. You typically access these pages through the built-in Tomcat web server and use a URL of the form http://hostname:portnumber/cfusion/filename.cfm, as follows:

  • hostname - The machine name, IP address, localhost, or 127.0.0.1.
  • portnumber - The port number of the Tomcat web server, typically 8080.
  • filename - The directory path and file to display. The path is relative to the cfusion directory.

For example, to display a CFM file located at /Applications/Jakarta-4.1.18/webapps/cfusion/eisapp/index.cfm, you could specify the URL as http://127.0.0.1:8080/cfusion/eisapp/index.cfm.

Other issues

This section lists issues related to running ColdFusion MX for J2EE on Mac OS X. For a complete list of ColdFusion MX for J2EE known issues, go to http://www.macromedia.com/go/cfmxj2ee-known_issues.

  • Using the directory browser - The version of Internet Explorer that ships with Mac OS X does not support the JavaScript used by the ColdFusion MX Administrator for directory browsing. You must manually specify directory paths.
  • Using the sample applications - When running the ColdFusion MX sample applications, use 127.0.0.1 in the URL instead of localhost. For example, specify http://127.0.0.1:8100/cfusion/cfdocs/exampleapps/index.cfm.
  • Using the Japanese locale - When you start Tomcat with -Duser.language=ja -Duser.region=JP -Duser.country=JP, the getLocale function returns English(US) instead of Japanese.
  • Setting the context root to slash (/) on JRun - By setting the context root to /, you do not have to include cfusion in the URL when accessing CFM pages. To set the context root to /, perform the following steps:
    1. Stop the JRun server that is running ColdFusion MX.
    2. Delete the jrun_root/servers/server_name/default-ear directory and all subdirectories.
    3. Start the JRun server that is running ColdFusion MX.
    4. Make sure the admin JRun server is running.
    5. Start the JMC (http://localhost:8000).
    6. Click on the server in the left pane.
    7. Click on the cfusion Web Application.
    8. Change the context path to / (instead of /cfusion).
    9. Click Apply.
    10. Restart the JRun server that is running ColdFusion MX.
  • Using the Apache web server with JRun - These instructions describe how to access ColdFusion pages through the web servers that are built into JRun and Tomcat. Macintosh OS X also supports the Apache web server. If you want to access ColdFusion pages through Apache when using JRun, you must do the following:
    1. Run the JRun Web Server Configuration tool. When running this tool, you must specify the directory that contains the Apache httpd.conf file (this is typically /etc/httpd). Also, the tool updates the httpd.conf file, so you must have sufficient privileges to modify the httpd.conf file; if not, you must login as the root user.
    2. Check the Macromedia JRun support center to see if there are any patches you should apply.
    3. Store ColdFusion pages in the Apache web root or other Apache mapped directories.
  • ColdFusion MX graphing is not supported with JDK 1.4.1.


Back to Contents