Home / Developer Center / ColdFusion Developer Center /

ColdFusion Article

Installing and Configuring ColdFusion MX 6.1 Multiple Instances with IIS and Apache Virtual Hosts

Brandon Purcell

This article explains the process of creating multiple instances with ColdFusion MX 6.1 Enterprise and configuring multiple instances to both Microsoft Internet Information Services (IIS) and Apache using virtual hosts. By running ColdFusion in multiple instances instead of a single instance on a single machine, you can:

Isolate applications to ensure high availability.
Isolate applications for security.
Fine-tune each website with its ColdFusion server instance.

For more details on advantages of using multiple instances, read my article, Advantages for Using Multiple Instances for ColdFusion MX and Tim Buntel's article, Introducing Multiple Server Instances in ColdFusion MX Enterprise 6.1.

Now that you know why you should use multiple instances, the question is: How do you do it? In this article, I outline a step-by-step process—installing ColdFusionMX 6.1, creating new instances of JRun, deploying ColdFusion to the new instances, and configuring each new instance to the external web server.

Requirements

To complete this tutorial you will need to install the following software and files:

ColdFusion

Additional information:

To best illustrate configuring multiple instances, you will configure two instances of ColdFusion and connect these instances to three sites in IIS and three Apache virtual hosts. Figure 1 demonstrates the configuration you will use with Apache. Virtual Host 1 will have its own ColdFusion instance while Virtual Hosts 2 and 3 will share the second ColdFusion instance. This approach gives mission-critical sites their own instances, while a site with less traffic shares instance with other virtual hosts. Figure 2 shows the same model using IIS.

Figure 1. Three Apache virtual hosts connected to two instances of ColdFusion

Figure 2. Three IIS sites connected to two instances of ColdFusion

Installing ColdFusion MX 6.1 Enterprise with the J2EE Configuration

In this section, you will install ColdFusion MX 6.1 with the J2EE configuration, which includes a full version of JRun 4. If you have only used the Server configuration (see Figure 3) in the past, then this approach will be somewhat different for you. The J2EE configuration gives you the flexibility of both multiple instances and clustering.

Install ColdFusion MX 6.1 with the J2EE Configuration (ColdFusion MX with JRun 4).

Figure 3. Selecting your install configuration in the Installation Wizard
During the install process, select the Built-in web server.

Figure 4. In the Installation Wizard, choose the Built-in web server.
Follow the Installation Wizard prompts.
When the Installation Wizard finishes, launch the Configuration Wizard and enter your ColdFusion Administrator password; follow the prompts to complete the install.
On Windows, the wizards install five different services:
1. ColdFusion MX ODBC Agent (from the Configuration Wizard)
2. ColdFusion MX ODBC Server (from the Configuration Wizard)
3. Macromedia JRun Admin Server - JRun Management Console (JMC) at http://127.0.0.1:8000/ (from the Configuration Wizard)
4. Macromedia JRun CFusion Server - ColdFusion Server (from the Installation Wizard)
5. Macromedia JRun Default Server - Default JRun Server (from the Installation Wizard)
Only services a, b, d are necessary for ColdFusion MX to run; you can shut down the JMC (JRun Management Console) and Default server unless you need to use the JMC to administer JRun.
On Unix, you can use the following commands to start and stop the JRun servers:
1. /jrun4/bin/jrun -nohup -start <servername>
2. /jrun4/binjrun -stop <servername>
3. /jrun4/bin/jrun -nohup -start cfusion

Creating Multiple Instances of ColdFusion

In this section, you will configure multiple instances by creating new instances of JRun and deploying ColdFusion to each new instance.

Stop the cfusion server from the command prompt or in the Windows Services control panel.
Copy the cfusion-ear directory from the cfusion server in C:\JRun4\servers\cfusion\cfusion-ear\ to a location of your choosing. In this example I chose C:\working\cfusion-template. You will use these files when you create new instances of ColdFusion MX. As you create new instances, you will copy the entire folder to the server root of the new instance.
Start cfusion server through the Windows Services control panel or from the command line.
Create a new JRun server or instance of JRun and deploy ColdFusion MX to it. To create the new JRun server, you must have JRun admin server running. You can start the process in the control panel or from the command line with the following command:
{jrun4}\bin\jrun -start admin
Open a web browser and type the following URL to access the JMC: http://<host>:8000/.
After logging into the JMC with the username and password that you specified in the ColdFusion MX installation, click Create New Server, at the top of the JMC.
Type a name for the JRun server; in this example I used cfusion2; next, click the Create Server button.

Figure 5. Creating a new server in the JMC
Choose the ports for the server (Figure 6). Specify a JNDI port in the range of 2900-3000; you can specify any port for the Web Server Port Number or Proxy Port Number. In this example, I chose the default values:

