At Envy Labs, we start most projects by setting up a user authentication system. We like ThoughtBot’s Clearance gem for its simplicity, but we’ve found that we often end up adding a common set of additional features on top of what Clearance provides.

So today we’re announcing the public release of our modified version of Clearance, which we’re calling Blue Light Special. In addition to its user authentication system, Blue Light Special provides a simple role system with built-in support for admin users, the ability for an admin to impersonate other users, and starting points for your application layout and administration interface.

Blue Light Special also sets up a few gems that we find ourselves using on most projects. These include:

• delayed_job for processing background jobs
• mad_mimi_mailer for sending emails through Mad Mimi
• mini_fb to support authentication via Facebook Connect

And for testing:

• shoulda
• factory_girl
• webrat
• fakeweb

If you’re thinking, “Blue Light Special seems highly opinionated,” you’re right. We like it that way. It means that all of our projects have a common starting point. We care a lot about performance, and building in support for delayed_job and Mad Mimi right from the start gives us a solid foundation on that front. If you’d like more information about the benefits of using delayed_job, check out Railscasts episode 171. For an overview of Mad Mimi, take a look the the 3rd part of the latest Scaling Rails screencast.

Setting Up Blue Light Special

Install the Blue Light Special gem:

gem install blue_light_special

Require it in your config/environment.rb:

config.gem 'blue_light_special'

Run the blue_light_special and delayed_job generators, then migrate your database:

script/generate blue_light_special
script/generate delayed_job
rake db:migrate

You’ll also want to edit the config/blue_light_special.yml file. Here you can set configuration options for Blue Light Special and the external services that it uses:

#
# The mailer_sender is set as the reply address for all
# notification emails.
#
# Set madmimi_username and madmimi_api_key to your MadMimi
# username and API key.
#
# The impersonation_hash is used to secure user impersonations.
# Set it to a long, random hash.
#
# To turn on Facebook Connect, set use_facebook_connect to true.
#
# If you are using Facebook Connect, you'll need to provide your
# application's API and secret keys from your Facebook
# application settings at http://facebook.com/developers.
#

development:
  mailer_sender: donotreply@example.com
  madmimi_username: MADMIMI_USERNAME
  madmimi_api_key: MADMIMI_API_KEY
  impersonation_hash: REPLACE WITH A LONG RANDOM HASH
  use_facebook_connect: true
  facebook_api_key: FACEBOOK_API_KEY
  facebook_secret_key: FACEBOOK_SECRET_KEY

Now fire up your Rails development server and point your browser at http://localhost:3000/sign_in to give it a try. You’ll be able to sign up using an email address and password or, if you’ve enabled Facebook Connect, sign in using your Facebook account.

In order to see the administration interface, you’ll need to manually create your first admin user. Go to http://localhost:3000/sign_up and create a user:

Now run script/console, find the user you just created, and set the role:

u = User.find_by_email('me@example.com')
u.role = 'admin'
u.save

After you’ve done this once, you’ll be able to use this admin login to give other users admin permissions.

Generating Tests

Blue Light Special can optionally generate integration tests that cover all of its basic features. To generate the tests:

script/generate blue_light_special_tests

After the generator runs, you’ll see instructions for updating test/test_helper.rb to include some helper methods that the tests require. You can use these helper methods in your own integration tests whenever you need to sign a user in or out.

Generating an Admin Interface

The final Blue Light Special generator builds a starting point for your application’s admin interface. This includes controllers and views for managing and impersonating users. To generate the admin controllers and views:

script/generate blue_light_special_admin

This will also generate integration tests for the admin  interface.

Any additional admin controllers that you create should inherit from Admin::AdminController, which provides access control for the admin interface.

Photo credit: Blue Light District

Related posts:

1. Census: Rails Demographics Collection
2. Common Rails command shortcuts
3. The Rails State Machine