Last night, one of those friends retweeted a request for a guard plugin to work with the annotate gem.

I figured that was good a cause as any to finally dig in and give guard a try. What better way to begin using and understanding a gem, then by writing an extension for it?

About two hours later, I released the first versions of guard-annotate on rubygems.org (source code on Github).

So, if you use the annotate gem on your rails projects, as well as guard, feel free to give the gem a try and save your self some time re-running your annotations.

As always, comments and questions, as well as pull requests for features and bugfixes are welcome.

** UPDATE **

guard-annotate has now been officially added to the main guard repository on GitHub. You can still install the gem the same way, but now you can also find the codebase on the guard page at GitHub as well.

Today I’m making publicly available the first beta version of my new Echowaves Notofier for OS X.

The Echowaves Notifier is a simple OS X status bar application that will provide updates for when you have new messages in any conversations you follow on Echowaves.com.

The app is pretty simple at this point, but the core functionality works and I’m hoping to get some people to test it out. Next up is adding growl support and some user preference options.

The source code is available on github.com and the application is released under the MIT License so feel free to hack away on it if you like. If you do, please submit back any modifications so they can be included back into the “official” release.

The gem (and zip and tarballs) are all available now via RubyForge.

Thanks to all who had a part in this release. Paul Hinze added bazaar
SCM support. Joe Van Dyk did some general code cleanup and Git SCM
updates.

So, grab the new version and kick the tires with it. Get the word out.

I’d really like to see Cerberus get some more usage and to see it grow
into a really mature, lightweight tool in the coming months.

Here is the changelog details for version 0.7

== Version 0.7
New config options, Bazaar SCM support, removed GMailer bugfixes

* added support for bazaar scm
* fixed bug with ActionMailer 2.3.3
* removed GMailer library. Use default Mail publisher instead
* added ‘build_dir’ option for setting custom build directory
* added ‘setup_script’ option for a custom script to be run before build command
* Projects using the Git SCM were not getting the full diff output in
their Publishers

This is probably because of the spindump utility that OS X launches to create crash and “hang” reports located in /Library/Logs/HangReporter.

This is all fine and good, but spindump has an annoying habit of thrashing your system disk and eating up a sizable chunk of RAM. Personally, the MAJOR annoyance isn’t worth the aggravation just to get a useless “hang” report like the following.

Date/Time:      2008-07-09 16:33:26 -0400
OS Version:     10.5.4 (Build 9E17)
Architecture:   i386
Report Version: 4

Command:        Skitch
Path:           /Applications/Skitch.app/Contents/MacOS/Skitch
Version:        1.0b6.2 (1.0b6.2 (v10678))
Parent:         launchd [107]

PID:            377
Event:          hang
Time:           7.75s
Steps:          1

I’m sure there are many ways to disable this utility, but here is a quick an easy method I used to prevent the “sluggishness” after an app crash

sudo -i
cd /usr/sbin
mv spindump spindump.disabled
ln -s /usr/bin/true /usr/sbin/spindump

Problem solved!

Thinking it over, I clearly had two options: 1) code my own custom forum system for the site, or 2) use an existing forum system.

While I don’t mind coding forums for the site, I really didn’t want to set aside the time needed for coding when I could have been working on plenty of other projects. So, I set out researching existing forum software that I could utilize.

In searching for a third-party forum system, I really only had one major requirement – users needed to be able to login to the main website and be authenticated at the same time on the forums. I didn’t want my users to have to maintain separate accounts and separate logins for the forums and the main website. If I did, there would be no need for this tutorial as implementing standalone forums is a basic task.

First off, I researched existing forum systems that were already rails based, hoping there was something I could quickly integrate into my app. I checked out all the regular suspects like Beast, Altered Beast, Savage Beast 2, and the new rBoard.

Of the existing rails forums, rBoard showed the most promise but none of them really work well for integrating into an existing, established rails app. All of the rails options are really intended for standalone use as a forum only.

Next I proceeded to research non-Rails based forums like bbPress, vBulletin, phpBB and a handful of others.

I ended up settling on the punBB forum software, written in PHP. I chose punBB for a few reasons: 1) it was a lightweight forum system, 2) it seemed to get good reviews online, and 3) I was able to find some existing information online on integrating punBB with Rails.

Terrell Russell wrote two blog posts (post one, post two) regarding running PHP from within a Rails environment and how to get punBB (and DokuWiki) running within a Rails app using single sign-on. I used Terrell’s posts as a starting point for my project as some of his information is now outdated for both Rails 2.3x and punBB 1.3x.

