Please note: The main Blacklight website is http://projectblacklight.org

=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 ( http://lucene.apache.org/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 

  /my_app/Gemfile
  ...
  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:  http://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'

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. 

(TODO: Instructions on how to tell BL the name of your user model if it's
not User?)

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

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

  rake db:migrate

Start up your application

  $ rails server

Visit the catalog at:  http://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 git@github.com:projectblacklight/blacklight.git  

(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"
       end
* 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). 


==Pre-requisites
Whichever method you choose for installation, be sure you have all the pre-requisites in place. You can find these detailed in {PRE-REQUISITES}[https://github.com/projectblacklight/blacklight/wiki/PRE-REQUISITES]

==Running solr
You'll also want some information about how Blacklight expects Apache SOLR ( http://lucene.apache.org/solr ) to run, which you can find in {README_SOLR}[https://github.com/projectblacklight/blacklight/wiki/README_SOLR]