A Step-By-Step Guide To Install Railo 3.3 + Resin On Mac OS X 10.7 (Lion) Server
I'm going to wax-poetic for a moment, if you want to just jump to the nitty gritty, then click here. If not, sit back, pour yourself some Jack and enjoy the show.
Hi! My name is Doug, you may remember me from such wacky articles as Installing Railo 3.1 On Mac OS X 10.5 (Leopard), Installing Railo 3.1 On Mac OS X 10.6 (Snow Leopard), and Lion Server. The Little App That Should, But Doesn't.Ahhh, those were the days. I was young, happy and had so much free time. Sometimes I could sit for hours, my windows open (Real windows, not the MS variety), enjoying the cool sounds and smells of summer that would take me away to far away lands. Where the heck has the time gone!?!?
The last article I wrote, Lion Server. The Little App That Should, But Doesn't, was about my total and utter disappointment with the Mac OS X 10.7 Lion Server software. It was one of those moments in my life, when I become extremely disappointed with a company that I admire. I hadn't felt like that since 1996 when Norton Anti-Virus completely toasted a hard drive, causing me to lose 6 months worth of work. Almost a year-to-the-day that I wrote that article, I decided to give it another stab. I downloaded the update, which at the time of this writing was 10.7.4. Just like the previous version, it installed without a hitch. But something was different this time... something I... can't... put in... words... it worked!?!? It's actually working... without... crashing!!! Slow clap for you Apple, Inc. Yes, you deserve a pat on the back. Well, I mean it should have been working a year ago, but still, congrats!
I was pretty stoked and maybe a little drunk with excitement. The thought of getting my years old Mac Mini server up and running with actual server software, which has cool features like iCal, DNS, Mail... I was giddy, like a 5 year old on Christmas morning. I knew before I did anything, I had to make sure that I could get Railo and MySQL running. The first thing I decided to do was try and get MySQL. Believe it or not, this wasn't a problem. They had an installer and I had it up and running within 10 minutes. Next, I decided to jump over to GetRailo.org and see what we was new in the world of Railo. They had an installer as well, but it wasn't Railo with Resin, it was Railo with Tomcat. Resin, Tomcat, what the heck do I care. Tomcat was made by the same dudes who work on Apache, so it's probably better, right? If there was ever a moment of pure unbridled euphoria in this story, this is it. I continued and installed Railo, and for the love of Ron Howard, it went without a hitch. I may have added a couple of lines of code to httpd.conf, but other than that, my sites seemed to be working!
Millions and millions of years from now, when scholars are searching for important moments in history. They will look upon the last day of June, the year twenty-twelve, as being one of the top five happiest moments for any human being on the planet earth. They will also correlate this date with data from other societies, from other planets, and determine that it was also within the top fourteen happiest moments of any person or species in the known universe. As they continue with their research, they will examine the events and players involved in all of the happiest moments and soon make an astounding revelation. This one person that was involved in the top five happiest earth moments, the top fourteen known universe moments, was also involved in one of the top 3 most devastating, most heart-wrenching moments of all time. That person was me.
On June 30th, 2012, I was busy debugging a large site that I had moved off of my development server. On this rare occasion, my server was free of any "current" client projects, I thought this was a perfect time to attempt the upgrade. Unfortunately, do to the fact I was so focused on my clients job, I neglected to truly test my server after the upgrade. I just hit the front page on a few sites and they were in fact working. But unbeknownst to me, they weren't. You see, I make extensive use of SES Url's on all of my sites. These are the cool little url's that look something like this:
Apparently, Apache Tomcat does not handle these. Which is mind-boggling to say the least. Sure there's ways to "hack" it, to get it to work, but most of these fixes require you to hard code the "url-rewrite" rules. That ain't going to fly on my development server. So I spent two days going through every article I could find on the subject and not one of them where able to fix the problem. Seriously, a lot of people swear by Tomcat, but not having the ability to do something as basic as this really was a let down. At this point, I didn't know what to do, because I really was didn't want to have to revery my server back to Snow Leopard. What to do, what to do...
Resin Railo Where Art Thou?
Screw Tomcat. There I said it. And if your reading this article, you may have said it yourself. I wanted my old Railo back. The one that just "worked". But the nice Railo guys didn't make an installer for me and I am far from being any kind of expert when it comes to Apache, config files, terminal and techie mumble jumbolia. Unfortunately, I don't have anyone to turn to for this kind of stuff. I just had to jump in and figure things out. So without further ado, here's what I did, how I did it and how you can be just like me and do it to!
Dum Dum Daaaaaaa
The goal of this install is to get Railo running on my Mac OS X 10.7 (Lion) 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.
- Here's a quick list of my setup:
- Apple Mac Mini Server running Mac OS X 10.7 (Lion) Server
- Railo 3.1.1 w/Resin for Apache (www.getrailo.org/index.cfm/download/) <-- notice the irony?
- MySQL 5.5.25 (This is not really important for this tutorial, just listing what I'm using)
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 will need to have administrator privileges. 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 a web server running. To do this, you need to open up Server.app, click on Web and make sure it's on. 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 Mac OS X Server 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 go to Downloads > Software archive. From here you want to download the last Railo + Resin installer they made for Mac OS X. Don't worry, we'll update this later. At the time of this article, it was version 3.1.1 Download the railo-3.1.1.000-resin-macosx.zipserver. Un-compress the zip archive and place the contents of folder into a new folder called Railo and place this inside the Library. (/Library/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.
Step 2 (This step requires XCode to be installed) - Build the Railo/Apache Connector
I'm not sure if this step is actually needed anymore, but I really don't know. Maybe a smarter person than me can chime in. Anyway, let's compile the Apache connector (this comes directly from my past articles). 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 /Library/Railo $ ./configure --with-apxs=/usr/sbin/apxs --with-java-home=/System/Library/Frameworks/JavaVM.framework/Home --enable-64bit
The Terminal.app should start spitting out a whole bunch of code 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. This is one of the grey areas that I'm not really sure what's going on, but I'm following my previous articles and seems as if the "make install" is not really doing anything, but I'm not 100% sure. I'm still typing it just the same. Anyway, in the Terminal.app type:
$ sudo make $ sudo make install
Again, you are going to see some lines of code 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:
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:
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. Lion Server's Apache files are located at
/Library/Server/Web/Data/Default. 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" />
<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 #189 and #238:
... and around line #265
And now the "hack". Towards the bottom of the file, you should see something that looks like this:
# # mod_caucho Resin Configuration # LoadModule caucho_module /usr/libexec/apache2/mod_caucho.so ResinConfigServer localhost 6800 CauchoConfigCacheDirectory /tmp CauchoStatus yes
2/19/2013 EDIT: We're not going to use that anymore, so comment the entire thing out or remove all together. (To comment it out, just put a # in front of each line).
# # mod_caucho Resin Configuration # #LoadModule caucho_module /usr/libexec/apache2/mod_caucho.so #ResinConfigServer localhost 6800 #CauchoConfigCacheDirectory /tmp #CauchoStatus yes
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 CFML files (.cfm). Easy enough to change so again, in
/private/etc/apache2/httpd.conf change the following: (Around line #301)
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 #279)
Options Indexes FollowSymLinks MultiViews
Options FollowSymLinks MultiViews
2/19/2013 EDIT: For what ever reason, multiviews was causing problems with my .htaccess file. See VirtualHost edit below
More info at Ben Nadel's site: http://www.bennadel.com/blog/2218-Negotiation-Discovered-File-s-Matching-Request-None-Could-Be-Negotiated.htm
Step 5 - Tell Apache That Resin Should Handle Things
Ok, this is a total hack. I'm sure there's a better way of doing things, but this seemed to be the only way I could get Apache to hand things off to Railo. Mac OS X Lion Server has a folder called Sites that's located in
/private/etc/apache2/. From what I can gather, this folder contains all the configuration files for the various ports and virtual hosts. Some of these files, as well as settings, get generated automatically from Lion Server. I had to modify the
0000_any_80_.conf file in my case. Open it up and add the following items towards the bottom (listed in bold):
## 2/19/2013 NOT USED ANYMORE!
## Default Virtual Host Configuration
<VirtualHost *:80> ServerAdmin email@example.com DocumentRoot "/Library/Server/Web/Data/Sites/Default" DirectoryIndex index.html index.php /wiki/ default.html CustomLog "/var/log/apache2/access_log" combinedvhost ErrorLog "/var/log/apache2/error_log" <IfModule mod_ssl.c> SSLEngine Off SSLCipherSuite "ALL:!aNULL:!ADH:!eNULL:!LOW:!EXP:RC4+RSA:+HIGH:+MEDIUM" SSLProtocol -ALL +SSLv3 +TLSv1 SSLProxyEngine On SSLProxyProtocol -ALL +SSLv3 +TLSv1 </IfModule> <Directory "/Library/Server/Web/Data/Sites/Default"> Options All +MultiViews -ExecCGI -Indexes AllowOverride All <IfModule mod_dav.c> DAV Off </IfModule> </Directory> <!-- TELL RAILO TO HANDLE EVERYTHING --> ProxyPreserveHost On ProxyRequests Off <Proxy *> Order deny,allow Allow from all </Proxy> ProxyPass / http://localhost:8600/ ProxyPassReverse / http://localhost:8600/ </VirtualHost>
2/19/2013 EDIT: This is what I am using now to get the .htaccess working properly...
## Default Virtual Host Configuration
<VirtualHost *:80> ServerAdmin firstname.lastname@example.org DocumentRoot "/Library/Server/Web/Data/Sites/Default" DirectoryIndex index.cfm index.html index.php /wiki/ default.html CustomLog "/var/log/apache2/access_log" combinedvhost ErrorLog "/var/log/apache2/error_log" <IfModule mod_ssl.c> SSLEngine Off SSLCipherSuite "ALL:!aNULL:!ADH:!eNULL:!LOW:!EXP:RC4+RSA:+HIGH:+MEDIUM" SSLProtocol -ALL +SSLv3 +TLSv1 SSLProxyEngine On SSLProxyProtocol -ALL +SSLv3 +TLSv1 </IfModule> <Directory "/Library/Server/Web/Data/Sites/Default"> Options All -Indexes -ExecCGI -Includes -MultiViews AllowOverride All <IfModule mod_dav.c> DAV Off </IfModule> <IfDefine !WEBSERVICE_ON> Deny from all ErrorDocument 403 /customerror/websitesoff403.html </IfDefine> </Directory> #Invoke Resin LoadModule caucho_module /usr/libexec/apache2/mod_caucho.so ResinConfigServer localhost 6800 CauchoConfigCacheDirectory /tmp CauchoStatus yes <Location /caucho-status> SetHandler caucho-status </Location> </VirtualHost>
...Also, to get this working properly I had to search for the "mod_caucho.so" file and manually place it into the "/usr/libexec/apache2/" directory.
Again, not 100% sure, but this should pass everything off to Railo. I saw some examples that would only pass ColdFusion files, but was unable to get that to work. All I know is that this works for me!
Step 6 - Automatically Launch Railo on System Start-Up
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>KeepAlive</key> <true/> <key>Disabled</key> <false/> <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.
That's it. You should now have Railo working on Lion 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.