Figure 6. Choosing the ports for the new JRun server in the JMC
Now that you have created a new JRun server, you can add it as a service on Windows; if you are on Unix, you will start JRun from the command line. To add the server as a service, use the jrunsvc command. For information on the jrunsvc command type:

c:\jrun4\bin\jrunsvc ?

To add the server as a service type the following command:

C:\JRun4\bin>jrunsvc -install cfusion2 "Macromedia JRun CFusion2 Server" "Macromedia JRun CFusion2 Server"

The following message appears if the command succeeds:

Service "Macromedia JRun CFusion2 Server" installed with display name "Macromedia JRun CFusion2 Server"
Copy the cfusion-ear directory from the temporary location you copied them to earlier to the server root for the new server you just created. In this example, I copy the files from C:\working\cfusion-template\cfusion-ear to C:\JRun4\servers\cfusion2\cfusion-ear.
Start cfusion2 (or your new server name) server through the Services control panel or from the command line.
Delete the default-ear from the newly created JRun server. Since both cfusion-ear and default-ear have a context root of /, they will conflict; therefore, you must delete the default-ear. I deleted mine from C:\JRun4\serves\cfusion2\default-ear. You must also undeploy the flashgateway.ear included with JRun so that it does not conflict with the gateway that is packaged with ColdFusion. To undeploy the flashgateway.ear, click the server name in the left frame of the JMC. Click J2EE components, then click "X" next to the Flash Remoting EAR.
You have now successfully created two instances of ColdFusion. For each additional instance, follow steps 4–13 each time you want to create a new server.

Note: In some cases you may want to have individual settings for each instance. For example, perhaps you want to configure the first instance with a maximum JVM heap of 512MB, and you want to have 256MB for the second instance. Or maybe you want to configure a different classpath for each instance. By default, this is not possible; you must create different jvm.config files for each instance and follow the instructions in TechNote 18206: JRun 4.0: Configuring Individual JVM Settings for each JRun Server to configure different JVM configurations.

Web Server Configuration Apache and IIS

For the web server configurations, you will find detailed instructions on configuring both Apache and IIS to ColdFusion MX 6.1 below. In the Apache configuration, you will use virtual hosts to configure multiple sites to multiple ColdFusion instances (see Figure 7). With the Apache configuration, you use wsconfig GUI to configure Apache to a single ColdFusion instance. Then, you will manually configure each of the virtual hosts to the appropriate ColdFusion instance. With IIS, you will configure each site in IIS and then you will use the wsconfig GUI to configure each individual site to the appropriate ColdFusion instance.

Apache Configuration

In this section, you will configure three virtual hosts in Apache to the two instances of ColdFusion that you created earlier (see Figure 7).

Figure 7. Three Apache virtual hosts connected to two instances of ColdFusion

Configure Apache with three virtual hosts, each with its own doc root. The example below shows my configuration from httpd.conf. You can find more details in the Apache documentation. The following is the Apache httpd.conf file, configured with three virtual hosts:

NameVirtualHost * 
<VirtualHost *>
ServerAdmin webmaster@site1.com
DocumentRoot "C:/appservers/Apache/Apache2/htdocs2"
ServerName www.site1.com 
ErrorLog logs/site1-error_log
</VirtualHost>
<VirtualHost *>
ServerAdmin 
webmaster@site2.com
DocumentRoot "C:/appservers/Apache/Apache2/htdocs3"
ServerName www.site2.com 
ErrorLog logs/site2-error_log
</VirtualHost>
<VirtualHost *>
ServerAdmin webmaster@site3.com
DocumentRoot "C:/appservers/Apache/Apache2/htdocs4"
ServerName www.site3.com 
ErrorLog logs/site3-error_log
</VirtualHost>

After configuring your virtual hosts, place an HTML page in each doc root and verify that it works properly.
With the IIS configuration instructions below, you can use the wsconfig GUI to configure the external web server. Many times, Unix users using Apache will not have access to a wsconfig GUI; therefore, I use the command line version of wsconfig below. In this step, you will configure Apache to the cfusion server. If you are running in an environment where you have a wsconfig GUI, you have the option of performing these steps with the wsconfig GUI version of wsconfig.

