coldfusion 9

Multihoming with Multiple Instance ColdFusion 9 with Apache 2 on Mac OS X

Multiple Instance ColdFusion has a number of advantages that reach beyond the obvious benefits to a large scale, high traffic, production server farm.  As a consultant, I have multiple clients and some clients have multiple web sites and web apps.  My clients aren't related, so why should I configure a single local instance of CF to handle all of their apps and web sites? That would be a configuration headache since with a single instance, you also have a single CF administrator.  Suppose one client uses CF sessions and other uses JSessions and for whatever reason, that cannot change. If you're anything like me, you're jumping from client to client and can't be worrying about logging into you local CF admin and resetting it to mirror that client's environment. Enter multiple instance ColdFusion...


I'm writing this entry because I found the documentation on configuring and managing multiple instances -at times - confusing, lacking, or not what I needed at the time.  In the end it turns out to be fast, simple, and as user friendly as a server administrator could really ask for.

Download and Install ColdFusion

This might seem like a useless sections but if you've never installed the multi-instance version, you might wonder why you can't find it easily. It's just the developer edition - nothing special. Just choose multiple instance when you step through the wizard.

Visit Adobe's ColdFusion Web site to get the latest version (9 as of this writing).

I grabbed the 64 bit version for Mac OSX.

Here are the screen shots for the most relevant wizard screens during installation.

Assuming all went well, you now have a single instance of a multiple instance ColdFusion server installed. Unlike the the standard single instance install, the URL of this one is not localhost:8500, but rather localhost:8300.

New Server Address

After the installation is complete, you have one instance name cfusion that serves as the primary administrative instance on your computer. The cfusion instance is like the single instance you may be used to except it can do more (like create and manage other instances).

The administrator is located at a new address:


New Server Location

If you chose the default parameters during installation, your JRun server is located in /Applications/JRun4. In the JRun4 directory, you will find the servers directory and inside that, you will find a cfusion directory (/Applications/JRun4/servers/cfusion).

Each time you create an instance using the cfusion administrator, it will end up in the servers directory, unless you explicitly tell it otherwise. The reason: ColdFusion is actually just a J2EE Web Application deployed to a servlet container - in this case, JRun4. In future releases of ColdFusion, Tomcat will be used in place of JRun.

Server Directory Layout

The layout of the directory is slightly different than that of a single instance.

Document Root: /Applications/JRun4/servers/cfusion/cfusion-ear/cfusion-war

When ColdFusion is installed in multiple instance configuration, each instance is created and deployed as an EAR file. An EAR file is an Enterprise ARchive file that contains one or more J2EE modules along with instructions for how the modules are to be deployed. We are interested in the document root, CFIDE, and WEB-INF.

Creating an Instance

Let's create a new instance using the cfusion administrator. It will serve as a template for new instances when they are created. By default, when a new instance is created, the settings from the cfusion instance are copied to the new instance. This includes data sources and mappings.  I've experienced a mix of results with this so be sure each instance is configured how you want.  A benefit of multiple instances is that you can have different settings so this might not be what you want anyway.

Open the cfusion administration page and click Instance Manager under the Enterprise Manager menu option on the left.

This page lists all instances that you have installed and on which port they run whether or not they are running now.

Click New Instance and give your instance a name. As you can see, you can point to an EAR or WAR file but we'll let the administrator create the instance for us so leave that blank.

Click Submit.

After the instance is created, you can view the list of servers and see your new instance.

Notice that the instance may not be started by default. If not you'll have to start it manually. Also note the port, 8301. Each instance is assigned the next available port beginning at port 8300. Since the cfusion instance run on 8300, the next available port is 8301.

NOTE: If you have a server running on ports 8301, 8302, and 8303 and the delete the server on port 8302, the next available becomes 8302. As such, the next instance will be assigned this port.

The administrator URL for your new server is http://localhost:8301/CFIDE/administrator/index.cfm

The document root of your new server (assuming you also named your server 'bar') will be /Applications/JRun4/servers/bar/cfusion.ear/cfusion.war

Apache Web Server Connector

Normally, users aren't hitting your ColdFusion server directly. Under typical use, a web server hands requests for ColdFusion pages off to the ColdFusion server and requests for other types files are handed off to some other application server.

Start apache by running:

sudo /usr/sbin/apachectl start

Start the web server configuration tools that ships with ColdFusion by running the following command:

sudo java -jar /Applications/JRun4/lib/wsconfig.jar

Click Add...

Select the instance you want to connect and specify the location of Apache's httpd.conf file. In my case, I'm using Mac's built-in apache web server.

Be sure to check Configure web server for ColdFusion 9 applications.

Click OK and you will see a message to restart apache. Click Yes and your Web server will be connected to your new instance of ColdFusion. All connected instances will be listed in the Configured Web Servers dialog box. Close the dialog box.

