How To Configure A Production Environment with IIS, Coldfusion, JRun, and Flex Data Services

Flex Data Services(FDS) is best known for its data management capabilities, the real-time data push/data synchronization feature more specifically. There is simply nothing else like it on the Web, not even AJAX can push data, it uses a scheduled pull. FDS runs on top of a J2EE server like the integrated JRun that comes with the free FDS Express version(1 CPU supported). So when Flex was first released, CF coders saw that FDS runs on JRun, the first thought that entered their collective minds was, "I can load Flex Data Services on CF's JRun." Many CF coders thought this and leaped in, only to end up limping out, full of frustration and failure.

Most of us have been there. Even Adobe's experts were attempting to get the word out the best that they could that you have to use a separate instance of JRun for FDS and a separate instance of JRun for Coldfusion - they were never meant to be combined.

As time moves along, we're roughly 10 months from when Flex 2 was officially launched, some of us who found the time to persevere through the frustrations are slowly figuring things out. It turns out that you can use Coldfusion's JRun with FDS and it is possible to use an IIS web server that is connected to JRun and FDS in a production environment. If you are using Coldfusion Standard Edition, you can use a stand-alone J2EE server like JBoss or JRun and get the data push/data sync capabilities of FDS too. I'm going to explain it all right here. By the time you are finish reading all of the this and trying out the examples, you will be illuminated with the knowledge of configuring a development environment using your own URL (not localhost) and/or setting up a production environment; using Windows Server 2003 (without SP1) and IIS 6, stand-alone JRun 4 (either Developer or Full edition), Coldfusion MX 7.0.2 Standard or Enterprise (you don't need stand-alone JRun with CF Enterprise), and Flex Data Services 2.0.1.

All of the documentation that I've seen concerning Flex and FDS show example after example with localhost:8700 or localhost:8300. It really isn't difficult at all to get a development environment setup, if you don't mind using localhost. But when it comes to configuring your development environment using your own domain name like http://www.yourdomain.com/Flexapp or configuring your production environment, that's where the documentation stops and now I step in to save you a ton of time.

The integrated JRun that comes with Flex Data Services is licensed for development and testing purposes only; you cannot use it in Production. Now you can setup you own domain name to work with the integrated JRun for development and testing if you want, but since Flex is so new, I would rather mimic my client's Production environment, for development. That way I know if it works in dev it'll work in prod too. To deploy your Flex app with FDS in a Production environment, you are required to use a stand-alone J2EE server.

JBoss (from RedHat) seems like a good option because it is free, but it depends on how valuable your time is. JBoss has integrated the J2EE Web Server, Tomcat, into it, which is different than the previously available stand-alone version of Tomcat. The procedures for connecting IIS to the stand-alone Tomcat (which are all over the web) do not work with JBoss Tomcat. It is a very manual process involving registry files, .properties files, and .dll files, most of which you have to manually code. I tried one of the only tutorials I could find on the web, and it ended up jacking up my registry and I had to reload Win2003 and everything else again. Some day someone smarter than me will build a Web Server Config Tool for JBoss to connect Apache and IIS Web sites to JBoss Tomcat, but until that time, I highly recommend making your life easier by using the stand-alone version of Adobe JRun; unless you are using the Enterprise Edition of Adobe Coldfusion, which is the other JRun alternative. Whichever JRun you use, it comes with its own Web Configuration Utility Tool which connects your IIS sites to JRun in seconds.

Let's get started by getting everything installed properly on your Win2003 (without SP1) server. Complete each step in the order it is listed:

