Accessibility
 
Home / Products / ColdFusion / Support
J2EE Support

Installing and Deploying ColdFusion MX 6.1 on Macintosh OS X

The Macintosh OS X operating system is built on top of BSD UNIX, which enables Macintosh users to run software that supports the UNIX platform. Such software includes the Apache web server (included with Macintosh OS X), JRun 4, Tomcat, and ColdFusion MX.

This document describes how to install, deploy, and configure ColdFusion MX as a J2EE application, running on JRun 4 and Tomcat.

About this document

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

Installing, deploying, and configuring ColdFusion MX 6.1 on Mac OS X with Tomcat

Usage notes

About this document

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

  • Macromedia JRun 4
  • Tomcat

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

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

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

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 6.1 Release Notes.

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 Installation Wizard; 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 Usage notes, later in this document.

Comparing Macintosh and UNIX

The Mac OS X operating system is built on top of BSD UNIX. There are several differences between Macintosh and UNIX operating systems:

  • 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 be accessed only through the command line interface.

    To start the command line interface (also called a command window, command shell, or console), open Finder, go to the Applications > Utilities folder, and double-click on Terminal.

ColdFusion MX, JRun, and Tomcat are 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/.

Note: The graphical installation is not available with the 1.4.1 JDK. If your Macintosh is using the 1.4.1 JDK as the default, you must use console-mode installation or specify a fully qualified path to another JDK version when executing the Installation Wizard, as explained in the installation procedures.

To determine the location of the JDK on your Macintosh, open a command window and enter the following command:

locate java | grep bin

Note: Java is case-sensitive.

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

You can deploy ColdFusion MX 6.1 on JRun 4 using either an EAR file or WAR files.

  • EAR file - Deploy ColdFusion MX 6.1 as an enterprise application with the ColdFusion web application located at the context root that you specified in the Installation Wizard. Because EAR deployment automatically manages the context root, it is the recommended option.
  • WAR files - Deploy ColdFusion MX 6.1 as one or more web applications.

The following procedures explain how to run the ColdFusion MX Installation Wizard, how to deploy using WAR files, and how to configure JRun JVM settings for ColdFusion MX.

For information on deploying ColdFusion MX 6.1 as an EAR file, see Installing and Deploying ColdFusion MX 6.1 on Macromedia JRun 4.

Note: If you are updating a currently deployed version of ColdFusion MX on JRun, see the instructions in "Enabling and Using ColdFusion MX Features on Your J2EE Server" before continuing.

