miscellaneous, etc.

I’ve been working on learning Ruby and getting Rails all figured out. It’s been a lot of fun and I’m pretty happy with the way it’s working out so far. For the last couple of years it’s been all Java all the time and it’s nice to take a break.

My first big task was to get Ruby and Rails working on my workstation. That sounds pretty easy and it is, sort of. There are many introductory tutorials and they get you to the point where you can run some Ruby code and put together a simple Rails project. But that’s where they leave you and it’s a little bit shy of actually deploying a real application. To quote Apple:

To do any serious Rails development you’ll want to install a production-quality web server, database server, and a few other goodies.

And I do. In fact, now that I’m thinking about it, I’d like to get as close to my deployment environment as possible. It’s a real server, it’s running FreeBSD and Apple’s always bragging on the “UNIX underpinnings” so this shouldn’t be too hard. So, yeah, I’d like to install Ruby and Rails, then Apache 2 and MySQL 5. That’d be totally kick ass, I could even move data between my deployment server and my workstation to troubleshoot.

Most of the tutorials don’t deal with these issues. Apple gives it a shot, but they recommend Locomotive. It’s a pretty nice product and I like a nice GUI just as much as the next guy, but this is the sort of thing I’ve become used to dealing with at the prompt. My server is managed from the prompt and maybe this makes me some kind of backwards knuckle-dragger, but I’ve grown to like it that way. I decided that these introductory articles simply are not for me and I needed to write my own (you are reading it now).

The FreeBSD server that I’ll be deploying my fancy new Ruby apps onto has this nice, relatively painless tool/system called port that manages installing and upgrading software. It took me a while to get used to, at first I would tell port to update this or that critical chunk of infrastructure (like PHP) and I’d literally bite my nails as my stomach did somersaults. After doing this for a while and nothing bad happening, I finally learned to de-clench and trust port to do it’s thing.

On Mac OS X we have two choices in this space:

• Fink
• MacPorts

Fink is definitely the road more traveled. I spent some time with Fink back in the day when I was running Panther. It’s modeled after the Debian system, I know very little about the Debian system for managing packages. MacPorts is closer to the FreeBSD port system that I know, so I picked that one (it used to be called “DarwinPorts”, if that rings a bell).

Install MacPorts

Installing MacPorts is pretty easy as long as you have the Xcode tools installed (install them now if you haven’t already). I won’t go over the steps for either here. Before you run over to their installation page and start clicking about willy-nilly, here’s a tip for you: skip directly to step 4.

Installing MacPorts

Once you’ve done that, add the two directories for the MacPorts commands to your path. Open up the terminal and bring up your profile. I used “vi” to do this, if you use TextMate (which you should) use “mate”. instead.

vi .profile

You might have an entry where you export your PATH already. Add this line or alter your existing path.

export PATH="/opt/local/bin:/opt/local/sbin:$PATH"

This puts the MacPorts commands (in /opt/local/…) first in your path. If you install something that Apple already has installed (like Ruby), you’ll use the MacPorts version instead of Apple’s. Exit your Terminal session and open another so that your change takes effect.

Now that MacPorts is installed, give it a chance to update itself and it’s tree of software.

sudo port selfupdate

MacPorts will phone home and get the current tree of software and set it up on your Macintosh. If necessary, it’ll download a new version of itself as well.

Install Apache

Now that MacPorts is all updated and running, you’re all set to install some software. We’ll install Apache 2 first.

sudo port -v install apache2

If you leave off the “-v” flag, you won’t see the output from the compile process. I like to see it so that I know something is actually happening. Port will download the source code for Apache 2, apply patches from the MacPorts project, compile it and then install it. If you haven’t done so already, make sure that “Personal Web Sharing” isn’t running on your Macintosh. You can click it off in the “Sharing” control panel inside the System Preferences application.

Port doesn’t setup a httpd.conf file as part of the install process. It does, however, leave us with a working sample one. We’ll copy that over and use it as a starting point.

cd /opt/local/apache2/conf cp httpd.conf.sample httpd.conf

Enable User Home Directory Serving

This configuration is pretty good, but it won’t serve up files in the Sites folder in your Home folder. You probably want that, I know that I do. Open up the httpd.conf file and scan for a couple lines that read:

# User home directories

#Include conf/extra/httpd-userdir.conf

Remove that hash-mark in front of the “Include” and Apache will start serving up your personal Sites folder. This is very nearly what we want except that the default rules for the user directories are a little too restrictive. Open up that file and take a look…

vi extra/httpd-userdir.conf

I am the master of my workstation, so I’ve configured mine like so:

<directory> AllowOverride ALL Options ALL </directory>

Order allow,deny Allow from all

This lets me do pretty much whatever I want via .htaccess files in my Sites folder. You want to do this too, when you deploy Rails applications they have a bunch of mod_rewrite rules to keep the URL’s looking pretty.

With that done, let Mac OS X know that you want it to startup Apache 2 when the Macintosh starts up.

sudo launchctl load -w /Library/LaunchDaemons/org.macports.apache2.plist

That will instruct launchd to read in the configuration file for Apache 2. If you want to start and stop Apache on command, you can still do that the old fashioned way.

sudo apachectl start

