The Code

Let’s just drop the code in and discuss it afterwards:

# config/sunspot.yml
# copy the test settings into the cucumber environment
test: &TEST
  solr:
    hostname: localhost
    port: 8981
    log_level: WARNING

cucumber:
  <<: *TEST

# features/support/config.rb
# start the Solr server and give it a few seconds to initialize
Sunspot::Rails::Server.start
sleep 5

# make sure that pickle calls #index! on our appropriate models
require File.join(File.dirname(__FILE__), 'pickle')
module Pickle
  module Session

    def create_model_with_sunspot(a_model_name, fields = nil)
      result = create_model_without_sunspot(a_model_name, fields)

      model = model(a_model_name)
      model.index! if model.respond_to?(:index!)

      result
    end
    alias_method_chain :create_model, :sunspot

  end
end

# clean out the Solr index after each scenario
After do
  Post.remove_all_from_index!
end

# shut down the Solr server
at_exit do
  Sunspot::Rails::Server.stop
end

The Details

This method was heavily influenced by Brandon Keeper’s post on using Cucumber with ThinkingSphinx. Thanks Brandon! So in my setup, I’m using Sunspot, Cucumber and Pickle (see Ryan Bates’ railscast on using Pickle with Cucumber for more details on the wonderful Pickle gem).

First and foremost is getting the testing Solr server running. It will look for settings in config/sunspot.yml according to the environment we’re running in, so we need to duplicate the test environment for cucumber. I’ve found that it takes 3-5 seconds for Solr to properly spin up, so we’re sleeping for a few seconds to avoid the problem.

Next we need to ensure that each model gets loaded into Solr’s index when created. If you’re instantiating models on your own, this boils down to calling #index! on any models that you create. Since I’m using Pickle (and didn’t want to rework the included pickle_steps.rb), I needed a bit more invasive measure. A bit of alias_method_chain voodoo lets me call #index! on every instantiated model that responds to it. This ensures that Pickle always adds it’s models to Solr’s index. I was pleased to find that I didn’t have to disable transactional fixtures

Finally, we need to ensure that our index is fresh for each scenario, so we clear the Solr index out after each scenario is run. If you want a more targeted approach, you can use

# features/support/config.rb
# clear Solr index only if we've actually used it
After('@sunspot') do
  Post.remove_all_from_index!
end

to only clear the Solr index after stories which are tagged with @sunspot. Once all the stories are run, shut down the server. Viola!

will_paginate

The current version of the gem (v2.3.12) doesn’t work, as it relies on the now-removed scope method. It looks like there’s a fork out there which resolves the issue, but it hasn’t been merged into master yet.

Formtastic

The current version of the gem (v0.9.7) seems to work just fine. All you need is an initializer to set the gem up and load it into rails:

require 'formtastic'

# from formtastic's rails/init.rb
ActionView::Base.send :include, Formtastic::SemanticFormHelper

validation_reflection

You can use validation_reflection (v.0.3.1) with Formtastic by simply requiring it in the initializer:

require 'formtastic'

# from formtastic's rails/init.rb
ActionView::Base.send :include, Formtastic::SemanticFormHelper

require 'validation_reflection'

Authlogic

Not sure about the working state of the gem yet, but the 2.x style generator is clearly not working. I’ve forked Paul Berry’s list of Rails 3 generators and added a simple user session generator.
Edit: Actually, the gem doesn’t work either. Seems to rely on a before_persisting callback which isn’t there anymore.

Edit II: The before_persisting callback is actually built by Authlogic. It seems the Authlogic::Session::Base module isn’t loading callbacks like it should.

RSpec

This is also a no-go in Rails 3. David Chelimsky, being the always-on-top-of-it developer, is already planning for RSpec 2.0 as a working partner for Rails 3. No sign of it yet in the github repo though. If you’re interesting in playing around anyway, you can find some RSpec generators at the link above.

Bundler

The new gem bundler is indeed pretty sexy. Unfortunately, with all that great work it does, it doesn’t actually load the gems into your Rails environment. Neither do any of the config files (boot.rb, application.rb, etc etc). David Trasbo had some luck adding Bundler.require_env to the end of the environment.rb file bundler creates, though he’s run into load-order troubles. José Valim recommends placing the line at the end of application.rb to ensure the Rails core is loaded first. This takes care of loading all the gems, so you can skip the initializers above.

1. Sunspot includes a development version of Solr

There’s no need to download an official Solr release from Apache for development work. Just install sunspot and you get Solr for free, complete with some nice Rake tasks.

gem install sunspot
rake sunspot:solr:start --starts the solr server
rake sunspot:solr:stop --stops the solr server


2. Using Sunspot in Rails requires the sunspot_rails gem