To install ColdFusion MX 6.1 on JRun 4:

  1. If you haven't already done so already, 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 plan to install ColdFusion MX on the default JRun server, create a new JRun server to which you will deploy ColdFusion MX.

  2. Download ColdFusion MX 6.1 from the Macromedia website.

    The download file is named coldfusion-61-other.jar. If your browser renames it to index.cgi or some other name, rename the file to coldfusion-61-other.jar.

  3. Run the ColdFusion MX 6.1 installation procedure by double-clicking the coldfusion-61-other.jar file.

    Alternatively, you can perform the following procedure to run the coldfusion-61-other.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-61-other.jar file.
    3. Use either of the following commands to run the Installation Wizard. 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-61-other.jar -i gui (graphical installation is not available with the 1.4.1 JVM)

      Text-mode installation - java -jar coldfusion-61-other.jar -i console

  4. Answer the questions. When prompted, do the following:
    1. Select Enterprise Edition, Developer Edition, Trial, or upgrade, as appropriate.
    2. Select J2EE configuration/WAR file.
    3. Specify the install directory. Make a note of this directory; you will need to know it later.
    4. Specify a password for use with the ColdFusion MX Administrator.

    The Installation Wizard places the WAR files in the install directory.

    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 entering ./jrun.

  6. Create a new directory named cfusion under your JRun server instance.

    This directory becomes 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 becomes the web application root into which the remote development service (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/servername/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 servername 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/servers/servername/CFIDE (or cd ../CFIDE)
    jar -xvf cfmx_install_directory/rds.war
    

  10. Start the JRun server and monitor startup messages to ensure that the ColdFusion MX web application deployed properly.

    You can start the JRun server using the JRun Launcher or by entering jrun_root/bin/jrun start servername 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 Configuration and Settings Migration Wizard executes the first time you open the Administrator.

  12. Code and test ColdFusion MX CFM pages. Store these pages in the ColdFusion web application root directory. For example, to display a CFM file located at jrun_root/servers/default/cfusion/eisapp/index.cfm, you could specify the URL as http://127.0.0.1:8100/cfusion/eisapp/index.cfm.

Installing, deploying, and configuring ColdFusion MX 6.1 on Mac OS X with Tomcat

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

Note: ColdFusion MX 6.1 supports Tomcat version 4.1.12 or later.

To install ColdFusion MX on Mac OS X using Tomcat:

  1. If you haven't done so already, install Apache Tomcat.
  2. Download ColdFusion MX 6.1 from the Macromedia website.

    The download file is named coldfusion-61-other.jar. If your browser renames it to index.cgi or some other name, rename the file to coldfusion-61-other.jar.

  3. Run the ColdFusion MX 6.1 install procedure by double-clicking the coldfusion-61-other.jar file.

    Alternatively, you can perform the following procedure to run the coldfusion-61-other.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-61-other.jar file.
    3. Use either of the following commands to run the Installation Wizard. 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-61-other.jar -i gui (graphical installation is not available with the 1.4.1 JVM)

      Text-mode installation - java -jar coldfusion-61-other.jar -i console

  4. Answer the questions. When prompted, do the following:
    1. Select Enterprise Edition, Developer Edition, Trial, or upgrade, as appropriate.
    2. Select J2EE configuration/WAR file.
    3. Specify the install directory. Make a note of this directory; you will need to know it later.
    4. Specify a password for use with the ColdFusion MX Administrator.

    The Installation Wizard places the WAR files in the install directory.

    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. If your version of Tomcat uses a Java Runtime Environment (JRE) other than 1.4.2, 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. Required if using sandbox security.
    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. Restart the Tomcat server and monitor startup messages to ensure that all configurations were applied successfully.
  13. Start the ColdFusion MX Administrator and run the Configuration and Settings Migration Wizard. You start the Administrator using a URL of the form http://hostname:portnumber/cfusion/CFIDE/administrator/index.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).
  14. Code and test ColdFusion MX (CFM) pages. Store these pages in the cfusion web application root 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.

Usage notes

This section lists issues related to running ColdFusion MX 6.1 on Mac OS X.

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 /:

  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. Ensure that 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 that you should apply.
  3. Store ColdFusion pages in the Apache web root or other Apache mapped directories.

ColdFusion MX graphing

ColdFusion MX graphing is not supported with JDK 1.4.1.

Setting the crossContext attribute to enable RDS on Tomcat

On Tomcat, 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 editing the tomcat_root/conf/server.xml file manually.

To set the crossContext attribute through the Tomcat Administrator:

  1. Restart Tomcat.
  2. Open the Tomcat Administrator (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. Select Tomcat Server > Service (Tomcat-Standalone) > Host (localhost).
  4. Click on Context (/CFIDE).
  5. Set the Cross Context field to true.
  6. Click Save.
  7. Click Commit Changes.

To set the crossContext attribute by editing the server.xml file:

  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="C:/jakarta-tomcat-4.1.12/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.

Undeploying ColdFusion MX

To undeploy ColdFusion MX:

  1. Stop the Tomcat or JRun server.
  2. Make a backup copy of the jrun_root/bin/jvm.config file (JRun) or setenv.sh file (Tomcat).
  3. Open the jrun_root/bin/jvm.config file (JRun) or setenv.sh file (Tomcat) in a text editor and remove all ColdFusion MX specifications.
  4. Delete ColdFusion MX directories, as follows:
    • JRun - jrun_root/servers/servername/cfusion and jrun_root/servers/servername/CFIDE.
    • Tomcat - tomcat_root/webapps/cfusion and tomcat_root/webapps/CFIDE.
  5. Restart Tomcat or JRun.