Now, on to the tutorial.

My next decision was to choose how exactly to integrate the PHP code into my Rails app. I could put the forum’s PHP code into my application’s

RAILS_ROOT/public/forums/

directory, or I could install the forums somewhere else on my servers file system.

Since the forums really are their own separate application, and the code is independent of my Rails code, I decided to install punBB on its own and leave it out of my source repository. This will allow me to maintain/upgrade/modify the forum software without touching my Rails repository.

As a side note, your server must be able to run PHP. My app server is a Debian Lenny system and I installed PHP via the normal

$ sudo aptitude install

routine. (Installing PHP on your server is beyond the scope of this tutorial.)

I went ahead and setup the punBB files into

/var/www/punbb

on my server. I want users to be able to access the forums by visiting http://xboxmma.com/forums, so there were a few additional steps I needed to take.

First, when I deploy my app via capistrano, I setup a symlink in the public directory to point to my forum installation. I also copy the forum config file into my Rails app config directory (I’ll explain why later). Add the following code to your capistrano deploy file.

# RAILS_ROOT/config/deploy.rb
desc "Setup settings for punBB forums"
task :after_symlink, :roles => [:app] do
  run "ln -nfs /var/www/punbb #{release_path}/public/forums"
  run "cp /var/www/punbb/config.php #{release_path}/config"
end

My app server uses Nginx as the web front end, so I also needed to update my nginx configuration to properly route requests for the new forums.

My existing nginx configuration file looked like this

