Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Blacklight Plugin
Ruby JavaScript Shell

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Please note: The main Blacklight website is

Installing Blacklight

Some background information

Blacklight is open source discovery software. Libraries (or anyone else) can use Blacklight to enable searching and browsing of their collections online. Blacklight uses the Apache SOLR ( ) search engine to index and search full text and/or metadata, and Blacklight has a highly configurable Ruby on Rails front-end. Blacklight was originally developed at the University of Virginia Library and is made public under an Apache 2.0 license.

Install & Use (With Devise)

Create a new rails 3 application

$ rails new my_app

Add blacklight to your gem file

gem 'blackight'

Install blacklight

$ rails generate blacklight --devise

Run your database migrations

$ rake db:migrate

You will need a Solr setup, referred to in your config/solr.yml. You can install an example jetty container with Solr, that has Solr configured to work with Blacklight's defaults, like:

$ rails generate blacklight:jetty

You can also install your own Solr or use an existing install. But Blacklight configuration needs to match your Solr setup, and there are certain things in a Solr setup that Blacklight requires. To generate some Solr config files that match what default Blacklight expects:

$ rails generate blacklight:solr_conf path/to/output/directory/

Start up your application

$ rails server

Visit the catalog at: localhost/catalog

Install and Use (with a custom user authentication system)

Blacklight 3 requires Rails 3.0 or greater.

Add the blacklight gem to your ./Gemfile

gem 'blacklight'

$ bundle install

If you have a user model already, the Blacklight generator will connect to it automatically during installation. However, you will need to make sure the following named routes are included in your /config/routes.rb file:

match 'new_user_session',          :to => 'Your User Session Controller # Log in action'
match 'destroy_user_session',      :to => 'Your User Session Controller # Log Out action'
match 'edit_user_registration',    :to => 'Your User Session Controller # Account edit action'

One blacklight view uses #to_s on your user model to get a user-displayable account name/identifier for the currently logged in account, you probably want to have such a method.

And you will need to make sure the following methods are available both on controllers and as helpers:

current_user   - Which should return a user object that include Blacklight::User
user_session   - Which should return a user session

Once these are in place, you can run the Blacklight Installation Generator:

rails generate blacklight [MODEL NAME]

Where model name is the name of your user model.

Execute your migrations, and you should be good to go.

rake db:migrate

Start up your application

$ rails server

Visit the catalog at: localhost/catalog

Using Blacklight source checkout as gem for development

The ordinary install instructions install the BL gem (which is not full source code) in wherever your system installs gems.

Sometimes, especially for development, it's useful to check out a complete copy of the blacklight source code, and link your app to that as a 'gem' instead.

Checkout the code:

$ git clone

(While the rails3 branch is still a seperate branch called 'rails3', if you'd like to checkout the rails3 branch, or any other particular branch/tag using ordinary git commands:

$ cd blacklight
$ git checkout -t origin/rails3


Now, in your local app's Gemfile, simply specify that it should find the Blacklight gem at this source checkout location:

gem 'blacklight', :path=>"./relative/path/to/blacklight_checkout"

You can have the blacklight source checkout anywhere you want, referred to by absolute or relative path. You can have it inside your local app's directory if you want, or you can have it outside using a relative path beginning with “../”. If you have it inside your app's root, you can even use 'git submodule' techniques to link your app to a particular git commit, like some of us did in Rails2 Blacklight. (But you probably don't want it in your local apps ./vendor/plugins, that'll likely confuse Rails, since it's already being referred to in your Gemfile).

Running Blacklight's own tests

Any application that refers to a Blacklight gem using a source checkout (see above) can run the automated tests (cucumber and rspec) that come with Blacklight source.

Of course, if you've customized the app quite a bit, the tests may not pass, as they test expected default behavior in some cases. So ordinarily tests are run against a pretty basic stub app. The tests also test authentication features, so expect the app to have auth features installed, for instance with a Devise install.

To run the tests:

  • Create a stub app with BL with devise, following the ordinary instructions for installing blacklight, but linking to a source checkout of Blacklight following the instructions above in “Using Blacklight source checkout as gem for development”

  • You also need to include some gems in your test app's Gemfile needed for running our tests:

    group :development, :test do 
       gem "rspec"
       gem "rspec-rails", "~>2.5.0"       
       gem "cucumber-rails"
       gem "database_cleaner"  
       gem "capybara"
       gem "webrat"
       gem "aruba"
  • run `bundle install` in the test app, and don't forget `rake db:migrate`

  • complete the install of cucumber: 'rails g cucumber:install'

  • remove /public/index.html (blacklight tests expect / to map to catalog)

  • You need to install a jetty/solr with test data for testing. You can do that like this (from your stub app home directory):

    rails generate blacklight:jetty test_jetty -e test
    rake solr:marc:index_test_data RAILS_ENV=test
  • Now use some rake tasks that come with Blacklight to actually run the tests. Run these from your stub app:

    • rake blacklight:cucumber:with_solr – run tests in BL, start and stop the test jetty/solr around tests

    • rake blacklight:cucumber – run tests in BL, no jetty/solr. (Tests will fail unless you start it yourself)

    • rake blacklight:spec:with_solr

    • rake blacklight:spec

    • the standard rails tasks for cucumber/rspec are all included with blacklight: prefix, and should work as expected, but using specs/features defined in BL plugin instead of in your local app. (Not every variant has a :with_solr yet).


Whichever method you choose for installation, be sure you have all the pre-requisites in place. You can find these detailed in PRE-REQUISITES

Running solr

You'll also want some information about how Blacklight expects Apache SOLR ( ) to run, which you can find in README_SOLR

Something went wrong with that request. Please try again.