1. If you are loading CF for the first time on your server or have to reinstall it and you are using Windows Server 2003, then do not install SP1 - if it is already installed, uninstall it in Control Panel>Add Remove Programs. There is a nasty bug that errors out the web connector and an ant script when SP1 is loaded. It should be fixed in Scorpio, but for now avoid Win2003 SP1 and CF 7.0.2 will load fine.
2. Download and install the JDK 5.0 Update 11 One Note when installing the JDK 5.0, the default installation path is c:\Program Files\..., so change the installation path to c:\Java\jdk1.5.0_11 and c:\Java\jre1.5.0_11. Remove the Program Files directory from the path.
3. Install JRun4. Go ahead and check the checkbox to load the JRun4 Windows Service. After JRun4 is installed, then install the JRun Updater 6 from Adobe.com. This is required for the connector to IIS to work.
4. Load Coldfusion 7.0.2 - just download it from Adobe.com and you won't have to worry about updating it from the 7.0 version on CD-ROM. Install the Server Configuration if you are using CF Standard or the Multiserver option if you are using CF Enterprise.
5. Install Flex Data Services (FDS) without the integrated JRun.
6. Restart the Server (hardware)

Make sure you have an IIS site configured and that you can browse a simple html file. Now its time to run the JRun Web Configuration Utility Tool. Start>All Programs>Macromedia JRun 4>Web Server Configuration Tool. It's really simple; I bet you can figure it out. Click the Add button. Leave the JRun Server Properties alone, Web Server is IIS - all you have to do is choose which IIS sites to connect to, or All of them. Check the Configure web server for ColdFusion MX applications checkbox too. I ignore the options in Advanced - feel free to play, if you want. Click OK.

Before we go any farther, you should have either WinZip or WinRAR loaded on your PC. If you don't, you can get either of them from Download.com. Then come back to continue....

If you are using the Stand-alone version of JRun4 either the full version or trial/developer version then proceed to the next section. If you are using Coldfusion's JRun Server, then skip the next section and head to the section after it called, Using Coldfusion MX 7.0.2 Enterprise Edition's JRun.

Using the Stand-Alone JRun 4 with Updater 6 or higher
Let's setup JRun4 to work with Flex Data Services. Browse to C:\fds2 and you'll see three WAR files:

1. flex.war
2. flex-admin.war
3. samples.war

A .war file is a Web Archive file and can be extracted with Winzip or WinRAR. Extract samples.war to: C:\JRun4\servers\default\flexsamples - where flexsamples is a new folder that WinZip or WinRAR will create. We could have named the new folder anything and remember that it is case-sensitive; probably best to use all lowercase. The new flexsamples folder is called the "context root" of the JRun4 server named default. When configuring your own Flex app, you will unzip flex.war (instead of samples.war) into a content root folder named whatever you want. You will need to restart the JRun Server and IIS each time to add a new context root. This is the process for configuring each of your Flex apps to work with JRun and FDS. You can create as many servers as you'd like (via the JRun Administrator, similar to CF Instances), and create as many context roots as you'd like; one for each Flex app. Flex.war creates an empty FDS container for your app, which will require more configuration later in order to work with data. We're using samples.war for this example, because it contains finished Flex apps you can test and play with.

After unzipping samples.war into the flexsamples context root on the JRun4 server named default, we should now be able to test locally. If you're setting up this server for development then you'll want to make a change to the Macromedia JRun Default Server service; otherwise if you're setting up a Production environment skip to the next paragraph, You're ready to start JRun. Go into Services and find the Macromedia JRun Default Server service:

1. If the service is running, stop the service.
2. Right click on the Service and click Properties.
3. Change Startup type to Manual, then click OK.

You will find that being able to start and stop the JRun server via a Command Prompt will be far more convenient when developing your Flex App. As soon as you close the Command Prompt window, the server will stop - so keep it open. You will also get valuable debugging info sent to the Command Prompt as well - another reason to keep it open. When you put your Flexapp into Production, change the service back to Automatic. There's no need to use the Command Prompt for Production apps - you want it to stay running all the time. As soon as you start the service, the server is running.

You're ready start JRun. If you're setting up a Production environment start the server in Services - look for the Macromedia JRun Default Server, and start it. You're done, head to the next paragraph, You're Ready To Test. If you're setting up a development environment:

1. Open a Command Prompt.
2. First let's change the directory, at the prompt type>cd c:\jrun4\bin. Hit Enter.
3. Type>jrun -start default. Default is the name of the server.

