Blacklight

Please see README_PROJECT.rdoc for main information about this project and plugin.

Please see PRE-REQUISITES.rdoc for pre-requisites Blacklight needs.

Please see README_SOLR.rdoc for information about setting up and configuring SOLR (lucene.apache.org/solr).

Note: these instructions apply to releases 2.4.0 and above.

How to install Blacklight

Blacklight uses a new Rails feature called "templates". To install the Blacklight plugin into a new Rails application, run the following command (be sure to answer all of the installation questions):

Installing Blacklight 2.4 (recommended):

  rails ./blacklight-app -m http://github.com/projectblacklight/blacklight/raw/v2.4.0/template.rb

Installing the "trunk", or master branch:

  rails ./blacklight-app -m http://github.com/projectblacklight/blacklight/raw/master/template.rb

After the installation process, make note of the instructions for starting Solr and indexing data. Blacklight depends on Solr so be sure it is running. Start Solr

The template will give you instructions on how to start Solr, copied here for convenience:

  cd jetty
  java -jar start.jar

This starts an instance of jetty with Solr running on port 8983. If you want to start on another port, use Java’s -D argument:

  java -Djetty.port=8888 -jar start.jar

Once you start it you can run your Rails app and it will use this SOLR index (expected on port 8983).

  ./script/server

Now navigate to localhost:3000 and you should have a working demo blacklight application with the test data set! Possible Issues with Gems

ruby-xslt gem: installations on Windows machines may have difficulties with ruby-xslt. This gem is only used for indexing EAD files. To remove this dependency, in bl-demo/vendor/plugins/blacklight/init.rb comment out the line:

  config.gem 'ruby-xslt', :lib=>'xml/xslt' # you may need to install libxml and libxslt

by inserting "#" at the beginning of the line.

Note: as of 2009-08-10, there have been some reports of problems with gems. If you are seeing errors relating to gems, you may need to uninstall other versions of gems if they are already installed, for example:

  sudo gem uninstall nokogiri
  sudo gem uninstall ruby-xslt

Be aware of gems that may have been inadvertently installed in your (home)/.gems directory, rather than in your system location for ruby gems. At least one site encountered difficulties when gems were installed in the account’s directory, rather than in the system location. (This can happen if you don’t use "sudo gem install" but instead use "gem install"). In this case, you may need to remove the account’s version of the gems.

  gem uninstall (gem name)   -  note absence of ''sudo''

If that doesn’t work, you can try the brute force method to remove them:

  cd ~/.gem/ruby/1.8/gems

then remove everything in that directory.

You may also see messages to run refresh_spec when you run the ’’rake gems’’ command; go ahead and follow those instructions. (In at least one case, the refresh_spec command needed to be run many times before the error messages ceased.)