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

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'

And you will need to make sure the following helper methods are available:

  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

== Setting up a development environment

Checkout the code:

  $ git clone git@github.com:projectblacklight/blacklight.git blacklight
  $ cd blacklight

(While the rails3 branch is still a seperate branch called 'rails3':)
  $ git checkout -t origin/rails3

Now create a test bed application inside of Blacklight that will allow you
to include Blacklight as a gem.
The test_app directory already exists, and contains a .gitignore file that
will mean all of the generated code is ingored.  - There are a few directories
already in palce in test_app that WILL be included in the git repository.  These
include:
* test_app/features - which contains cucumber tests for blacklight
* test_app/spec - rspec tests
* test_app/jetty - The blacklight Jetty module (discussed later)
* test_app/data - Another remote module.

To create the rails application:

  $ rails new test_app --skip-test-unit --skip-git

Or if you are using Jruby:

  $ jruby -S rails new test_app -m http://jruby.org/rails3.rb --skip-test-unit --skip-git

Add gem 'blacklight' to the test applications Gemfile:

  gem 'blacklight', :path => '../'

Run bundle install in the test app
  $ bundle install

Install and configure blacklight (with devise setting)
  $ rails generate blacklight --devise

Remove index.html - which will allow the routes to take you directly to the catalog page.
  $ rm public/index.html  (allow us to redirect to catalog)

Migrate your database
  $ rake db:migrate

Get Solr running somewhere.  If you don't have Solr installed, blacklight comes with a default setup.
  $ cd blacklight
  $ git submodule init
  $ git submodule update
  $ cd test_app
  $ rake solr:marc:index_test_data RAILS_ENV=test
  $ cd jetty
  $ java -jar start.jar

Start up your Server, and take a test run. (from blacklight/test_app)
  $ rails server
  
Now go check it out, should be running.

== Running the tests

You will need to add some gems to your test_app's Gemfile

   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
  
  $ bundle install

Install cucumber

  $ rails generate cucumber:install

If you haven't yet done this to load the bundled jetty/solr environment and test data in your blacklight checkout, from the blacklight checkout dir:
  git submodule init
  git submodule update

Load in the test data

  $ rake solr:marc:index_test_data RAILS_ENV=test

Run the tests
  
  $ rake solr:spec 
  $ rake solr:features

==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]