What I am still learning about the web

Acknowledgements

Before I start this article, I would like to  state this is a continuation of a blog written by Sean Corfield which can be found here An Architects View – Railo build blog. And I would strongly advise anyone attempting to build Railo, to read both articles to get a better understanding of the whole process.

Requirements

In order to build Railo from the Source in an easy and simple way, you’re going to need a few things first.

• An SVN Client I use Tortoise SVN.
• Eclipse, preferably the JEE version.
• Eclipse, with installed JRE set to JDK 5, not 6.
• The latest Railo.War.
• The latest Apache Tomcat.

Working Railo Explanation

If you followed my advice you would have visited Sean’s site and seen the requirement for a running Railo installation. This sometimes puzzles people but can be easily explained. The later sections of the build process are processed in ColdFusion, this means you need an environment capable of parsing CFML, and what better one to use than the one you have decided to build.

Install Tomcat (optional)

This part is only for people who wish to do as I did, and use the Windows Tomcat installer to get Railo up and running quickly.

Use the Windows Service Installer, it’s quick and painless. Once installed check that the service is not running, if it is stop it.

Install Railo

Get the latest Railo.war and rename if to something like railobuild.war. This will just make the URL you’re going to need later easier to read. Place the newly renamed war file into the webapps directory within Tomcat and start the Tomcat service, this should unpack the war file into a directory named railobuild in my example or in yours whatever your war file was named.

Well done Railo is ready. Now we can get the Source.

Getting the source

Using your SVN client checkout the latest source from Railo’s repository

http://anonsvn.jboss.org/repos/railo

This will take some time but when completed you should have a single Railo folder containing the standard Branches, Tags and Trunk directories at the time of this article being written Branches and tags were empty. But being as we are only interested in Trunk that’s no great shakes.

Setting up the Eclipse Projects

Now we have the source code we need to add the projects to eclipse. To do this we will import them. This part is shamefully similar to Sean’s explanation but that’s because there really is only one way to do this part.

In Eclipse select File > Import > General > Existing Projects into Workspace and click Next >. For the root directory, Browse to railo/trunk/railo-java/railo and Choose that folder. It should now import the project into a directory called Railo. Click Finish.

Do exactly the same for railo/trunk/railo-java/railo-core, railo/trunk/railo-java/railo-loader and railo/trunk/railo-java/railo-master.

Fixing the Build Paths

You will notice that Railo-Core and Railo-Loader have a red ‘x’ on the project. This is due to the build paths being incorrect. Lets fix that by right clicking on the project and selecting Build Path > Configure Build Path navigate to the libraries tab select all the jars apart from the JRE System Library, and click remove. Now we need to replace them with the same jars but in the correct locations. Click Add External Jars then Browse to the railo/trunk/railo-java/libs directory and select all the jars, being careful not to copy the .svn directory and click open. This should populate the libraries tab with all the jars. Make sure you have done this for both Railo-Core and Railo-Loader.

Preparing your Working Railo

We need to move some files into the Railo you created earlier, copy the contents of the railo/trunk/railo-cfml directory into the Railo-Build directory on your tomcat railo install.

This is also a good time to log into your Railo web administrator and set a password. This will be required during the build process.

Setting the Build Properties

Within the Railo-Core project you will find the build.properties file, open this within a text editor and within that file change the railo.url to the location of your compileAdmin.cfm which if you have followed this tutorial with no variation will be:

railo.url=http://localhost:8080/railobuild/compileAdmin.cfm

Building Railo

Within the Railo Source project, right click the build.xml file and select Run as > Ant Build. The build will begin and approximately half way through a prompt box will appear asking you for the Railo password you provided in your tomcat Railo setup. Once accepted the build process will complete the final coldfusion parts of the build process. Within the console you should see all the output and  hopefully “Build Successful”.

Deploying your Railo

Now right-click the Railo-Core project and select Refresh. The red ‘x’ should go away and you should see build and dist directories inside that project. Open the dist directory and you should see [version].rc file.  Take the created .rc file and paste it into the following directory within your Railo install.

C:\tomcat\webapps\railobuild\WEB-INF\lib\railo-server\patches
if this is where you have your directory.

Now all that is left to do is restart Railo. When you next log into the web administrator you will see within the overview that the version number has changed to the version you have just built.