You will see it start and at the bottom it should report how many seconds it took to start. If it gets stuck, then close the Command Prompt window and try again. Mine takes about 2 seconds to start.

You're ready to test. Open a browser and type http://localhost:8100/flexsamples. It should run properly. Feel free to play around with some of the sample apps.

You should be able to browse a test html file within your webroot by typing: http://www.yourserver.com/test.html.

Okay, the moment you've been waiting for. Test our IIS connection to JRun and FDS, type in your browser: http://www.yourdomain.com/flexsamples. That URL should pull up the same page as using http://localhost:8100/flexsamples. Note that the flexsamples in the URL is your context root name. This is important, and you cannot have any directories in your IIS webroot with the same name, or it will not work.

Whew! We're in business. We now have Flex Data Services working. Skip the next section, and have a look at, How to Create a Flex Project using Flex Data Services in Flex Builder 2.0.1.

Using Coldfusion MX 7.0.2 Enterprise Edition's JRun
Let's setup Coldfusion's JRun4 to work with Flex Data Services. Browse to C:\fds2 and you'll see three WAR files:

1. flex.war
2. flex-admin.war
3. samples.war

A .war file is a Web Archive file and can be extracted with Winzip or WinRAR. Extract samples.war to: C:\JRun4\servers\cfusion\flexsamples - where flexsamples is a new folder that WinZip or WinRAR will create. We could have named the new folder anything and remember that it is case-sensitive; probably best to use all lowercase. The new flexsamples folder is called the "context root" of the JRun4 server named cfusion. When configuring your own Flex app, you will unzip flex.war (instead of samples.war) into a content root folder named whatever you want. You will need to restart the JRun Server and IIS each time to add a new context root. This is the process for configuring each of your Flex apps to work with JRun and FDS. You can create as many servers as you'd like (via CF Instances in the CF Administrator), and create as many context roots as you'd like; one for each Flex app. Flex.war creates an empty FDS container for your app to use, which will require more configuration later. For now we'll just use samples.war since it contains finished Flex apps you can test and play with.

After unzipping samples.war into flexsamples on the cfusion JRun4 server, we should now be able to test locally. If you're setting up this server for a Production environment, go ahead and skip to the next paragraph, You're ready to start JRun. If you're setting up this server for development with a custom URL, then you'll want to make a change to the Macromedia JRun Cfusion Server service. Go into Services and find the service. If it is running, Stop the service. Now right click on it and click Properties. Change Startup type to Manual, then click Ok. You will find that being able to start and stop the JRun server via a Command Prompt will be far more convenient when developing your Flex App. Plus, you will also get valuable debugging info sent to the Command Prompt as well - another reason to keep it open. If you're using a CF Server Instance then do the same to its Windows Service. When you put your Flexapp into Production, change the service(s) back to Automatic. There's no need to start/stop the server manually via the Command Prompt.

You're ready to start JRun. If you're setting up a production environment, simply start or restart the service to the server you are using - in our example that is the Macromedia JRun Cfusion Server service. You're done, skip to the next paragraph, You're ready to Test. For a development environment with a custom URL:

1. Open a Command Prompt.
2. Change the directory, at the prompt type>cd c:\jrun4\bin. Hit Enter.
3. Type>jrun -start cfusion. Cfusion is the name of the default JRun server.

You will see the JRun server start and at the bottom it should report how many seconds it took to start. If it gets stuck, then close the Command Prompt window and try again. As soon as you close the Command Prompt window, the server will stop - so minimize it to keep it running and out of your way. When you make changes to your Flexapp, you'll likely need to close the Command Prompt and restart the server multiple times, so this makes it convenient.

You're ready to test. Open a browser and type http://localhost:8300/flexsamples. It should run properly.

You should be able to browse a test html file within your webroot by typing: http://www.yourserver.com/test.html.

Okay, the moment you've been waiting for, it's time to test our IIS connection to JRun and FDS, type in your browser: http://www.yourdomain.com/flexsamples. That should pull up the same page as using http://localhost:8300/flexsamples. Note that the flexsamples in the URL is your context root name. This is important, and you cannot have any directories in your IIS webroot with the same name, or it will not work.