Now we test the Web server and the ColdFusion instance to be sure it all worked.

Test Apache

Once apache has been restarted, it will be configured to hand off ColdFusion requests to your new instance. To test apache, we'll put a sample HTML file in the document root of the Web server. For me, that is located in /Library/WebServer/Documents.

All I'll do is change the text in index.html.en to Hello from Apache2!. Since Apache is configured to look for .html files before .cfm files, this will be served when the root directory is requested.

Test that the Web server serves this by going to http://localhost/

Test ColdFusion Instance

To test that your ColdFusion pages are being served properly, add an index.cfm file to your instance's root. Recall, this is /Applications/JRun4/servers/bar/cfusion.ear/cfusion.war

View the page at http://localhost/index.cfm and you'll see the ColdFusion page.

Configuring Apache for Multihoming to Multiple ColdFusion Instances

Perhaps the most necessary piece of understanding is how to specify which ColdFusion instance handless requests for particular ColdFusion page. With multiple ColdFusion servers, how to we know which server to direct to?

Create a New Instance

Create a new ColdFusion instance named foo and create a directory of the root named "my-resource-killer-app" and place in it, an index.cfm file.

Test that you can see the page before continuing.

Notice that the port number of this instance is 8302 (the next available from 8300).

Configure Apache

You can't use the Web server configuration tool to link this new instance since the purpose of the wsconfig.jar program is to connect a Web server - we already have one connected. We need to manually edit the configuration file to get it to talk to the new instance sometime and the old instance (bar) other times.

sudo emacs /etc/apache2/httpd.conf

Look for the following section:

This is part of the configuration that the tool added when we ran the Web server configuration tool. It tells Apache to hand off requests for .jsp .jws .cfm .cfml .cfc .cfr .cfswf files to the JRun server.

Note the following line:

JRunConfig Bootstrap

This is the location of the connection between the Web server and the ColdFusion instance. We need to know the location of the new instance (foo) that we can use it in our next step. To find it, we'll need to take a look a the JRun Administrator.

Start the JRun Admin web App

Run the following command to open the JRun instance launcher:


Notice the admin JRun server (not running) on port 8000. Click on it and click start.

Go to the admin app in your browser:


The user name is admin and the password is the same password you've been using to log into all your ColdFusion administrators.

We are interested in the Proxy Port column here. Note our bar instance is running on proxy port 51000.  Equally important, our new foo instance is on proxy port 51002.

Remember that port.

Note: If for some reason, the proxy service is running, your Web server will not be able to connect to your instance so double check that it is in fact running by clicking on Services under the bar instance on the left side navigation. Ensure that the ProxyService is running. If it's not, start it.

Return to your Apache configuration file and make three changes...

Comment out two lines from the configuration shapshot shown above

uncomment the following line:

Modify the following <Directory> directive.

Open the httpd-vhosts.conf file for editing.

sudo emacs /etc/apache2/extra/httpd-vhosts.conf

You'll need to configure a Virtual Server (virtual host) for each instance that will be handling requests from this Apach server.

Change the Virtual Hosts section to something like what I have below. Use the values that that appropriate for your configuration - obviously.

Notice that all requests for ColdFusion resources at killerapp.localhost will be handled by the foo instance and all requests for ColdFusion resources at localhost will be handled by the bar instance.

Also notice that the proxyport 51002 is set for foo. BE SURE THE PROXY IS RUNNING!

Modify Hosts File

Before we can test this on our computer, we have to modify the hosts file so that the address killerapp.localhost will loop back to for our apache Web server to handle. This is only necessary when you aren't running your own DNS server. Which, if you are - very cool, nerd.


Now that you're all configured, test both URLs.

First, the standard localhost address that we changed to a virtual host.

Next, the killerapp.localhost that points to foo.

Wrap Up

Being able to isolate Web sites or even Web apps allows us several advantages. Since each instance runs as a single server, the server can be tweaked to perform optimally just for that site or application.  Moreover, applications and sites no longer need to run on the same physical machine or virtual machine. This overcomes limitations like memory, processor core allocation and disk space.

Our example offloaded a resource intensive ColdFusion application to a new server (bar) so the rest of the site wouldn't be affected by requests to the app. This is very typical but it doesn't have to be just an app. Entire sites, can be treated this way. For example the following fictitious sites can all be severed from the same Web server but reside on separate physical instances of ColdFusion:


Multihoming is a popular configuration for serving ColdFusion pages from multiple instances. I don't run this configuration on my local development machine but it is something that clients may require and a solid understanding of what's going on under the hood is always a good basis to pitch your ideas to a client. Problems pop up along any step and being able to overcome them is rooted in logic. We're developers, that's how we think anyway :)

Hope this helps.