spotlight
| | Release Notes | Design Documents
Spotlight is open source software that enables librarians, curators, and other content experts to easily build feature-rich websites that showcase collections and objects from a digital repository, uploaded items, or a combination of the two. Spotlight is a plug-in for Blacklight, an open source, Ruby on Rails Engine that provides a basic discovery interface for searching an Apache Solr index.
Read more about what Spotlight is, our motivations for creating it, and how to install and configure it in the wiki pages. You might also want to take a look at our demo videos, especially the tour of a completed Spotlight exhibit and the walkthrough of building an exhibit with Spotlight.
Requirements
- Ruby (2.7 or greater)
- Rails (5.2 or greater)
- Java (7 or greater) for Solr
- ImageMagick (http://www.imagemagick.org/script/index.php) due to carrierwave
Installation
To bootstrap a new Rails application:
$ SKIP_TRANSLATION=1 rails new app-name -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb
or from an existing Rails application:
$ SKIP_TRANSLATION=1 rails app:template LOCATION=https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb
During this process you will be prompted to enter an initial administrator email and password (this is a super-admin that can administer any exhibit in the installation). If you choose not to create one, the first user will be given administrative privileges.
Change directories to your new application:
$ cd app-name
Run the database migrations:
$ SKIP_TRANSLATION=1 rake db:migrate
Start Solr (possibly using solr_wrapper
in development or testing):
$ solr_wrapper
and the Rails development server:
$ rails server
Go to http://localhost:3000 in your browser.
Configuration
Default ActionMailer configuration
Spotlight introduces functionality that depends on being able to send emails to exhibit curators and contacts. Be sure to configure your application's environments appropriately (see the Rails Guide for Action Mailer Configuration).
See the Spotlight wiki for more detailed information on configuring Spotlight.
Developing Spotlight
Spotlight:
- is a Rails engine and needs to be used in the context of a Rails application. We use engine_cart to create an internal test application at .internal_test_app/
- uses Solr as part of its integration tests. We use solr_wrapper to manage the Solr instance used for development and test.
Our $ rake ci
and $ rake spotlight:server
tasks utilize Solr and the testing rails app automatically.
See more detailed instructions for development environment setup at "Contributing to Spotlight"
With Docker
# because of how docker compose handles named images, running `docker compose up --build` will error when the Rails images have not been built locally
docker compose build
docker compose up
Tests
Run all the tests:
$ rake
This utilizes Solr and the testing rails app automatically.
Translations
Spotlight ships with i18n-tasks
to help manage translations. To run a translation health check:
$ bundle exec i18n-tasks health
See developer-facing instructions for enabling translation on the wiki.
Community
- Join us on the code4lib Slack
- #spotlight-development - a developer-focused channel for Spotlight
- #blacklight - a developer-focused channel for discussing implementation, customization, and other software concerns in the larger Blacklight community
- #spotlight-service - a service-focused channel for people who support exhibit-builders at institutions already using Spotlight
- Google Groups
- Blacklight Development Google group
- Spotlight Community Group (equivalent to #spotlight-service)
Updating the JavaScript bundle
The JavaScript is built by npm from sources in app/javascript
into a bundle
in app/assets/javascripts/spotlight/spotlight.js
. This file should not be edited
by hand as any changes would be overwritten. When any of the JavaScript
components in the gem are changed, this bundle should be rebuilt with the
following steps:
- Install npm
- Run
npm install
to download dependencies - Run
npm run prepare
to build the bundle - If you are releasing a new version of the gem, follow the release instructions below.
Releasing a new version and publishing the JavaScript
You only need to update package.json
and prepare/publish the JavaScript package for npm if there are changes to the JavaScript.
- Edit
version.rb
andpackage.json
to set the new version - Run
npm run prepare
to build the JavaScript bundle - Run
npm i --package-lock-only
to update the version inpackage-lock.json
- Commit the changes e.g.
git commit -am "Bump version to X.X.X"
- Push the release to rubygems and GitHub:
bundle exec rake release
- Run
npm publish
to push the JavaScript package to https://npmjs.org/package/spotlight-frontend
See "Updating the JavaScript bundle" above for more details.