Configuration Cauldron

Before we go any further, you have got a Rails app to deploy, haven't you? If not, you had better read up on some tutorials first and create one. Be mindful that your Rails app's public/dispatch.fcgi file has the right Ruby in the path. I edited mine and hardcoded it to /opt/local/bin/ruby, which is the path of the DarwinPorts Ruby installation.

I had a specific end state in mind when I wrote this guide. I had a VirtualHost configured on this Apache installation, and I wanted to install my Rails app against a specific URL that didn't actually exist in the DocumentRoot.

Let's say for argument's sake the host was http://www.hagus.net. I wanted to access my Rails app at http://www.hagus.net/railstest. But obviously I don't want my whole Rails app living in the DocumentRoot; I want it somewhere like /Users/hagus/src/railstest. How to make this happen?

First, we dive into httpd.conf. We need to add a few extra configuration lines to make sure FastCGI is completely ready to rock & roll:

For cleanliness, we wrap these files between an IfModule declaration, in case we disable FastCGI in the future for some reason. The two config lines are simple: we declare a temporary directory for the FastCGI process to write out various files; then we add a handler to tell Apache that files ending in .fcgi are FastCGI scripts.

Before we go any further: be very aware that changes to the httpd.conf file and friends may be overwritten by Server Admin. Unfortunately this is a difficult situation, as Server Admin doesn't really let us edit the httpd.conf file in a granular enough fashion. So we're forced to hand-edit.

A workaround to protect your httpd.conf modifications is to set the "immutable" bit with the chflags command. In reality, if you're diving in and editing your httpd.conf file manually, you probably don't lean heavily on Server Admin anyway.

Now, we must edit the VirtualHost directive for our host to finish the job. Add these lines inside the <VirtualHost> for your site (OS X Tiger stores its VirtualHosts in /etc/httpd/sites, in case you're having trouble locating them):

Alias /railstest "/Users/hagus/src/railstest/public"
<Directory "/Users/hagus/src/railstest/public">
AllowOverride all
Allow from all
Order allow,deny
</Directory>

We first declare an Alias. This gets me what I wanted: a URL on my website that actually terminates outside the DocumentRoot. We then use a standard Directory tag to set the AllowOverride preference. We need this set to allow .htaccess in the public directory to do its job. You could also add some HTTP authentication directives here too, if desired.

There's just one more bit that needs to be taken care of. We need to edit the public/.htaccess file of our Rails app. We must set the RewriteBase directive correctly so that requests are correctly routed to dispatch.fcgi. Locate the line that says RewriteBase, and uncomment it appropriately. In my case:

RewriteBase /railstest

We must also choose to use dispatch.fcgi rather than dispatch.cgi. This is a simple matter of changing the appropriate RewriteRule line from this:

RewriteRule ^(.*)$ dispatch.cgi [QSA,L]

to this:

RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

Now give your web server a kick in the guts (pardon the Australian colloquialism):

# /usr/sbin/apachectl restart

And you should now be able to access your Rails app!

Final Thoughts

You should now have a Rails app living at http://www.yoursite.com/yourapp/. Your Rails app should be "teh snappy" thanks to the wonders of FastCGI.

Your Ruby, Rails, Gems, and FastCGI installations are being managed out of the DarwinPorts distribution system. Your Apache and MySQL are still managed by Mac OS X Server, but we have had to hand-edit httpd.conf. We also had to hand-compile the FastCGI Apache module.

On my own RoR installation, I have everything checked into Subversion, which is also available via DarwinPorts:

# port install subversion

So when I make a change in development (I use the excellent Locomotive all-in-one environment) and confirm that it works, I can just log into my production server and issue the checkout command to refresh my code. Simple and elegant, the way Ruby on Rails should be. :)

Luke Burton
chipped his teeth on C++, and
has lately sought refuge in the beautiful world of scripting
languages like Ruby and Perl.