with ColdFusion 5, MX, and BlueDragon with ColdFusion 5, MX

app servers
Setting Up Your
Development
Server
with ColdFusion 5,
MX, and BlueDragon
Browse code in your webroot and serve it via all three app
servers just by changing the virtual directory in your URL
T
he world of ColdFusion application servers is quite
interesting at the moment. Macromedia’s recent
update to CFMX 6.1 promises to add a lot of stability
and speed to the product. BlueDragon, New Atlanta’s alternate
CFML runtime engine continues to gain momentum. Yet
despite these two great products, much of the development out there is still based on ColdFusion 5 (or earlier).
What if you’re interested in running one or more of
these at once? Perhaps you’re going to upgrade an
app from one server to another? How do you test your
current applications for compatibility among the
other servers without reconfiguring your development machine? If you’re a consultant, or work for a
consulting firm, there’s a good chance you’ll have
multiple clients, each with different server requirements. How do you handle the changing requirements without reconfiguring your server every time?
The good news is that you can install all three products at once to test them, but they each support slightly
different versions of CFML. How do you set things up so
that you can test a set of CFML templates against each
server, while keeping the CFML code in one place?
28
CFDJ SEPTEMBER 2003
This article answers those questions by showing you how to
run all the application servers off of a single instance of Microsoft
IIS 5 on Windows 2000, and will make it easy to test for cross-compatibility in your code. Normally, if you set up a ColdFusion (or
BlueDragon) server to use IIS, it will replace any prior IIS settings
for running CFML templates. We’ll show you how to resolve that.
Even if you use Apache, iPlanet, IIS on a Windows Server
edition, or some other external Web server, the concepts here
will generally apply (though they may be even
more flexible). If you already have CF5, CFMX, or
BlueDragon installed, just follow along to learn a
couple of interesting points to enable setup of IIS
to run all three servers at once, pointing to the
same directory of CFML code. It’s a great way to do
testing against all three servers.
Installing/Configuring ColdFusion 5
By Jeffry Houser
By Charlie Arehart
The first step is to install and configure ColdFusion
5 on your machine. If you already have it installed
and configured to use IIS, you can skip to the next
paragraph. ColdFusion 5 can currently be downloaded from the Macromedia Web site, at
http://download.macromedia.com/pub/coldfu
sion/esd/coldfusion-50-win-us_devrel.exe. It can also
be found on your ColdFusion Studio 5 CD or included
in Ben Forta’s CF5 Web Application Construction Kit
book and others. Install it to the default directory,
C:\Cfusion. During the install process you should let
the installer set itself up for IIS.
ColdFusionJournal.com
You can test the success of your installation by running the
ColdFusion Administrator (such as http://localhost/cfide/
administrator/index.cfm) or by creating and running a page
using the code below:
<cfoutput>
Level: #Server.ColdFusion.ProductLevel#<br>
Name #Server.ColdFusion.ProductName#<br>
Version #Server.ColdFusion.ProductVersion#<br>
</cfoutput>
Save the page in your IIS webroot (\inetpub\wwwroot\),
perhaps as cfversion.cfm, and load the page in your browser
with http://localhost/cfversion.cfm. You’ll see that the product
version is 5,0,0,0, the name is ColdFusion Server, and the level
is either Professional or Enterprise.
The install process will create two mappings in IIS, one for
cfm pages and one for dbm pages. To see these, open up your
Internet Services Manager (found at Start-->Settings->Control Panel-->Administrative Tools), right-click on the
Default Web Site, and choose Properties. Click on Home
Directory and Configuration. (If the Configuration button is
not selectable, close that window and right-click on the computer name above the Default Web Site, choose Properties,
choose Edit for the Master Properties of the WWW Service,
then choose Home Directory and Configuration.) You should
see a cfm extension mapping listed on the app mappings tab,
like that shown in Figure 1.
Figure 1
PAPERTHIN
www.paperthin.com
ColdFusionJournal.com
SEPTEMBER 2003 CFDJ
29
app servers
The mapping should point to “C:\Cfusion\BIN\ISCF.DLL”.
That’s the name of CF5’s IIS adapter. We’re next going to install
CFMX and eventually cause it to overwrite this IIS configuration for CF 5, so you should write down the mapping information as you’ll need it later.
You’ll also want to make backup copies of the ColdFusion 5
Administrator (cfide) and documentation (cfdocs) directories
that were installed by default in the IIS webroot
(\inetpub\wwwroot), as they will also be overwritten in a later
step. A simple way to do this is by renaming them to cfide5
and cfdocs5. We’ll show you how to make them accessible
again later.
Click the add button and you’ll see the screen shown in
Figure 3.
Installing/Configuring ColdFusion MX
Our next step will be to install/configure ColdFusion MX. If
you already have it installed and configured to use its built-in
Web server, you can skip the next two paragraphs. If you are
already configured to use IIS, skip to the next subsection, “you
are checking the IIS Configuration for CFMX”.
You can download the latest version of ColdFusion MX
from the Macromedia Web site, at www.macromedia.com/
software/coldfusion/trial. ColdFusion MX will install into the
CFusionMX directory by default. Just be sure not to install into
the same directory as your ColdFusion 5 installation.
In fact, the installer will detect that ColdFusion 5 is
already installed. Tell it you want it to coexist and install
ColdFusion MX using its built-in Web server. You could tell it
during the install to implement its IIS connection, but we
want the article to help those who may have already installed
CFMX with its built-in Web server, who will want to follow
the next steps.
Once the installation is done, you can confirm that the
installation was successful by running the CFMX
Administrator. By default, CFMX will set up its built-in Web
server at port 8500, so the URL would be http://localhost:
8500/cfide/administrator/index.cfm.
Next, or if you had previously installed CFMX using its
built-in Web server, we will want to manually set up CFMX to
work via IIS. Using Windows Explorer or My Computer, look in
the C:\CfusionMX\runtime\lib directory and double click on
wsconfig.jar. (In CFMX 6.1, there is also a new menu option,
Start-->Programs-->Macromedia-->Macromedia ColdFusion
MX-->Web Server Configuration Tool.) The screen shown in
Figure 2 will come up.
Figure 2
30
CFDJ SEPTEMBER 2003
Figure 3
If you find that you can’t launch the JAR file (such as if it
tries to open it like a ZIP file), or if it doesn’t work for any other
reason, look at the CFMX documentation, Installing
ColdFusion MX and its section, “Configuring Web Servers” in
Chapter 2.
Assuming things are working for you as shown in the figures, select your IIS Web site, click the Configure Web Server
for ColdFusion MX Applications button and then click OK. You
will be asked to restart the Web server.
Checking the IIS Configuration for CFMX
The ColdFusion MX mappings are now created on IIS. As
was described in the CF5 step, open up your Internet Services
Manager and bring up properties on the Default Web Site (or
the Master Properties, if necessary). Click on Home Directory
and Configuration. You should see a bunch of mappings,
including cfm and cfc, listed on the app mappings tab, similar
to the one shown in Figure 4.
You’ll also see jsp, jws, and cfml mappings listed. The mappings probably point to “C:\CFusionMX\runtime\lib\
wsconfig\1\jrun.dll”. Write down this value to use in a later
step. Take note, as well, that CFMX’s installation of the IIS
adapter actually builds the file named in that mapping. It’s not
enough to skip this step and just use the aforementioned DLL
name in the later step.
You can run the CF Admin or our test code from above to
verify that IIS is now sending pages to ColdFusion MX. In
either case, you’d no longer want to use the port 8500 on the
URL to test against CFMX. Instead, use the same URL you
used above to test CF5. The Product Name is still ColdFusion
Server, the Product Level should still be Enterprise or
ColdFusionJournal.com
5 mappings from IIS, but don’t worry about that for now. We’ll
show you shortly how to reactivate ColdFusion 5 via IIS.
Note that the earlier installation of CFMX (using the built-in
Web server) installed the CFMX documentation and
Administrator in the “C:\CFusionMX\wwwroot”. If you want to
be able to easily access these by way of IIS, you will need to
copy the ColdFusion MX Administrator (cfide) and documentation (cfdocs) directories into the IIS Web root
“C:\inetput\wwwroot”. This is why we had you rename those
directories when they had been installed with CF5.
Installing/Configuring BlueDragon
Figure 4
Professional (or may now be Standard, in CFMX 6.1). The version should start with “6” and be something like 6,1,0,63239.
Again, installing ColdFusion MX has removed your ColdFusion
Finally, we want to install BlueDragon Server. Even if you
don’t know about it, there’s no harm in installing it. It can run
alongside both CF5 and CFMX. In simplest terms it’s just
another server for running your CFML, as you will see. You can
learn more about it, including other benefits and features, at
www.newatlanta.com/bluedragon/.
Installing BlueDragon Server is easy. It’s downloadable from
the New Atlanta Web site. Get the Server JX version, which like
CF is available as a 30-day, full-featured trial that reverts to a
single-IP developer edition after that. There is also a Server version, which is free for both development and deployment, without a time limit (though not free for redistribution). It lacks a
few features available in the BlueDragon Server JX (and
BlueDragon/J2EE) edition, but is much more full-featured than
was the previous free edition of ColdFusion from Allaire in the
4.5 timeframe, called CF Express.
FUSETALK
www.fusetalk.com
ColdFusionJournal.com
SEPTEMBER 2003 CFDJ
31
app servers
While you can install BlueDragon into its default directory
(C:\Program Files\New Atlanta\BlueDragon_Server), for the
purposes of this article it may be preferable to install it instead
to a C:\Bdragon directory, for reasons explained later. And
again, let’s install BlueDragon using its built-in Web server, just
as you did for ColdFusion MX. If you already installed it in its
default directory, don’t worry. We’ll explain this issue later.
It’s worth noting that like CF, you could instead have
installed BlueDragon to integrate with IIS (or other Web servers
like Apache and IPlanet). You could also easily add IIS integration after installing it using the BlueDragon Administrator. For
the purposes of this article, we’ll instead be manually setting
up IIS to connect to BlueDragon. Indeed, we’ll create a special
virtual directory for each server in the next section.
You can confirm that BlueDragon is working by running its
Administrator. It’s accessible only by using the BlueDragon builtin Web server, which by default would be available at
http://localhost:8080/bluedragon/admin.cfm. (Unlike CF, for
security reasons the BlueDragon Administrator is accessible only
from the localhost, from the machine on which it was installed.
Therefore, even if you had installed it with IIS, or later configured
it to use IIS, there’s no point in trying to copy the admin to the
IIS webroot as we did with CFMX.)
You are now ready to start configuring IIS.
Configure IIS
Let’s take stock of what you’ve done to your machine thus
far. ColdFusion 5, ColdFusion MX, and BlueDragon are
installed. Only ColdFusion MX is set up to run using IIS. All
CFML templates in all directories run though IIS will execute
by way of CFMX. BlueDragon will run only in stand-alone
mode using its built-in Web server. ColdFusion 5 won’t work at
all because its mappings were replaced by ColdFusion MX. We
now want to accomplish our goal of having everything run off
of our single instance of IIS, pointing to the inetpub/webroot.
The solution is to create virtual directories for each server
that point to the webroot, but run the templates through the
desired CFML server. The key is in those extension mappings
that we referred to before. In fact, we can create different virtual
directories that each use a different mapping for CFML templates. You can do this from the Internet Services Manager.
Follow these instructions:
1. Right-click on the Default Web Site and select Virtual
Directory from the New menu.
2. Name the first virtual directory something like CF5. When
asked to enter the path containing the Web content, use the
available Browse button to point to inetpub\wwwroot. Now
the virtual directory is created.
3. Bring up that new virtual directory’s properties by rightclicking it and selecting Properties. Click on the
Configuration button on the virtual directory tab. It will
probably have inherited mappings (for the .cfm and .cfml
extensions) that point to the ColdFusion MX IIS DLL,
because CFMX was configured to use IIS integration in that
previous CFMX install step. We will want to override this
mapping. Change the cfm and cfml mappings to point to
C:\Cfusion\BIN\ISCF.DLL, the value you wrote down earlier in this article during the CF5 setup.
32
CFDJ SEPTEMBER 2003
Figure 5
4. Now, templates executed with the new /CF5 URL will execute via CF5 instead. You can confirm that your new setup
is working by using the URL http://localhost/CF5/ to run
some CFML templates in the inetpub\wwwroot. If you followed the recommendation of renaming the CFDOCS
directory that had been installed with CF5, the URL would
now be http://localhost/cf5/cfdocs5/dochome.htm. The
CF5 Administrator would be http://localhost/cf5/cfide5/
administrator/index.cfm. Admittedly, not all the images will
work correctly and some links may not work as expected,
but at least it’s better than having lost the CF 5 Admin and
docs if we’d installed CFMX directly to the IIS webroot and
had overwritten them entirely.
Now, what about CFMX? Though it’s already set up to serve
docs in the webroot, you may want to create another virtual
directory, named CFMX, to parallel what you did for CF5. You
can follow steps similar to those above to create a virtual
directory named CFMX, using the CFMX version of the IIS
DLL mappings we had taken note of earlier.
The final step is to create a BD virtual directory. Again, use
the same steps above, but in this case the DLL file we want to
point the cfm mappings to is located in that BDragon directory we installed it to, at C:\BDragon\bin\isapi\BlueDragon_
Adapter.dll, as shown in Figure 5.
Now we can explain why we chose to install BlueDragon to
a BDragon directory rather than Program Files\New Atlanta.
It’s due to a limitation in the IIS Internet Services Manager
dialogue we’ve been using for associating a DLL to an extension mapping. The problem is that it will not accept a directory path containing spaces.
This wouldn’t be an issue if we were to choose IIS integration
at installation of BlueDragon, or if we selected it afterward using
ColdFusionJournal.com
the BlueDragon Administrator. In those cases, BlueDragon uses
a programmatic API to set the extension mapping and the path
to its DLL, where the spaces don’t matter.
If you’ve already installed BlueDragon and want to try this
manual approach to setting up a new virtual directory, and
you don’t want to reinstall BlueDragon, you can still point to
your existing directory here. You’ll just have to convert the
path to the Windows 8.3 format. On our test machine, that
path name would be C:\Progra~1\NewAtl~1\BlueDr~1\
bin\isapi\BlueDragon_Adapter.dll. This will vary on your
machine depending on other directories you may have in the
Program Files or New Atlanta directories. If you’re comfortable
using the DOS command line, you can determine the 8.3
name for a given path using the DIR command’s /X switch.
Finally, note that unlike CFMX, we did not need to install
the IIS adapter in order to use that BlueDragon_Adapter.dll. As
in CF5, it’s simply placed there automatically during the install
process along with all the other external Web server adapters.
Conclusion
Now you can browse code in your webroot and serve it via
all three application servers just by changing the virtual directory in your URL.
• Localhost/cf5 will send code to the ColdFusion 5 server.
• localhost/cfmx will send code to the ColdFusion MX server.
• localhost/bd will send code to the BlueDragon server.
And notice that while we’ve created the virtual directories
to point to the IIS webroot, you could just as easily create
three sets of virtual directories to point to another content
directory outside the webroot.
Maybe someone out there would like to take this concept and
extend it to offer similar instructions for doing this in Apache,
iPlanet, or IIS 6 on Windows Server 2003. Again, the concepts are
similar, and sometimes even easier on those Web servers.
In any case, for those on IIS, jumping between projects,
clients, and application servers just became much easier.
About the Authors
Jeffry Houser has been working with computers for over 20
years and has been working in Web development for over 8
years. He owns a consulting company based in Connecticut,
and has authored three separate books on ColdFusion, most
recently ColdFusion MX: The Complete Reference (McGrawHill Osborne Media).
jeff@instantcoldfusion.com
Charlie Arehart is co-technical editor of ColdFusion
Developer’s Journal and a Macromedia Certified Advanced
ColdFusion developer and trainer. He has recently become CTO
of New Atlanta Communications, makers of BlueDragon. In his
new role, he will continue to support the CFML community,
contributing to several CF resources, and speaking frequently at
user groups throughout the country.
charlie@newatlanta.com
CRYSTALTECH
www.crystaltech.com
ColdFusionJournal.com
SEPTEMBER 2003 CFDJ
33