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.

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

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 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.

The latest changes include some minor bugfixes, better RSpec support, the ability to write and use your own custom publishers, and a cron-like scheduling option for the ‘buildall’ command.

Also of important note, the official tracker for issues and bugs has been moved from RubyForge to a new Lighthouse tracker. Also, a mailing list / public forum has been setup for discussion.

As usual, you can grab the newest gem from RubyForge or download the source code at GitHub.

The new major features include the Twitter publisher support that I added and the Git SCM support added by Rob Kaufman. Several other minor updates and bug fixes were also included.

Cerberus is a lightweight Continuous Integration package written in Ruby. The package hadn’t been under active maintenance lately, but I hope to be able to get some new work done on the project now that I am on the development team.

Unfortunately, Cerberus doesn’t seem to still be under active maintenance as the most recently commit on the main RubyForge SVN repository was back in July of 2007. Since Cerberus was written under the MIT License, I made a copy of the repository and posted it to GitHub.

At the moment, Cerberus appeared to be missing two major features as far as I was concerned. First, no git support for an SCM and second, no Twitter support for posting build success and failure notifications.

A quick search of Github revealed that Rob Kaufman had already added git support so I went ahead and added Twitter support to Cerberus.

I plan on pulling the git support into my git repository and submitting a patch to the official Cerberus project. Hopefully the original developers are still around and willing to update the repository. If not, feel free to clone or fork my copy of Cerberus for the new features.

I haven’t done much work with the ParseHTML library, simply because I wasn’t actively doing development on the ClothBlue HTML-to-Markdown library. ClothBlue is the reason I wrote ParseHTML in the first place. Well, I’ve had some downtime and figured I would revive the ClothBlue rewrite effort and that meant getting ParseHTML up to snuff.

The library should be fully working now as most of the previously reported bugs have been sorted out. If you find any issues or new features you want added, just let me know.

I’ve been using Bob Aman’s standard FeedTools library to grab and parse some RSS feeds for output in a WordPress site.

Now, it was obvious to me this had something to do with character encoding issues so I dug in to find out the problem. It turns out FeedTools converts the feeds it parses to UTF-8 encoding, which is great, but can result in some strange characters in the string depending on what the original feed encoding was.

Viewing the native feeds in a feed reader I could see they were simply quotes, apostrophes and ellipses characters. I needed a way to either convert these character strings into ASCII printable characters or simply discard them altogether.

I didn’t want to go through the process of setting up a translation table for every possible character code that might possibly show up in a feed title, so I simply chose to discard the “unprintable” strings completely. I came across this post by Obie Fernandez and decided his simple method would work for me.

require 'iconv'

class String
  def to_ascii_iconv
    converter = Iconv.new('ASCII//IGNORE//TRANSLIT', 'UTF-8')
    converter.iconv(self).unpack('U*').select{ |cp| cp < 127 }.pack('U*')
  end
end

Ruby’s built-in Iconv library can be used for charset conversions. I extended the String class to include a new to_ascii_iconv method. This method creates a new Iconv converter that will convert from UTF-8 encoding to ASCII encoding. The IGNORE and TRANSLIT flags tell the converter to ignore errors and transliterate accented chracters to an appropriate charcter in the ASCII charset. Next, I use the newly created converter to do the conversion and then strip out any characters with decimal values higher than 127 (non-ASCII printable characters).

The results are exactly what I needed. No “funky” characters in my output.