Local Development Setup Pt 3: Virtual Directories in Apache

In a previous post we touched upon the Alias statement in your VirtualHost directives. An Alias is a way of defining a virtual directory for your site. This is a pretty common practice in the web world. Your site code may be stored in your site's root (wwwroot) folder, but you may want to store your assets (images, video, stylesheets, etc.) outside your webroot. You might even want to store them on another server altogether. You'll want to access these items as if they're part of your site, like http://username.companyname.loc/Images/mypic.jpg or http://username.companyname.loc/Media/myvideo.flv.

Defining an Alias is easy, when dealing with your local file system. An Alias that points to a UNC path, in Windows, is another story. You have to use a UNC path because Apache will not allow you to utilize a mapped drive (it'll crash Apache, at least under 2.0). What took me a while to figure out was that you can not use Apache to control the directory access (as in permissions), you must do this through the user account access. You can not use the Directory Apache directives for access control. This also means that your Apache instance must run as the user who has access to the remote resource (I also setup CF instance to run as the same user).

I also discovered something else the hard way, Apache Aliases are case-specific. This means that you have to use double Aliases for each virtual directory that you define via an Alias. Remember, this is Windows, so code can go either way. You'll want to plan for either eventuality.

In our last post we defined a 'sites' instance, for the display of a mythical, templated application system. So, imagine that each site of that system would require it's own VirtualHost directive. Each one, though, would also be using shared media resources from the same location outside the webroot, like on a media server. For this, you can create another include in your Apache conf folder - site_aliases.conf, within which you could singularly define your remote virtual directories:

view plain print about
1Alias /Images/ //remote-serv1/Inetpub/wwwroot/Images/
2
3Alias /images/ //remote-serv1/Inetpub/wwwroot/Images/
4
5Alias /Video/ //remote-serv1/Inetpub/wwwroot/Video/
6
7Alias /video/ //remote-serv1/Inetpub/wwwroot/Video/
8
9Alias /Styles/ //remote-serv1/Inetpub/wwwroot/Styles/
10
11Alias /styles/ //remote-serv1/Inetpub/wwwroot/Styles/
12
13Alias /SiteSpecific/ //remote-serv1/Inetpub/wwwroot/SiteSpecific/
14
15Alias /sitespecific/ //remote-serv1/Inetpub/wwwroot/SiteSpecific/

Once you've defined these remote shared resources, you can then Include them in your site definitions in your VirtualHost directives:

view plain print about
1<VirtualHost 127.0.0.1:80>
2    ServerAdmin username@companyname.com
3    # Root folder for thisdomain.com, in the 'sites' instance
4    DocumentRoot "C:\Documents and Settings\username\My Documents\wwwroot\siteroot"
5    ServerName *.thisdomain.loc
6    # SGB [072007]: shared Alias Include
7    Include conf/site_aliases.conf
8    ErrorLog logs/thisdomain.loc-error.log
9    CustomLog logs/thisdomain.loc-access.log common
10    # SGB [072007]: Add include for the 'sites' ColdFusion instance
11    Include conf/cf_sitesinstance.conf
12</VirtualHost>

Once you've restarted your Apache instance you will be able to access these resources as part of the domain.

Local Development Setup Pt 2: Multiple ColdFusion Instances

Our last post discussed installing Apache and ColdFusion, as well as configuring your default instance for Apache access. Now it's time to create additional ColdFusion instances.

By default, ColdFusion (or, more appropriately, JRun) is only configured to utilize 512MB of RAM per instance, and is only capable of accessing 1024MB. This is due to a limitation of 32bit JVMs, and will someday be formerly addressed by Adobe. But that doesn't mean that you are necessarily restricted to only using 1GB of RAM for ColdFusion. You may define multiple instances of the server, each of which will address it's own memory space, it's own instance of the JVM, and it's own instance of ColdFusion (and JRun). Not only does this allow you to utilize more of the memory available to you today, in our high powered systems, but it will also sandbox applications that are separated into their own instances.

For instance: Let's say you have a dynamic template application. One that reads the requested URL and supplies customized content dependent upon the site identified. Any number of sites could be configured in a database, rendered by the same code, off of a single instance of ColdFusion (or a clustered set of instances, maybe). You could have a 'sites' instance of ColdFusion that served this content. Now, the same set of sites might require a backend administrator, or content management system, for the configuration of those sites. You might set this up on a single domain name, with users logging in to their specific set of tools and data. It would be it's own application, with dynamic options and data according to the user logging in. This might be placed in another 'control' instance of ColdFusion.

Setting up additional instances of ColdFusion is easy, but requires a small bit of manual effort when working with Apache. First of all, the connectors for JRun and Apache are not completed automatic, so you need to setup a few folders on the file system. Find the root directory for JRun. The default location is C:\JRun4. You are creating folder for the connectors, which will be located in the {JRun Root}\lib\wsconfig. Notice that there is already a subdirectory titled 1. This is the connector for your default ColdFusion instance. You'll want to create an empty subdirectory for each instance you setup, named exactly as you will name your instances. According to the above example, you want to create a 'sites' directory, and a 'control' directory.

Your next step requires logging into the ColdFusion Administrator of your default ColdFusion instance. In our last post we setup a url for accessing this, http://username.companyname.loc/CFIDE/Administrator. Once you've logged in, in the default instance (and only the default instance) you will see an option at the bottom of the menu for Enterprise Manager. You'll want to select this, and it's sub-item, Instance Manager. Here you will see a samples instance that is already defined, though disabled. This is the instance for running the sample applications that ship with ColdFusion. To create a new instance you simply select Add New Instance. This will bring up the new instance dialog. In the server name type 'sites' (exactly as you named the folder, including case) and select the Create Windows Service option, then hit Submit. That's it! ColdFusion automatically goes through a four step process to create your new instance, giving you status updates along the way. Once it's complete, go back to the Instance Manager and do the same thing for your 'control' instance.

OK, so you have new instances, but Apache still can't talk to them yet. We need to do a little more work on the Apache config before we can really start to play. The first thing you'll need to do here is locate the JRun Settings block in your httpd.conf. It'll look very similar to this:

view plain print about
1# JRun Settings
2LoadModule jrun_module "C:/JRun4/lib/wsconfig/1/mod_jrun20.so"
3<IfModule mod_jrun20.c>
4    JRunConfig Verbose false
5    JRunConfig Apialloc false
6    JRunConfig Ssl false
7    JRunConfig Ignoresuffixmap false
8    JRunConfig Serverstore "C:/JRun4/lib/wsconfig/1/jrunserver.store"
9    JRunConfig Bootstrap 127.0.0.1:51000
10    #JRunConfig Errorurl <optionally redirect to this URL on errors>
11    #JRunConfig ProxyRetryInterval <number of seconds to wait before trying to reconnect to unreachable clustered server>
12    #JRunConfig ConnectTimeout 15
13    #JRunConfig RecvTimeout 300
14    #JRunConfig SendTimeout 15
15    AddHandler jrun-handler .jsp .jws .cfm .cfml .cfc .cfr .cfswf
16</IfModule>

Alright, some major points to notice here. Two big lines to look at for multiserver configuration stuff, the Serverstore and the Bootstrap. These will be different for each instance of ColdFusion. You probably already recognize most of the path in the Serverstore value. The 'control' and 'sites' instance folders that you had created will replace the 1 in your new definitions. The Bootstrap value comes from each instance's port setting in it's JRunProxyService. To get this value, go to that instance's jrun.xml file, located at C:\JRun4\servers\[instance name]\SERVER-INF\jrun.xml. Open this file and find the following service definition block:

view plain print about
1<service class="jrun.servlet.jrpp.JRunProxyService" name="ProxyService">
2    <attribute name="activeHandlerThreads">25</attribute>
3    <attribute name="backlog">500</attribute>
4    <attribute name="deactivated">false</attribute>
5    <attribute name="interface">*</attribute>
6    <attribute name="maxHandlerThreads">1000</attribute>
7    <attribute name="minHandlerThreads">1</attribute>
8    <attribute name="port">51002</attribute>
9    ....

Two things you need here. First, make sure that the deactivated attribute is set to false. Next, write down the port value. So, if you are in the jrun.xml of your 'control' instance, and the port is '51020', then write that down (control: 51020) and do the same for your 'sites' instance. Also remember that you will need to restart these instances after changing the deactivated attribute.

Next, let's break out the default ColdFusion instance specific information and place it inside it's own include config file. In your Apache conf directory, create a new file - cf_defaultinstance.conf. In this file we'll place those settings we want for our default instance:

view plain print about
1<IfModule mod_jrun20.c>
2    JRunConfig Verbose false
3    JRunConfig Ignoresuffixmap false
4    JRunConfig Serverstore "C:/JRun4/lib/wsconfig/1/jrunserver.store"
5    JRunConfig Bootstrap 127.0.0.1:51000
6</IfModule>

With these settings now within their own include, we can now remove them from the httpd.conf file:

view plain print about
1# JRun Settings
2LoadModule jrun_module "C:/JRun4/lib/wsconfig/1/mod_jrun20.so"
3<IfModule mod_jrun20.c>
4    JRunConfig Verbose false
5    JRunConfig Apialloc false
6    JRunConfig Ssl false
7    JRunConfig Ignoresuffixmap false
8    #JRunConfig Serverstore "C:/JRun4/lib/wsconfig/1/jrunserver.store"
9    #JRunConfig Bootstrap 127.0.0.1:51000
10    #JRunConfig Errorurl <optionally redirect to this URL on errors>
11    #JRunConfig ProxyRetryInterval <number of seconds to wait before trying to reconnect to unreachable clustered server>
12    #JRunConfig ConnectTimeout 15
13    #JRunConfig RecvTimeout 300
14    #JRunConfig SendTimeout 15
15    AddHandler jrun-handler .jsp .jws .cfm .cfml .cfc .cfr .cfswf
16</IfModule>

Notice that I just commented them out. You can remove the entirely if you like, but I'm gonna leave it. Next I'm going to adjust my VirtualHost for my default instance administrator access:

view plain print about
1#
2# Use name-based virtual hosting.
3#
4NameVirtualHost 127.0.0.1:80
5
6    ....
7
8<VirtualHost 127.0.0.1:80>
9    ServerAdmin username@companyname.com
10    # Root folder for my scratchpad stuff
11    DocumentRoot "C:\Documents and Settings\username\My Documents\wwwroot"
12    ServerName username.companyname.loc
13    # Alias for /CFIDE, which the CF install placed in my Apache webroot.
14    # This is solely for our dev environment, and would not be a good practice
15    # within a production environment
16    Alias /CFIDE "C:/Program Files/Apache Group/Apache2/htdocs/CFIDE"
17    <Directory "C:/Program Files/Apache Group/Apache2/htdocs/CFIDE">
18        AllowOverride All
19        Order allow,deny
20        Allow from all
21    </Directory>
22    ErrorLog logs/username.companyname.loc-error.log
23    CustomLog logs/username.companyname.loc-access.log common
24    # SGB [072007]: Add include for default ColdFusion instance
25    Include conf/cf_defaultinstance.conf
26</VirtualHost>

Now username.companyname.loc is setup to use the default ColdFusion instance. Next, setup an include for your 'control' instance. In Apache's conf directory, create another config file - cf_controlinstance.conf. Remember those port numbers you wrote down from the jrun.xml files? It's in the Bootstrap:

view plain print about
1<IfModule mod_jrun20.c>
2    JRunConfig Verbose false
3    JRunConfig Ignoresuffixmap false
4    JRunConfig Serverstore "C:/JRun4/lib/wsconfig/control/jrunserver.store"
5    JRunConfig Bootstrap 127.0.0.1:51020
6</IfModule>

Then you could define a special domain for accessing the 'control' instance's ColdFusion Administrator, by adding another VirtualHost directive to the Apache config:

view plain print about
1<VirtualHost 127.0.0.1:80>
2    ServerAdmin username@companyname.com
3    # Root folder for a 'control' instance
4    DocumentRoot "C:\Documents and Settings\username\My Documents\wwwroot\admin"
5    ServerName control.companyname.loc
6    # Alias for /CFIDE, each CF instance has it's own CFIDE.
7    # This is solely for our dev environment, and would not be a good practice
8    # within a production environment
9    Alias /CFIDE "C:/JRun4/servers/control/cfusion.ear/cfusion.war/CFIDE"
10    <Directory "C:/JRun4/servers/control/cfusion.ear/cfusion.war/CFIDE">
11        AllowOverride All
12        Order allow,deny
13        Allow from all
14    </Directory>
15    ErrorLog logs/control.companyname.loc-error.log
16    CustomLog logs/control.companyname.loc-access.log common
17    # SGB [072007]: Add include for the 'control' ColdFusion instance
18    Include conf/cf_controlinstance.conf
19</VirtualHost>

Notice the different path for the CFIDE folder. Each created instance will have a unique CFIDE. Also notice that I changed the DocumentRoot path, to reflect the root of the application I'll use with the instance. Now that you've setup your 'control' instance, config, and VirtualHost, you can do the same thing for your 'sites' instance. Just watch your port value, Serverstore path, and CFIDE and DocumentRoot paths.

Local Development Setup Pt 1: Apache and ColdFusion (7 or 8)

OK, so now that we are moving to localized development it has become necessary to learn how to configure our desktops for running a localized copy of our sites. The trick here is the complexity of our setup. We have multiple sites, sharing the same code base, accessing media from external resources. We also have to setup for multi-instance, to separate our front-end site and our back-end administration. We also need to be setup for one SSL site. Oh yeah, and we have to do it on Apache, since XP pro's version of IIS has some limitations about running multiple domains simultaneously. To top it all off (at least in my case) I also have to run Apache 2.0.59 so that I can also run Subversion, which is not yet compatible with Apache 2.2.

[More]