Throughout recent times I have been developing using ColdFusion, which is all well and good apart from the debugging element. I’m sure if your used to ColdFusion then you are certainly used to the tag CFDump to debug what you have actually put in any given variable. But when visiting the getrailo.org site I saw a link to Fusion Reactor’s FusionDebug being as I am already developing using Eclipse and FusionDebug has a plug-in for Eclipse I thought I would give it a try, and I’m glad I did.

Install FusionDebug on Eclipse

Start up Eclipse and select the Help -> Software Updates -> Find and Install options this will present you with a dialog box, select “Search for new features in Install” and after clicking next you will have to select “New Remote Site”. In the resulting dialog box enter the following information:

• Name: FusionDebug Update Site
• URL: http://www.fusion-reactor.com/fd/fd3update/

Ensure the “FusionDebug Update Site” is checked within the “Install/Debug” dialog and click finish.

You have now installed the plug-in and should now be able to see the new window “FusionDebug” you will of course have to license FusionDebug for continued use but Fusion Reactor are offering a 30 day trial license, which I would recommend to make sure this is the right plug-in for you.

FusionDebug Start-up part 1

To use the FusionDebug plug-in with Railo you will need to set up a debug port on the Tomcat installation that is running Railo. This is done very simply by altering Catalina.bat and adding you will basically have to add one line to this batch file.

CATALINA_OPTS=-Xrunjdwp:transport=dt_socket,

server=y, suspend=n, address=8000

(if you copy amd paste the line above it needs to be on one line with no spaces)

This should be placed directly beneath the large comment block found at the top of the Catalina.bat file, now when you want to start Tomcat do it through running the Catalina.bat file this will mean you will have a running tomcat with a debugging port.

FusionDebug Start-up part 2

Ensure that your coldfusion project is loaded as a project in Eclipse, a good plug-in for Eclipse is CFEclipse this does come as part of the FusionDebug as long as make sure it is selected as part of the plug-in install.

Now we have a running Tomcat with an open debugging port, we need to let the FusionDebug plug-in know which port to look for and in which project. So within Eclipse go to Debug and select from the drop down Debug Configurations here you will see a tree on the hand side which should include FusionDebug. Click on “New” enter name in the appropriate box. Then in the configuration panel. enter the required information remembering that the port is now 8000 or whatever you chose for the port entry in Catalina.bat.

Now click the “Run” button and your done, you now have the ability to debug ColdFusion code using FusionDebug.

I have been using Railo in development now for around 7 months, I have found it to be very stable and reliable. The way I have been deploying Railo onto my environment was through a windows installer I created using Inno-setup this allowed me to not only install Railo but Tomcat, Probe, a JDK and other application specific to my needs for development. Lately I was looking for a way to combine the usefulness of Tomcat with the parsing of Railo without deploying Railo on Tomcat as a web application. I came across a brilliant article by Sean Corfield You can find it here and paired with Sean’s article I also came across Jamie Krug’s excellent article Railo JARs on JBoss (or Tomcat) I would recommend these articles to anyone thinking of using a multi-web configuration.

My reasons for blogging this out are to hopefully provide solutions to some of the problems you may find when going through these steps, because as you will no doubt have seen Sean’s and Jamie’s articles have not been updated in some time although I will say these guys appear regularly on the Railo Google Group as do I now. So if you have any questions first search through the posts there after registering, then post and I’m sure one of us in the group will get back to you.

First Things First

I would recommend following Sean’s article if you are deploying a development environment, nothing against Jamie’s just Sean’s suited my needs better. When following Sean’s article I found that upon completion and starting the Tomcat service for the first time I had a SAXParseException on further examination I found this to be down to the encoding type set in tomcat-users.xml, by changing the encoding type to UTF-8 from CP1252 this cleared the error and allowed me to keep the apache-xml-xerces.jar.

Starting Tomcat for the First Time

OK this part is not hard but you may or may not know what to expect within your webapps (or whichever directory is defined for your applications) directory. What will happen now is, for every application you have defined within your webapps directory you will have a WEB-INF directory created containing the Railo web admin files. Navigate to (whatever your tomcat is set up as / your webapp/railo-context/admin/web.cfm) this should put you on the web administrator page for your application all changes made here will only affect the application you entered in the URL.

Server Settings

You can access the Server settings by clicking Server Administrator link that is ever present within the Web Administrator page Beware these settings will affect all applications upon your new Railo Tomcat multi web installation.