This one was easy to solve, but still surprised me a bit. The sunspot gem only provides the base interaction with the Solr server. In order to get ActiveRecord integration, you need to add the sunspot_rails gem:

# config/environment.rb
config.gem 'sunspot', :lib => 'sunspot'
config.gem 'sunspot_rails', :lib => 'sunspot/rails'

$ rake gems:install

3. Text Analysis is setup in Solr, not in Sunspot

It seems there’s not much written in the Sunspot documentation/groups about text analysis (such as word stemming, stop word filters, synonyms analysis, etc), and for good reason. These settings are defined in Solr’s setup via the schema.xml file. More details on Solr’s text analysis abilities can be found on Apache’s website. If you’re using the install you get with Sunspot, you can find this in RAILS_ROOT/solr/conf/schema.xml.

4. Sunspot executes its search DSL in a new scope

This one took me forever to figure out. By default, any details passed into Sunspot.search are not evaluated in the current context. This means that trying to search directly from the controller just doesn’t work as I expected. There’s no mention of this in sunspot_rails’ documentation, but there’s a brief snippet in sunspot’s:

If the block passed to search takes an argument, that argument will present the DSL, and the block will be evaluated in the calling context. This will come in handy for building searches using instance data or methods

So, in order to search from the controller (or rather in the model, like you should), you’ll need to pass an argument to the Sunspot.search block:

@search = Sunspot.search(Post) do |query|
query.keywords params[:query]
end

Basic S3 Setup

After registering for the service at Amazon’s site, you’ll need to collect your access credentials to allow Rails to connect to your account. You can find this in the Security Credentials link under the Your Account menu. Create a simple yaml file in your config directory with the following details:

# config/s3.yml
access_key_id: <your access key here>
secret_code: <your secret code here>

Note that this file can be configured to support multiple environments as well:

# config/s3.yml
development:
  access_key_id: <your development access key here>
  secret_code: <your development secret code here>
production:
  access_key_id: <your production access key here>
  secret_code: <your production secret code here>

S3 Buckets

I found that the tricky part in setting up Paperclip was dealing with S3 buckets. Buckets are something like file folders in the cloud, with the unusual stipulation that each bucket name must be unique across the entire service. Paperclip requires that you specify an S3 bucket to store your files in; unfortunately it doesn’t handle the creation of the buckets for you. That’s where the aws-s3 gem comes into play. Install it with gem install aws-s3, drop into the Rails console and execute the following:

# load the aws-s3 gem
>> require 'aws/s3'
=> []
# connect to your account
>> AWS::S3::Base.establish_connection!(YAML.load_file('config/s3.yml').symbolize_keys!)
=> <AWS::S3::Connection:0x2236d90 @secret_access_key=<your secret key>, @http=#<Net::HTTP s3.amazonaws.com:80 open=false>, @access_key_id=<your access id>, @options={:access_key_id=><your access id>, :secret_access_key=><your secret key>, :server=>"s3.amazonaws.com", :port=>80}>
# create your unique bucket
>> AWS::S3::Bucket.create('your_unique_s3_bucket')
=> true

Paperclip with S3

Once you’ve got your configuration file set and bucket created, it’s time to set up your model. Paperclip’s RDOC is really great at describing all the various options for their model and is well worth the time to read through. On top of that, there are several great tutorials on getting Paperclip running. The basics though, with the important S3 bits added, look like this:

# models/photo.rb
has_attached_file :image,
  :styles => { :thumbnail => "100x100>" },
  :storage => :s3,
  :s3_credentials => "#{Rails.root}/config/s3.yml",
  :bucket => "your_unique_s3_bucket";

Note that you can specify the :bucket option in your config/s3.yml file instead.

Using ImageMagick to Auto-Orient Images

With the above, you’ll have a functional S3-backed Paperclip-powered model. I quickly ran into an annoying problem though. Modern digital cameras add special metadata to their photos that indicates the orientation of the camera when a photo is taken. Unfortunately, most web browsers aren’t smart enough yet to handle that extra info, so whereas the photo appears as intended on the desktop, it appears flopped onto its side on the web. Some developers have taken to using RMagick to properly orient their photo uploads, but I’ve found that there’s a simpler way. Paperclip exposes a hook to send custom conversion flags straight to ImageMagick when a photo is uploaded. Even better, ImageMagick has a simple flag -auto-orient to handle automatically orient images according to their metadata. Simply change the model above to:

# models/photo.rb
has_attached_file :image,
  :styles => { :thumbnail => "100x100>" },
  :storage => :s3,
  :s3_credentials => "#{Rails.root}/config/s3.yml",
  :bucket => "your_unique_s3_bucket",
  :convert_options => { :all => "-auto-orient" }

You’ll now have a modern-camera-friendly, cloud-hosted image attachment system for your app. Enjoy!