The following command uses the wsconfig.jar to configure Apache to work with the cfusion server (The changed httpd.conf file is below the command.):
```
C:\>C:\JRun4\runtime\jre\bin\java -jar C:\JRun4\lib\wsconfig.jar -host 127.0.0.1 -server cfusion -ws Apache -dir 
C:\appservers\Apache\Apache2\conf -norestart -map .cfm,.cfc,.cfml -coldfusion -v
```
The following shows the JRun Container Directive in the configured httpd.conf:
```
# JRun Settings
LoadModule jrun_module "C:/JRun4/lib/wsconfig/1/mod_jrun20.so"
<IfModule mod_jrun20.c>
JRunConfig Verbose false
JRunConfig Apialloc false
JRunConfig Ssl false
JRunConfig Ignoresuffixmap false
JRunConfig Serverstore "C:/JRun4/lib/wsconfig/1/jrunserver.store"
JRunConfig Bootstrap 127.0.0.1:51005
#JRunConfig Errorurl # <optionally redirect to this URL on errors>
AddHandler jrun-handler .jsp .jws .cfm .cfml .cfc
</IfModule> 
```
Restart Apache, then copy a ColdFusion CFML file to each of the virtual hosts' DocumentRoot directories and invoke them through a browser to verify that the connector installed properly. When you request the test page through a browser, the server should execute the CFML page and display it in your browser; if you see the CFML source in the browser instead, or your browser prompts you to download a CFML file, it is not configured correctly. Make sure you restart the server after modifying the httpd.conf before testing. At this point, you have configured Apache at the global level, any Virtual Hosts inherit the ability to connect to the globally-defined JRun server, and any JRun settings in the Virtual Host directive can override settings at the Apache global level. If all the Virtual Hosts use the same JRun server as defined at the global level, they use the same configuration as the Serverstore and Bootstrap. In this way, you can configure Apache for ColdFusion/JRun in a many-to-one relationship. However, you can also configure a Virtual Host for a different JRun instance, to achieve a one-to-one relationship for each Virtual Host. In the next steps, you will configure each of the virtual hosts to work with its appropriate ColdFusion instance.
In this step you must manually enable the JRun proxy service for the cfusion2 server so that it can listen for requests from the web server connector. To do this, open the JMC and click the cfusion2 server (The cfusion2 server needs to be running to administer the server). Click services in the top right link bar. Click ProxyService, then click the button Start Proxy Service if it is not already running. Make a note of the JRun Proxy Port in use since you will use it later.
Create a directory where you will create the jrunserver.store file for the second and third virtual hosts. In {jrun4}/lib/wsconfig/, create a directory called vh23 (or whatever you choose):
{jrun4}/lib/wsconfig/vh23/
Modify the virtual hosts section in httpd.conf. Add the directives from inside the global JRun container directive to the first virtual host container:
```
JRunConfig Serverstore "C:/JRun4/lib/wsconfig/1/jrunserver.store"
JRunConfig Bootstrap 127.0.0.1:51020
JRunConfig Apialloc false
```
You must set the JRunConfig Apialloc in the Virtual Host for the second instance, to false. If not, one of every 4-5 requests will return an Apache Internal Server Error to the client with a 500 status code and the Apache error log records a message such as:
```
[Thu Jun 24 15:09:33 2004] [notice] jrApache[1635] JRun will not accept request. 
Check JRun web server configuration and JRun mappings on JRun server.
```
Note: The JRun connector setting for Apialloc governs how the connector allocates memory. When the connector stub needs to allocate memory, it can request memory from the operating system (apialloc=false) or Apache (apialloc=true). Requesting memory from Apache was probably quite safe in Apache 1.3x with just one instance of a JRun server, but Macromedia recommends that you always set apialloc to false and let the stub work with the operating system to manage memory.
For the second and third virtual hosts, you will copy the same lines as you did in virtual host, but modify the ServerStore and Bootstrap address to point to the cfusion2 server JRun Proxy Port. Use the port that you noted in step 5 above.
```
JRunConfig Serverstore "C:/JRun4/lib/wsconfig/1/jrunserver.store"
JRunConfig Bootstrap 127.0.0.1:51020
JRunConfig Apialloc false
```

Figure 10 below shows the httpd.conf after you have configured all virtual hosts. With this configuration, virtual host 1 uses the cfusion server while virtual host 2 and 3 use the cfusion2 server. To verify that everything works properly, create a CFML page in each of the docroots of the three virtual sites. Copying the following code to each page will display which ColdFusion instance handles the request:

<cfobject action="create" type="java" class="jrunx.kernel.JRun" name="jr"> 
<cfset servername = jr.getServerName()> 
<cfoutput>JRun Server Name: #servername#</cfoutput>

The following shows the Apache httpd.conf file configured with three virtual hosts and ColdFusion configuration:

NameVirtualHost * 
<VirtualHost *>
ServerAdmin webmaster@site1.com
DocumentRoot "C:/appservers/Apache/Apache2/htdocs2"
ServerName www.site1.com 
ErrorLog logs/site1-error_log
JRunConfig Serverstore "C:/JRun4/lib/wsconfig/1/jrunserver.store"
JRunConfig Bootstrap 127.0.0.1:51020
JRunConfig Apialloc false
</VirtualHost>
<VirtualHost *>
ServerAdmin webmaster@site2.com
DocumentRoot "C:/appservers/Apache/Apache2/htdocs3"
ServerName www.site2.com 
ErrorLog logs/site2-error_log
JRunConfig Serverstore "C:/JRun4/lib/wsconfig/vh23/jrunserver.store"
JRunConfig Bootstrap 127.0.0.1:51002
JRunConfig Apialloc false
</VirtualHost>
<VirtualHost *>
ServerAdmin webmaster@site3.com
DocumentRoot "C:/appservers/Apache/Apache2/htdocs4"
ServerName www.site3.com 
ErrorLog logs/site3-error_log
JRunConfig Serverstore "C:/JRun4/lib/wsconfig/vh23/jrunserver.store"
JRunConfig Bootstrap 127.0.0.1:51002
JRunConfig Apialloc false
</VirtualHost>

To complete the process, copy the /CFIDE directory from C:\JRun4\servers\cfusion\cfusion-ear\cfusion-war to the web root of your web server. In this example, I copied the /CFIDE directory to C:/appservers/Apache/Apache2/htdocs2 and to each of the other virtual hosts' DocumentRoot directories. Since the cfusion2 instance is configured to virtual host two and three, you only need to copy the /CFIDE/administrator directory to one of the virtual hosts. You can administer that ColdFusion instance through the virtual host you copied the administrator to. You must copy /CFIDE/classes, /CFIDE/scripts/, and /CFIDE/debug to every virtual host. The CFFORM tag, some client-side ColdFusion controls, and ColdFusion debugging use files in these directories.

Internet Information Server (IIS) Configuration

In this section, you will configure three IIS sites to the two instances of ColdFusion that you created earlier (see Figure 8).

Figure 8. Three IIS sites connected to two instances of ColdFusion

Connect the cfusion server instance to your IIS web server using the steps below (and also shown in Figure 9). For each new instance you will configure a new site in IIS using the wsconfig GUI; if you would like to use command line, see the ColdFusion LiveDocs.
1. Start the wsconfig GUI by typing the following command:
  c:\jrun4\bin\wsconfig
2. Click Add once. The wsconfig GUI starts.
3. For the JRun Host, select localhost unless the web server and JRun server are on separate machines.
4. For the JRun Server, select cfusion.
5. Select Internet Information Server (IIS) as the Web Server
6. Select the Default Web Site or your website name; do not use "All" for multiple instances with IIS.
7. Select the check box for: Configure the web server for ColdFusion MX applications.
8. Click OK. You have configured your web server.
  
  Figure 9. Configuring your first ColdFusion Instance in the Web Server Configuration Tool.
After configuring the web server, you must copy the /CFIDE directory from C:\JRun4\servers\cfusion\cfusion-ear\cfusion-war to the web root of your web server. In this example, I copied the /CFIDE directory to C:\Inetpub\wwwroot.
To verify the web server configuration, test the ColdFusion Administrator with the following URL: http://host:port/CFIDE/administrator/index.cfm.
Create an additional website if one does not already exist.
In the following steps, you will connect the cfusion2 server instance to the second site in IIS using the wsconfig GUI; if you would like to use the command line, see the ColdFusion LiveDocs.
1. Start the wsconfig GUI by typing the following command:
  c:\jrun4\bin\wsconfig
2. Click Add once. The wsconfig GUI starts.
3. For the JRun Host, select localhost unless the web server and JRun server are on separate machines.
4. For the JRun Server, select cfusion2 (or your new server name).
5. Select your Web Server (for this example I selected IIS).
6. Select the new website name. In this example I used IIS Site 2, but you can select your website name; do not use All for multiple instances with IIS. If you are using Apache or IIS, type the web server's configuration directory.
7. Select the check box for: Configure the web server for ColdFusion MX applications.
8. Click OK. You have configured your web server. In some cases, you may need to configure the web server manually.
  
  Figure 10. Configuring the second ColdFusion Instance with the Web Server Configuration Tool.
After configuring the web server you must copy the /CFIDE directory from C:\JRun4\servers\cfusion2\cfusion-ear\cfusion-war to the web root of your web server. In this example, I copied the /CFIDE directory to C:\Site2\wwwroot.
To verify the web server configuration, test the ColdFusion Administrator with the following URL: http://site2IP:port/CFIDE/administrator/index.cfm.
To configure a third site in IIS to the cfusion2 server. follow steps 4-7 with only one change: In Figure 10, select IIS Site 3 instead of Site 2.
For each additional instance that you create with ColdFusion, you can follow steps 4-7 to configure IIS to the new instances.

About the author

Brandon Purcell is a principal support engineer at Macromedia with over seven years of experience with developing, maintaining, and supporting web-based applications. Brandon has been working with ColdFusion for over six years and has over two years of experience with J2EE and Macromedia JRun.