Install mod_fcgid

Myself, I’ll be deploying my Rails applications with mod_fcgid. I’ve had nothing but problems with FastCGI and, lets be honest, it doesn’t look like anyone is working on it. Still, Ruby needs to link against FastCGI. Lucky for us, MacPorts will let us install just the development kit.

sudo port -v install fcgi

With that out of the way, we can install mod_fcgid.

sudo port install mod_fcgid

Port will download, patch, and then compile the package. It’ll do everything but actually update your apache configuration file. Open that file up.

vi /opt/local/apache2/conf/httpd.conf

Scan down to the end of the “LoadModule” section and add one for mod_fcgid to the end.

LoadModule fcgid-module modules/mod-fcgid.so

Those dashes should be underscores (Grrr…) Restart Apache so that these changes take effect. If you’re using launchd, you do it like so…

sudo launchctl stop /Library/LaunchDaemons/org.macports.apache2 sudo launchctl start /Library/LaunchDaemons/org.macports.apache2

Most launchd scripts also have a “restart”, but not this one. I’m sure they’ll get that straightened out eventually. In fact, it might be fixed by the time your read this.

Install MySQL

We’ll need MySQL to provide database services to our Ruby applications. This is very similar to the steps for installing Apache.

sudo port -v install mysql5 +server

Once port has installed MySQL5, you have to initialize the database. Port lists the couple of commands you should run to finish up the MySQL installation. First, initialize the database used by MySQL itself.

sudo /opt/local/lib/mysql5/bin/mysql-install-db –user=mysql

Again, the dashes should be underscores. Damn you, WordPress!

Now that MySQL is installed, you have to tell launchd to load it and start it.

sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5 sudo launchctl start /Library/LaunchDaemons/org.macports.mysql5

With MySQL started and running, you can change the root password. You’ll want to do this twice, once for the root account at localhost and again for root at your hostname. Port should list these commands as well.

mysqladmin5 -u root password ‘mumble2837’ mysqladmin5 -u root -h emma.nervestaple.com password ‘mumble2837’

Install Ruby and Rails

With all of that legwork done, We’re all set to actually install Ruby!

sudo port -v install -v ruby

How easy is that? To install Ruby software and libraries, we’ll want to install gem as well.

sudo port -v install rb-rubygems

We’ll also want MySQL support.

sudo port -v install rb-mysql

And fcgi support.

sudo port -v install rb-fcgi

Lastly, we’ll want to install Rails. We can use gem for that, Rails is more of a Ruby thing and isn’t as dependent on locally installed libraries.

sudo gem install rails

Update: It’s also possible to install the Ruby/MySQL bindings with Gem, but you have to pass in the location of the MySQL library and header files. When you call gem, if your first argument is “––”, subsequent arguments are passed onto the script that builds the C library.

sudo gem install mysql -- --with-mysql-include=/opt/local/include/mysql5/mysql --with-mysql-lib=/opt/local/lib/mysql5/mysql

Adjusting Your Rails Application

With this setup, your Rails application really do not need to be altered very much. The only thing that needs to be changed is the .htaccess and the dispatch.fcgi files in the public folder of the app.

The .htaccess file contains the mod_rewrite rules that keep the URL’s clean and push requests to the dispatch script. Go ahead and pull that file up in your editor of choice. The first step is to comment out the handlers that we aren’t using. The top of your file should look something like this:

# General Apache options AddHandler fastcgid-script .fcgi AddHandler cgi-script .cgi AddHandler fcgid-script .fcgi Options +FollowSymLinks +ExecCGI

We’ll be using the third handler to invoke mod_fcgid. Go ahead and comment out the first two handlers.

Scan down towards the end of the file, you should see a hunk of text that looks similar to this:

# If your Rails application is accessed via an Alias directive,
# then you MUST also set the RewriteBase in this htaccess file.
#
# Example:
# Alias /myrailsapp /path/to/myrailsapp/public
# RewriteBase /myrailsapp

RewriteRule ^$ index.html [QSA] RewriteRule ^([^.]+)$ $1.html [QSA] RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

The Rails application is being served from your home directory and that is very similar to an alias. We have to add a “Rewrite Base” line directly underneath the comments, this will be immediately before the first “RewriteRule”.

RewriteBase /~miles/r4rmusic1/public

My home directory is “miles” and my Rails application is called “r4rmusic”. Now, this won’t actually hide the other folders in your Rails application. That would require an Alias directive to be placed in the VirtualHost for your site and we’re not using an actual VirtualHost.

The last change to your application is to edit the “dispatch.fcgi” file, also in the “public” folder. We’re editing the first line. It should read:

#!/usr/bin/ruby

That will invoke the Ruby instance that came with Mac OS X. We want to use the one that we installed with MacPorts. Change that line to read:

#!/opt/local/bin/ruby

That’s it, everything is all set. To access this Rails app in my web browser, I’d load up an URL like this:

http://emma.local/~miles/r4rmusic1/public

There may be a way to get around the Alias restriction with mod_rewrite rules, but that would complicate this particular setup. For me, this is more than good enough.

That’s it! I hope you find this helpful. I know I’ll be coming back to this article the next time I have to setup another workstation. :)