Quickstart

Blacklight is a Ruby on Rails Engine, 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.

Dependencies

To get started with Blacklight, first install Ruby and install Rails, if you don't have it installed already. You'll need Ruby 3.0 or higher, and Rails 6.1 or higher.

To run Solr, you'll also need Java installed. If you have Solr running already or your system or in a Docker container, you can skip the Java setup.

If you are installing/developing on Linux, you will also need a JavaScript runtime installed, e.g. nodejs.

Got Ruby?

You should have Ruby 3.0 or greater installed.

$ ruby --version
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-darwin21]

Got Rails?

Blacklight works with Rails 6.1+

$ rails --version
Rails 7.0.4

Got Java?

$ 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.

Assets (Stylesheets and Javascript)

Blacklight is built on top of Rails, which is undergoing a transition in how it handles assets. That means there is more than one "right way". If you are not familiarized with different javascript runtimes or don't have an opinion about the different Rails asset pipelines options, installing nodejs and yarn, as shown below, will make your Blacklight installation easier. However, Blacklight allows other choices, like using sprockets and nodejs.

Got nodejs?

$ node --version
v18.4.0

You may install node, a Javascript runtime library, from your OS packaging system if available, or following the https://nodejs.org/ instructions.

Got yarn?

$ yarn --version
1.22.19

Yarn is needed to install Javascript packages and its dependencies, as part of the Rails Webpacker gem. Please follow the https://yarnpkg.com/en/docs/install instructions. Yarn is very sensible to being up to date, so unless your OS package is the same than upstream, you'll get errors. To avoid them, better use upstream version.

Importmaps

Rails 7 ships with support for importmaps. If this seems like a good fit for your needs, you can avoid installation of yarn. For more, see the documentation on importmap-rails. You'll sill need node as a JS runtime for use with sprockets, part of Rails' asset management system.

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 solr_wrapper executable.)

$ gem install solr_wrapper

After you've installed solr_wrapper, run the quickstart install template:

$ mkdir projects
$ cd projects
$ rails new search_app -m https://raw.github.com/projectblacklight/blacklight/main/template.demo.rb
      create  
      create  README.rdoc
      create  Rakefile
      create  config.ru
      create  .gitignore
      create  Gemfile
      create  app
      create  app/assets/javascripts/application.js
      create  app/assets/stylesheets/application.css
      create  app/controllers/application_controller.rb
      create  app/helpers/application_helper.rb
      create  app/views/layouts/application.html.erb
      create  app/assets/images/.keep
      create  app/mailers/.keep
      create  app/models/.keep
      create  app/controllers/concerns/.keep
  
.
.
.
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled
gem is installed.
$ cd search_app

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 1-4 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 this line to your application's Gemfile
```
gem 'blacklight', ">= 6.1"
```
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
```

Options during Blacklight installation

Including --devise will 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.
Including --marc will also generate blacklight-marc into your application, which adds library-specific functionality out-of-the-box.
Including --solr_version=x.x.x will tell solr_wrapper to use a specific Solr version.
Including --bootstrap-version=(4 or 5) will tell Blacklight to use a specific version of Bootstrap (version 4 or 5 are supported as of Blacklight 8)
Including --skip-assets can be used to skip installation of Style and Javascript assets. This is desirable if you are intending to use Blacklight solely as an API.
Including --skip-solr to skip installation of solr-wrapper and Solr. Use this if you're using the included Dockerfile or already have a Solr index.

See the install generator file to deduce any additional available parameters.

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.

Blacklight Home Page

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.