server {
        listen  80;
        server_name xboxmma.com;
        root /home/deploy/xboxmma.com/current/public;
        passenger_enabled on;
        access_log off;
        client_max_body_size 20M;

        location ~* \.(ico|css|js|gif|jp?g|png)(\?[0-9]+)?$ {
                expires max;
                break;
        }

        if (-f $request_filename) {
                break;
        if (-f $document_root/system/maintenance.html) {
                rewrite ^(.*)$ /system/maintenance.html break;
        }

        error_page 500 502 503 504 /500.html;
        location = /500.html {
                root /home/deploy/xboxmma.com/current/public;
        }
}

I updated it with the following sections

        location /forums {
                root /var/www/punbb;
                index index.php;

                if (-f $request_filename) {
                        expires 30d;
                        break;
                }

                if (!-e $request_filename) {
                        rewrite ^(.+)$ /forums/index.php?q=$1 last;
                }
        }

        location ~ \.php$ {
                fastcgi_pass 127.0.0.1:9000;
                fastcgi_index index.php;
                fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
                include /opt/nginx/conf/fastcgi_params;
        }

        location ~ /\.ht {
                deny all;
        }

The

location /forums {}

block will process all requests that are made to the /forums path on my site. I set the document root to

/var/www/punbb

where I installed the punBB software and set the index page to index.php.

The

location ~ \.php$ {}

block catches any request for a php page and passes the request along to the php5-cgi processor to handle the request.

The end result config file looks like this:

server {
        listen  80;
        server_name xboxmma.com;
        root /home/deploy/xboxmma.com/current/public;
        passenger_enabled on;
        access_log off;
        client_max_body_size 20M;

        location ~* \.(ico|css|js|gif|jp?g|png)(\?[0-9]+)?$ {
                expires max;
                break;
        }

        location /forums {
                root /var/www/punbb;
                index index.php;

                if (-f $request_filename) {
                        expires 30d;
                        break;
                }

                if (!-e $request_filename) {
                        rewrite ^(.+)$ /forums/index.php?q=$1 last;
                }
        }

        location ~ \.php$ {
                fastcgi_pass 127.0.0.1:9000;
                fastcgi_index index.php;
                fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
                include /opt/nginx/conf/fastcgi_params;
        }

        location ~ /\.ht {
                deny all;
        }

        if (-f $request_filename) {
                break;
        if (-f $document_root/system/maintenance.html) {
                rewrite ^(.*)$ /system/maintenance.html break;
        }

        error_page 500 502 503 504 /500.html;
        location = /500.html {
                root /home/deploy/xboxmma.com/current/public;
        }
}

Now that the boring php processing and routing stuff is out of the way, lets get into the important stuff and look how to integrate the authentication system of punBB and the Rails application.

The “trick” we will be using, is to manually set the login cookie for punBB whenever a user logs into the main website (we’ll delete the cookie as well when the user logs out). The login cookie format has changed a bit since Terrell’s writeup, so I had to get my hands dirty and dig into the punBB PHP codebase to see exactly how they are setting their cookies.

First, add the following code to your application controller (or another controller if you don’t want/need the methods to be available everywhere).

# RAILS_ROOT/app/controllers/application_controller.rb
  def set_shared_cookie
    return true unless Rails.env.production?
    require 'base64'
    expires = Time.now.to_i + 1209600

    begin
      # this sets the punbb cookie
      # it should be called on login from main site to allow unified login
      forumconfig = get_forum_config_data() # private method at bottom
      forumuser = ForumAccount.find_by_username( current_user.username )

      forum_hash = Digest::SHA1.hexdigest( forumuser.salt + Digest::SHA1.hexdigest( expires.to_s ) )
      cookie_value = "#{forumuser.id}|#{forumuser.password}|#{expires.to_s}|"
      cookie_value << Digest::SHA1.hexdigest( "#{forumuser.salt}#{forumuser.password}#{forum_hash}" )

      cookies[forumconfig[:cookie_name]] = {
        :value => Base64.encode64( cookie_value ),
        :expires => 14.days.from_now
      }
    rescue => e
      Rails.logger.warn "Problem setting punBB cookie #{e.message}"
    end
  end

  def clear_shared_cookie
    return true unless Rails.env.production?
    begin
      # should be called on logout from main site
      forumconfig = get_forum_config_data() # private method at bottom
      cookies[forumconfig[:cookie_name]] = nil
    rescue => e
      Rails.logger.warn "Problem clearing punBB cookie #{e.message}"
    end
  end

  private

  # Uses regex to parse the php punbb config file
  # taken from: ahgsoftware.com/punbb_sdk/
  def get_forum_config_data
    config_hash = Hash.new
    c = File.read( File.join( RAILS_ROOT, 'config', 'config.php' ) )
    c.scan(/\$(\w*)\s*=\s*['"](.*)['"];/).each do |pair|
      config_hash[pair[0].to_sym] = pair[1]
    end
    config_hash
  end

The

#get_forum_config_data

private method simply reads the punBB config.php file to get the forum configuration info. (Remember we copied the config.php file over in our capistrano deploy addition.)

Both the

#set_shared_cookie

method and the

#clear_shared_cookie

method will only run during production mode. I don’t have punBB setup on my dev system. If you run a staging server you probably want to change it to check

Rails.env.development?

so that the method will also be processed on your staging server.

You’ll also notice I wrap everything in both methods in a

begin ... rescue

block. I don’t want errors in the cookie creation/deletion to throw errors to the users, so I just log then gracefully for now.

Let’s do a quick run through on the #set_shared_cookie method. First we set an integer expiration date to 14 days in the future (the default punBB cookie length). Next we read the forum config data and find the existing user record from the punBB database via the ForumAccount model. We’ll look at the ForumAccount model in a bit.

Next we set the cookie value so it appears in the same format the punBB will expect when it reads the cookie back in and write the cookie to the session.

For XBoxMMA.com I use Authlogic as the authentication system, so I call the set_shared_cookie method from my user_sessions controller after a new session is created. I also call it from my users_controller when a new user is created. I call the clear_shared_cookie method when the user logs out.

Now that we’ve seen how to make the shared cookie, lets look at the models used to access the punBB database tables.

I use a separate database for punBB instead of dumping the tables into my rails app DB, so I added an extra section to my

RAILS_ROOT/config/database.yml

file.

forums_production:
  adapter: mysql
  database: xboxmma_forum
  username: xboxmma
  password: password
  host: localhost
  encoding: utf8
  socket: /var/run/mysqld/mysqld.sock

If you are using a staging environment, be sure to add a “forums_staging” section as well.

Next, I added two new models to access the punBB DB.

# app/models/forum.rb
class Forum < ActiveRecord::Base
  self.abstract_class = true
  establish_connection "forums_#{Rails.env}"
end

# app/models/forum_account.rb
class ForumAccount < Forum
  set_table_name 'users' # add the table prefix if you set one in punBB

  def encrypt_and_save_new_password( _password )
    write_attribute( "password", forum_hash( _password ) )
    save
  end

  private

  def forum_hash( _str )
    Digest::SHA1.hexdigest( self.salt + Digest::SHA1.hexdigest( _str ) )
  end

end

The

#encrypt_and_save_new_password

method should be called anytime your user updates their password in your Rails app. This method will update their forum password at the same time and keep the two in sync.

Now you have Rails models setup that will be able to access your punBB DB (you will remember the ForumAccount model we referenced earlier in the set_shared_cookie method).

Everything should now be working for you. Don’t forget to run the

admin/install.php

script as well to setup your initial punBB configuration.

The Rails project I’m working on has one action that accepts an *.xls format to deliver an excel spreadsheet to the user. Getting this to work is very simple, but for the sake of explanation here is the process.

Simply register the mime type in an initializer file

# config/initializers/mime_types.rb
Mime::Type.register "application/vnd.ms-excel", :xls

Then in your controller action’s respond_to block you can simply reference the new format:

# app/controllers/my_controller.rb
def my_action
  ...
  respond_to do |format|
    format.xls { send_file ... }
  end
end

Now, back to the “bug” or issue with IE6 and IE7. Every time a user hit that specific action with a regular request (not requesting the *.xls format), they received both the expected HTML output AND the xls format output.

Naturally, I don’t want to bombard the user with an IE popup dialog asking them to download an Excel file when they aren’t requesting one.

A quick trip to Google turned up this old Rails ticket. The issue appears to be with how IE6 and IE7 set their HTTP_ACCEPT headers:

image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/x-shockwave-flash, application/vnd.ms-excel, application/vnd.ms-powerpoint, application/msword, application/xaml+xml, application/vnd.ms-xpsdocument, application/x-ms-xbap, application/x-ms-application, */*

There are two easy work-around solutions.

First, you can manually check and set the format param for IE requests:

before_filter :hijack_ie_default_format

def hijack_ie_default_format
  if request.user_agent =~ /MSIE/ and params['format'].nil?
    params['format'] = 'html'
  end
end

However, be careful when doing this. If your action can also accept AJAX ( text/javascript ) requests, then this will override that as well and set the format to return as HTML which is obviously not what you want. You would then end up spending a few hours wondering why IE6 and IE7 where returning javascript “Syntax Errors” on your AJAX actions.

What I ended up doing, since I needed that specific action to respond to javascript requests as well, was to simply extract the excel request into its own action. Sure this may be overkill and not very DRY, but it is still a proper solution. I just created a new #excel_export action and updated my excel links to point to the new action.

The release included some better test support, as well as support for git branches and custom settings file inclusion for the Maven2 builder.

No, sooner had version 0.5 been released, then we began work in earnest on version 0.6

Mike Gunderloy has been working on adding features to Cerberus to support using a custom Ruby script as a project builder. The main reason, is to build the Rails project using their ci_setup.rb, CruiseControl build script.

The current code with Ruby builder support can be found in the ruby_builder branch of the main repository at the moment.

In addition, Mike wrote an excellent blog post on how he is building Rails using Cerberus and multiruby.

While trying to boost my YSlow score, I was having a bit of difficulty trying to figure out how to set HTTP expires headers on all the static assets served by my app.

Rails will set an internal time stamp on static assets (images, css files, javascript files, etc…) by appending a integer value onto the end of the asset filename

http://mydomain.com/images/asset.png?12345678

My original attempt at getting nginx to set an expires header for these assets had me adding the following location block to my nginx config file:

location ~* \.(ico|css|js|gif|jpe?g|png)\?[0-9]+$ {
    expires max;
    break;
}

The regexp I was using was incorrect however as it didn’t take into account that the ?timestamp might not exist in the URI.

Hongli Lai kindly pointed me in the right direction and showed me the proper regexp that he is using.

location ~* \.(ico|css|js|gif|jpe?g|png)(\?[0-9]+)?$ {
    expires max;
    break;
}

./script/plugin install -h

yielded the helpful information I needed. Last July, a patch was committed to Rails that added the -r ( or –revision ) parameter.

The -r parameter will take either the name of a git branch or a tag string to checkout instead of the default master branch.

So issuing the following command:

./script/plugin install git://github.com/cpjolicoeur/my_plugin.git -r BRANCH_NAME

will checkout the BRANCH_NAME branch of the git repository.

Very helpful when testing and debugging new features and bugfixes in a plugin.

As a result, I couldn’t use the traditional Apache rewrite rules to display the maintenance.html page if it existed.

Here are the necessary corresponding rewrite rules for nginx to achieve the same effect.

if (-f $document_root/system/maintenance.html) {
    rewrite ^(.*)$ /system/maintenance.html break;
}

Place this inside your server {} block and you should be able to run cap deploy:web:disable and cap deploy:web:enable with no problems.