Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Blacklight is a Ruby on Rails Engine plugin, meaning it provides a small application that runs inside an existing Ruby on Rails project.
This Quickstart will walk you through installing Blacklight and Solr, and indexing a sample set of records. If you want information about configuring Blacklight to use an existing Solr index with your data in it, see the Developing Your Application section of the wiki.
To run Solr, you'll also need Java installed.
You should have Ruby 2.2 or greater installed.
$ ruby --version ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-darwin16]
Blacklight works with Rails 5.x
$ rails --version Rails 5.1.4
$ java -version java version "1.8.0_77" Java(TM) SE Runtime Environment (build 1.8.0_77-b03) Java HotSpot(TM) 64-Bit Server VM (build 25.77-b03, mixed mode)
The output will vary, but you need to make sure you have version 1.8 or higher. If you don't have the required version, or if the java command is not found, download and install the latest version of the JDK from Oracle at http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Creating a new application the easy way
Install the solr_wrapper gem, a dependency of the quickstart template. (Note: if you use
rbenv, you may need to run
rbenv rehash afterwards for the Ruby environment to find the
$ gem install solr_wrapper
After you've installed
solr_wrapper, run the quickstart install template:
What Does the Easy Way Generator Do?
When you run the Rails generator for a new application, you can pass in the name of a file of template commands to be run after the base generator runs. The template file above runs through steps 2-5 of the 'Hard Way' below.
Creating a new application the hard way
Create a new, blank Rails application
$ rails new my_new_blacklightapp $ cd my_new_blacklightapp ...
Append these lines to your application's
gem 'blacklight', ">= 6.1"
Especially if you are running on Linux, you may have to add
then, update the bundle
$ bundle install
Install blacklight using Devise for user authentication:
If you want to use devise you need to install the appropriate dependencies
$ gem install devise devise-guests
$ rails generate blacklight:install --devise --marc --solr_version=latest
--devisewill also generate devise-based Users into your application. If you would prefer to integrate with an alternative user authentication provider, see the User Authentication documentation.
--marcwill also generate
blacklight-marcinto your application, which adds library-specific functionality out-of-the-box.
Run your database migrations to create Blacklight's database tables:
$ rake db:migrate
Easy or Hard: After creating your new application
Make sure your Solr server is running.
$ bundle exec solr_wrapper
You should be able to navigate to Solr at http://localhost:8983/solr/#/blacklight-core/query
Index some data. You can index test the MARC records provided with Blacklight by running:
$ rake solr:marc:index_test_data
Depending on the version of Solr you're using, you may see a warning that can be safely ignored:
Warning: Specifying binary request handling from a Solr Server that doesn't support it. Enable it in the solrconfig file for that server.
Start up your application
$ rails server
Visit the catalog at http://localhost:3000/catalog.
You should see the Blacklight interface with 30 MARC records for testing. Additional MARC records are available from the blacklight-data repository. These can be ingested into Solr using SolrMarc,
$ rake solr:marc:index MARC_FILE=(path to file)
Note: To view your newly indexed data in Solr, you must check the "edismax" option at the bottom of the query interface in the Solr Admin, or add the following to the query URL: &defType=edismax
See Configuring and Customizing Blacklight for information about how to customize the Blacklight user interface, search experience, and more.