Creative Juices Bo. Co.

Satisfy Your Thirst For Something Refreshing!

Installing Railo 3.1 On Mac OS X 10.5 (Leopard)

A Step-By-Step Guide To Install Railo Server 3.1 On Mac OS X 10.5 (Leopard)

When I was ready to install Railo server I hit up google to see how you would go about installing it on Mac OS X 10.5 (Leopard). There wasn't a lot out there. Actually, there was only one good article I could find, but it didn't allow me to do everything. I've decided to post the steps I took to install Railo Server on my Apple G4 running Mac OS 10.5 Leopard. But first, I have to give credit where credit is due. I based this entire article on what I found here at Luis F. Majano's blog. Everything is built upon this post. Thanks Luis!

My Goal

The goal of this install is to get Railo running on my server and to have all web files located in a common folder and accessible from the outside internet. I need to do this, so my clients can check their site as I am developing them. I have not tried installing PHP or Adobe ColdFusion server along side Railo. This is something I may look into down the road.

My Setup

  • Here's a quick list of my setup:
  • Apple G4 Server running Mac OS X 10.5.8
  • Railo 3.1.1 w/Resin for Apache (www.getrailo.org/index.cfm/download/)
  • MySQL 5.1.38 (This is not really important for this tutorial, just listing what I'm using)

Pre-requisites

You are going to need to have a text-editor of some sort, I use BBEdit. It allows me to edit hidden/protected files, by providing my Admin password. I'm going to assume that you can figure out how to edit these files if you plan on using something else. You are going to need to use the Terminal.app (don't be scared, I'm by no means a Terminal master). And finally, you are going to need to have XCode installed on your development machine in order to make the install the Railo Apache connector. And lastly, you need to be logged in as an Administrator. I don't think this will work, if you cannot do this.

This may seem obvious to some, but just in case, you also need to have Apache running. To do this, you need to open up System Preferences > Sharing. Make sure that Web Sharing is checked. You can test if Apache is working by pointing your web browser to your server (localhost or 127.0.0.1 if it's on the machine locally) and see if you get the default Apache welcome screen. If it is, your ready to roll. If it's not, then you need to get that working before you can continue.

Step 1 - Get Railo

If you haven't already done so, go to GetRailo.org and download the latest Railo Server (Not Railo Express) for Mac OS X. At the time of this writing it was at version 3.1.1. Un-compress the zip archive and place the entire folder into your Applications folder. Rename this folder "Railo". There's some Windows executables located in this folder and we don't need them. So go ahead and delete httpd.exe, setup.exe and win32.

Edit 7/2/2010: The file you want to download is the "railo-3.1.2.001-resin-3.1.9-without-jre.zip (45 MB)" file. Not the version with JRE.

Step 2 (This step requires XCode to be installed) - Build the Railo/Apache Connector

We need to compile the Apache connector (this comes directly from Luis' blog). Go ahead and open the Terminal.app (located in Applications > Utilities). Once this opens you should type the following: (Do not type the leading "$", this is just to indicate the new line prompt)

$ cd /Applications/railo
$ ./configure --with-apxs=/usr/sbin/apxs --with-java-home=/System/Library/Frameworks/JavaVM.framework/Home

The Terminal.app should start spitting out a whole bunch of codey looking stuff and finally end with something that looks like this:

...
configure: creating ./config.status
config.status: creating Makefile
config.status: creating modules/c/src/Makefile
config.status: creating modules/c/src/common/Makefile
config.status: creating modules/c/src/apache1/Makefile
config.status: creating modules/c/src/apache2/Makefile
config.status: creating modules/c/src/resin_os/Makefile
config.status: creating contrib/init.resin
config.status: executing depfiles commands

This means that it is done compiling the code. So now let's do the make and install to install the mod_caucho.so connector. Luis' didn't mention to do this, but I added sudo in front of my make install command, this will require that you supply your admin password before it will continue. I had thought on my first try I received a permissions error, but I'm not 100%. All I know is that I did this, so I'm passing it along. Anyway, in the Terminal.app type:

$ make
$ sudo make install

Again, you are going to see some lines of codey stuff fly by. Once this is done and you see the prompt again. We are good to go.

Intermission I - What's Going On.

At this point Railo is installed. You can start Railo and test this by typing the following in Terminal.app:

$ /Applications/railo/bin/httpd.sh

Terminal should start spitting out information as Railo is starting up. It will also tell you of any errors. Also, you can also view errors by opening up the Console.app (Applications > Utilities > Console) and see if it alerts you to any errors. Be sure to leave Terminal open and wait for it to say that Railo has started. Now open up Safari and point it to your web server. You should be able to open Safari on your server and just point it to 127.0.0.1. If Apache is running properly and you haven't modified any of the HTML files, you should see the standard Apache welcome screen that comes default with the 10.5 install. Now type the following into the Safari location bar:

http://127.0.0.1/index.cfm

If everything worked properly, you should see Railo's default index.cfm page that contains a bunch of cfdumps. If not then double check everything and make sure you didn't miss a step.

So, even though Railo is installed and working, we still have a couple of problems. The first one is what we just did. We had to start Railo manually by using the Terminal. And Railo will stop if we close the Terminal.app. Not cool. We will need to make Railo start up automatically when the server starts. Secondly, Railo's document directory is not the same as Apache's document directory. Railo's is located in /Applications/Railo/webapps/ROOT. Apache's are located at /Library/WebServer/Documents. I wanted to make one folder that has everything. And because I access this directory from another server on my network, I want to make sure that I don't have any permission issues when I do this.

Step 3 - Change Railo's Default Directory or Web Root

To get Railo to use a new common default directory, I decided to put all of my web files inside one directory within my auto-login user account, which is Nimda. So create a folder inside your main user account and call it "ColdFusion". You should now copy all of the files located within the /Applications/Railo/webapps/ROOT directory into this new folder.

Now we need to tell Railo that we have moved the root folder. Open up /Applications/Railo/conf/resin.conf inside your text editor. You need to modify the following line with the path to your ColdFusion folder (Around line number 258 and swap out Nimba with your user account name):

<web-app id="/" root-directory="webapps/Root" />

to...

<web-app id="/" root-directory="/Users/Nimda/Coldfusion" />

As a side note, I typically comment out lines, and then add a new line with a comment that I modified on a specific date. Like <!-- Modified by DJ on 10/10/10 -->, this way I can go back to the file and easily find what I changed by searching for "modified by DJ". That's it, Railo now has to restart in order to use the new directory root. (You can restart your computer, logout/login or type sudo /usr/sbin/apachectl restart in the Terminal)

Step 4 - Change Apache's Default Directory or Web Root

Now we need to do the same with Apache. Open up /private/etc/apache2/httpd.conf inside your text editor. You need to modify the following lines accordingly.

Around line #163 (Again be sure to use your account name):

DocumentRoot "/Library/WebServer/Documents"

change to...

DocumentRoot "Users/Nimda/ColdFusion"

... and around line #190

<Directory "/Library/WebServer/Documents">

change to...

<Directory "Users/Nimda/ColdFusion">

That's it. Both Apache and Railo should now use the same directory, located in our user folder, to handle all the web files. But wait! There's more...

Step 5 - Tell Apache that we can use index.cfm as well as index.html

Now that the directory has been changed, we need to tell Apache one more thing. We need to let it know that we can now handle .cfm files as well. Easy enough to change so again, in /private/etc/apache2/httpd.conf change the following: (Around line #226)

DirectoryIndex index.html

to...

DirectoryIndex index.html index.cfm

And that's it. Apache will now look for either index.html or index.cfm in a directory to load the default file. If you didn't add this, Apache would show a list of the directory contents instead of loading the index.cfm file. And speaking of this, if you would like to turn off auto index of directories, you can change the following: (Around line #205)

Options Indexes FollowSymLinks MultiViews

to...

Options FollowSymLinks MultiViews

...and around line #99 change:

LoadModule autoindex_module libexec/apache2/mod_autoindex.so

to..

#LoadModule autoindex_module libexec/apache2/mod_autoindex.so

...and finally around line #457 change:

Include /private/etc/apache2/extra/httpd-autoindex.conf

to..

#Include /private/etc/apache2/extra/httpd-autoindex.conf

Step 6 - Automatically Launch Railo on System Start-Up

This was the most difficult thing for me to figure out. I know absolutely zilch about Launch Daemons, but I knew this is what I need to create to get Railo to automatically launch at system start-up. After some digging around and looking at some other LaunchDaemons, here's what I came up with. Create a new text file that contains the following information:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>com.railo.services</string>
        <key>ProgramArguments</key>
        <array>
            <string>/Applications/railo/bin/httpd.sh</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
    </dict>
</plist>

This file needs to be saved to the following location /Library/LaunchDaemons/. I had to come up with a name for this plist file so I decided on com.railo.services.plist. After you save the file, we need to go to the Terminal and change the owner to root. This tells the system that it's ok to run this daemon.

Open up Terminal and type the following commands (You will have to supply your admin password for the sudo command):

$ cd /Library/LaunchDaemons/
$ sudo chown root /Library/LaunchDaemons/com.railo.services.plist

You will need to restart your computer (Or logout/login) at this point to see if its working.

Bonus: Turning On PHP5

If you also plan on doing any PHP development, then you might want to turn on Apple's default php5 installation. It's really fairly simple. Fire up BBEdit and open up the hidden file /private/etc/apache2/httpd.conf, you will need admin privilages. Do a search for "php", you should find it around line 114. Uncomment the line by changing:

#LoadModule php5_module     libexec/apache2/libphp5.so

to...

LoadModule php5_module     libexec/apache2/libphp5.so

You will also want to update the DirectoryIndex again, to accept index.php. To do this just modify the following (Around line #226 and assuming you already added "index.cfm"):

DirectoryIndex index.html index.cfm

to...

DirectoryIndex index.html index.cfm index.php

Restart Apache and you should now have php5 available for your coding pleasure!

The End

That's it. You should now have a complete working Railo and Apache Web Server. If your getting any errors, then be sure that you check the Console log to see what's going on. You can typically see if you supplied a bad path or made a typo. If you followed everything I outlined here to a "T" then give me a shout. It's possible I have a typo or I missed something. I tried to be as thorough as possible, but even I make mistakes.

Good Luck!

[EDIT 9/22/09] - There was a step I left off for disabling autoindex, which has been corrected. Also, I added the method to turn on php.

[EDIT 7/2/10] - Just bought a MacMini and was trying to install Railo on Snow Leopard 10.6 and after the "sudo make install" I kept getting an -j: Invalid Option error when I tried to start it through the Terminal. Not 100% sure what's going on, but I was able to fix it by editing the httpd.sh file located in "/Applications/railo/bin/". For whatever reason the $JAVA_EXE variable is not being set. I wound up changing:

exec $JAVA_EXE -jar ${RESIN_HOME}/lib/resin.jar $*

line to:

exec /System/Library/Frameworks/JavaVM.framework/Home/bin/java -jar ${RESIN_HOME}/lib/resin.jar $*

Not sure what's happening, but it now will start up.... I'll post more info as I continue.