Whew! We're in business. We now have Flex Data Services working. Let's take a look at how to create a Flex Project, using Flex Data Services in Flex Builder 2.

How to Create a Flex Project using Flex Data Services in Flex Builder 2.0.1.

Let's create a new Flex Project for a new context root. First we'll create a new context root on the Win2003 server. I am assuming that your copy of Flex Builder 2.0.1 is on a computer separate from your server. On the server, if you're using the stand-alone JRun create the new directory named test in C:\JRun4\servers\default\. For CF JRun create a new directory named test in c:\JRun4\servers\cfusion\. As a reminder, by creating this new directory called test we're creating a new context root. The context root name is case sensitive and cannot be the same name as a directory in your IIS webroot, or it won't work. I recommend lowercase, instead of camel-case. Unzip the flex.war file (located in C:\fds2) into the new test context root.

Now back on your workstation, either PC or Mac, in Flex Builder 2 click New>Flex Project. A dialog box pops up in the center of your screen...you've likely seen this before, only this time select the Flex Data Services radio button. I find it more convenient to compile locally so select Compile application locally in Flex Builder radio button. Click Next.

Uncheck the checkbox that says Use default local Flex Data Services location, which activates the three text fields below it. For Root Folder, I use a mapped drive that is mapped to my development server's C:\jrun4 directory (we'll call it J:\).

• For Stand-Alone JRun: The full path should be J:\servers\default\flexsamples and the Root URL should be http://localhost:8100/flexsamples.
• For CF JRun: The full path should be J:\servers\cfusion\flexsamples\ and the Root URL should be http://localhost:8300/flexsamples.

A difference between Flex Builder 2.0.1 and Flex Builder 2 is that with 2.0.1 you should see the third text field called Context root. If you don't have that, you're still using version 2 - you need to update to 2.0.1. Put /test as that is our context root. Click Next.

Name your project anything you'd like. Then I always uncheck the Use Default location checkbox, and map to where I keep my apps. The location is totally your choice. I use my webroot. If you don't use your webroot, you'll have to add a custom mapping to your cfc files in the CF Administrator. Click Next.

On this screen you only need to fill out two text fields, the first one is Output folder. The path pattern is like this: J:\servers\default\[contextroot]\[projectname]. Output folder URL: http://www.yourserver.com/[contextroot]. Remember that [contextroot] for this example is test, so the URL would be http://www.yourserver.com/test. Click OK.

Now back in the main app of Flex Builder 2.0.1 you should see your new project and it has a bin folder with a shortcut symbol on it (a tiny gray box with an arrow). That means the bin folder is linked to an external location; it is not local like the files you are coding. When Flex Builder 2.0.1 compiles your files it puts them into your context root on your J2EE server where the FDS flex.war file was unzipped. When you type in the URL, IIS sends the request through the connector to JRun and runs the context root you typed in the URL. This is why you cannot have a directory in your webroot with the same name as your context root.

You should see a test.mxml file as your main Flex application file. Open it, if it is not already open. Make sure your code looks like this:

Save the file and Run it. You should now see the text in your browser.

So you have created a Flex app shell that uses Flex Data Services via IIS and JRun. But you're not pulling in any data from a database yet. You are not yet using the real-time data push/data sync feature you want to use, yet. The next step is to configure the data-management.xml and services-config.xml files for your app. Then you'll use the RDS Dataview (found in the CF Extensions for Flex Builder 2) and use the CFC Wizards. I'll leave that to a future blog entry. It is pretty well documented unlike what I've just shared with you in this blog entry. If you find any inaccuracies or errors in the procedures in this blog entry, please leave a comment and let me know.

I hope you will give Flex another try. It is super cool. If you live in Missouri or Kansas, I recommend you try out KCDevCore - An Adobe RIA User Group in Kansas City. I am the group's manager and our main focus is to help each other learn about Flex 2, Actionscript 3, and OO CFCs.