Instructions by Sean Corfield from [http://www.corfield.org/blog/post.cfm/Railo_for_Dummies_Part_III Railo For Dummies Part III] and [http://www.corfield.org/blog/post.cfm/Railo_for_Dummies_Part_IV Railo For Dummies Part IV]

Tomcat is a robust, high-performance Java-based web server and Servlet engine and it's also very light and lean. Tomcat is also the basis of the JBoss Web Server so all that you learn about getting things up and running on Tomcat can be carried over to JBoss when you need a full JEE server rather than "just" a Servlet engine.

1. Go to the [http://tomcat.apache.org/download-60.cgi Tomcat 6 download page] and select the appropriate binary distribution of the "Core". Select the 'zip' version for Mac OS X. If you are targeting Linux, you can use the 'tar.gz' version but the only difference is how you extract the files.

2. This puts a 6.3MB ZIP file in your Downloads folder which you can expand by double-clicking it.

3. At this point, you need to fire up Terminal and start working on the command line since the startup/shutdown shell scripts and not executable directly in Finder. You'll find Terminal in Applications > Utilities

4. In Terminal, navigate to the bin folder inside the expanded Tomcat directory, e.g.: cd Downloads/apache-tomcat-6.0.18/bin

5. A useful tip is that you can press 'tab' to auto-complete file paths in most Unix shells so this will probably get you there: cd Dow[tab]apa[tab]/bin (depending on what other files you have on your system).

6. Now we'll make the various shell scripts executable: chmod +x *.sh

7. If you use ls -l you'll see most files have permissions -rw-r--r--@ for owner-read/write and group/world readable. The shell scripts (*.sh) are now -rwxr-xr-x@ so they are executable (by owner, group and world).

8. Now you can start Tomcat

1. If you're still in the bin folder, you can start Tomcat by typing:

sh startup.sh

or:

./startup.sh

1. You should just get four lines of output saying which paths it is using. That's it, Tomcat is running!
2. You may also notice a new application running, called org.apache.catalina.startup.Bootstrap.
3. If it complains it cannot find ./catalina.sh, you didn't get the 'chmod' command right (see above).

1. Browse to http://localhost:8080/. You should see the Tomcat welcome page (you can't access the manager or admin consoles without doing some initial configuration - which is out of the scope of this list).
2. Now we need to get Railo installed and running...

1. Go to the [http://www.getrailo.org/index.cfm/download/ Railo Download page] and under "Railo Custom", pick the "war" (web archive) file: railo-3.0.2.xxxx.war
2. In the Finder rename the file to railo.war (it'll make life easier when we test things below).
3. Now drag railo.war and drop it into the webapps folder inside the expanded Tomcat folder. After a couple of seconds, you'll see a new railo folder appear next to the existing manager, ROOT and other folders.
4. Tomcat has automatically deployed the web archive for you! You can now remove railo.war or at least move it somewhere else in case you need it again.

1. Now browse to [http://localhost:8080/railo/] and you should see the familiar Railo test page. You can now do all the usual stuff with Railo at this point

1. Go back to your Terminal window and make sure you're still in the bin folder (the pwd command will print your current 'working' directory), then type:

sh shutdown.sh

or:

./shutdown.sh

1. After four lines of output, Tomcat will shutdown. As with startup, you can use ./sh[tab] to save yourself some key strokes.
2. If you want to be able to just double-click the startup script from the Finder, rename it so it has no extension. The Finder will confirm you really want to remove the extension - click Remove.
3. You can stop Tomcat by switching to the org.apache.catalina.startup.Bootstrap application (using Cmd-Tab) and quitting it like any regular application - or right-click > Quit on its dock icon.

1. If Tomcat is running, shut it down (by quitting the org.apache.catalina.startup.Bootstrap application).
2. You want move the Tomcat folder to a more permanent home. Using the Finder, drag apache-tomcat-6.0.18 to your /Developer folder but you can put it in your home directory or wherever else you want.
3. Rename it to tomcat so that the directory path is easier to type
4. We want to make Railo the 'root' web application so that it no longer needs the /railo prefix on its URLs. In the Finder,rename the 'ROOT' folder to 'welcome' (you can also remove it for production).
5. Rename 'railo' to 'ROOT'.
6. Restart Tomca using the following shell command:

/Developer/tomcat/bin/startup.sh

1. At this point, we can browse to [http://localhost:8080/] and see the Railo test page. (you might have to force your browser to refresh since it had cached the previous Tomcat welcome page).
2. If you renamed the old ROOT folder to welcome, you can still reach it on http://localhost:8080/welcome/.

1. If you want to look at the Tomcat Manager console, you need to do one more piece of configuration on Tomcat: adding a Tomcat user. 1.In the Finder, navigate to the conf folder under Tomcat and open tomcat-users.xml with your favorite text editor
2. In the section, add a user definition like this:

{{{Messagebox message="Warning: undeploying an application removes the entire directory structure from webapps!" type="info"}}}

1. As you see, in addition to the Railo web application (now at /), there are web applications for documentation (/docs), examples (/examples) and a couple of 'manager' applications. In production, you would want to remove anything you don't need. Since you can 'manage' Tomcat by editing XML files, you could remove everything except the ROOT (Railo) application.

Two main issues remain at this point:

1. The web root is webapps/ROOT/ under the Tomcat install
2. We are using port 8080 and not routing through Apache on port 80

1. Tomcat assumes the web root for each application is a folder under webapps. Also by default, the URL for each web application begins with a 'context root' that is the name of that directory (with the empty context - / - for the ROOT folder). This behavior is controlled by Tomcat's conf/server.xml file.
2. Open it up in your favorite text editor and go to the bottom of the file. You'll see a <Host..> section that defines the behavior for the default virtual host. You can add <Context..> tags inside this section to override the default 'context root' behavior for web applications. To point the default context to, for example: "/Users/scorfield/Sites" add:

In most blog posts, this is always the hardest part to follow. Almost everyone shows how to configure mod_jk which, whilst fairly standard, is a lot of work. For example, see [http://www.lynchconsulting.com.au/blog/index.cfm/2009/3/27/Installing-Railo-on-Tomcat-via-Apache-on-Leopard--Step-by-Step Marko Tomic's post on the Lynch Consulting] blog which walks you through building mod_jk from source in order to get Apache up and running.

That's far too much work for my taste and there is a much simpler solution. What a lot of people forget is that Tomcat is a very robust, high performance web server in its own right. With JRun, you usually want have Apache handle static content and JRun handle the requests for CFML pages and that's why you would use the JRun connector (which is what Adobe ColdFusion installs by default when you tell it to connect to a web server).

You could simply tell Tomcat to use port 80 and leave Apache out of the picture altogether. Just change the port= attribute from 8080 to 80 on the <Connector..> tag for the Catalina service in Tomcat's conf/server.xml file.

However, most systems run an existing web server on port 80 and you probably don't want to interfere with that - and instead just connect it to Tomcat. The easiest way to connect Apache to Tomcat is to proxy requests. This way you have control over which URLs are passed to Tomcat and can easily leverage all the other useful Apache modules.

Here's an example of an Apache virtual host for railo.corfield.org (an entry /etc/hosts file that points to 127.0.0.1 for testing sites locally):

<VirtualHost *:80>
  ServerName railo.corfield.org
  DocumentRoot /Users/scorfield/Sites
  ProxyRequests Off
 <Proxy *>
  Order deny,allow
  Allow from all
 </Proxy>
  ProxyPass / http://localhost:8080/
  ProxyPassReverse / http://localhost:8080/
 </VirtualHost>

This maps any request to Apache for [http://railo.corfield.org/] to Tomcat using the empty context root, which we already mapped to the same document root above.

You can use additional ProxyPass directives to exclude mapping certain requests. For example, you could exclude the images directory (and let Apache serve that instead of Tomcat) by adding this as the first ProxyPass directive:

ProxyPass /images !

I added the virtual host above to /etc/apache2/extra/proxy.conf and then edited /etc/apache2/httpd.conf to add the following immediately after the NameVirtualHost *:80 directive:

Include /private/etc/apache2/extra/proxy.conf

I prefer to keep my httpd.conf file as clean as possible and use include files for virtual hosts and other customization. You can restart Apache from the command line:

sudo apachectl restart

It will usually prompt you for your password. At this point you have Apache+Tomcat+Railo configured and you should be able to set up as many local virtual hosts as you want, each with its own web root and a local configuration of Railo.