{"id":13558200,"url":"https://github.com/projectblacklight/spotlight","last_synced_at":"2025-10-08T18:07:08.765Z","repository":{"id":11963853,"uuid":"14536054","full_name":"projectblacklight/spotlight","owner":"projectblacklight","description":"Spotlight enables librarians, curators, and others who are responsible for digital collections to create  attractive, feature-rich websites that highlight these collections.","archived":false,"fork":false,"pushed_at":"2025-09-30T15:37:05.000Z","size":12834,"stargazers_count":165,"open_issues_count":261,"forks_count":65,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-10-08T09:28:19.442Z","etag":null,"topics":["discovery-interface","exhibit","rails","rails-application","rails-engine","ruby","solr"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/projectblacklight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2013-11-19T19:49:19.000Z","updated_at":"2025-10-07T09:18:47.000Z","dependencies_parsed_at":"2023-01-13T21:00:45.352Z","dependency_job_id":"d7c779aa-4825-4148-a97f-7ec3ac3d2348","html_url":"https://github.com/projectblacklight/spotlight","commit_stats":{"total_commits":2692,"total_committers":46,"mean_commits":58.52173913043478,"dds":"0.46916790490341753","last_synced_commit":"40f023b3423e903a6108f0da2aa24a3dcfc59072"},"previous_names":[],"tags_count":193,"template":false,"template_full_name":null,"purl":"pkg:github/projectblacklight/spotlight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fspotlight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fspotlight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fspotlight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fspotlight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projectblacklight","download_url":"https://codeload.github.com/projectblacklight/spotlight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fspotlight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278976671,"owners_count":26078876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discovery-interface","exhibit","rails","rails-application","rails-engine","ruby","solr"],"created_at":"2024-08-01T12:04:48.401Z","updated_at":"2025-10-08T18:07:08.760Z","avatar_url":"https://github.com/projectblacklight.png","language":"Ruby","readme":"spotlight\n=========\n\n![CI](https://github.com/projectblacklight/spotlight/workflows/CI/badge.svg) | [![Gem Version](https://badge.fury.io/rb/blacklight-spotlight.png)](http://badge.fury.io/rb/blacklight-spotlight) | [Release Notes](https://github.com/projectblacklight/spotlight/releases) | [Design Documents](https://github.com/projectblacklight/spotlight/releases/tag/v0.0.0)\n\nSpotlight 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](https://github.com/projectblacklight/blacklight), an open source, Ruby on Rails Engine that provides a basic discovery interface for searching an Apache Solr index.\n\nIn addition to the information found below, you can read more about what Spotlight is, our motivations for creating it, and how to configure it in the [wiki pages](https://github.com/projectblacklight/spotlight/wiki). You might also want to take a look at our demo videos, especially the [tour of a completed Spotlight exhibit](https://www.youtube.com/watch?v=_A7vTbbiF4g) and the walkthrough of [building an exhibit with Spotlight](https://www.youtube.com/watch?v=qPJtgajJ4ic).\n\nIf you have questions or are interested in contributing, please reach out to the [Spotlight Community](#spotlight-community)\n\n## Requirements\n\n1. [Ruby](https://www.ruby-lang.org/) 3.2+\n2. [Ruby on Rails](https://rubyonrails.org/) 7.1+\n3. Java (11 or greater) *for Solr*\n4. ImageMagick (http://www.imagemagick.org/script/index.php) due to [carrierwave](https://github.com/carrierwaveuploader/carrierwave#adding-versions)\n\n## Installation\n\nThe following installation instructions are for setting up a new instance of Spotlight. To set up an environment for Spotlight development, see [Developing Spotlight](#developing-spotlight).\n\nTo bootstrap a new Rails application using [importmap-rails](https://github.com/rails/importmap-rails):\n\n```\n$ SKIP_TRANSLATION=1 rails new app-name -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb -a propshaft --css bootstrap\n```\n\nor using [jsbundling-rails](https://github.com/rails/jsbundling-rails) with [esbuild](https://esbuild.github.io/):\n\n```\n$ SKIP_TRANSLATION=1 rails new app-name -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb -a propshaft -j esbuild --css bootstrap\n```\n\nor from an existing Rails application:\n\n```\n$ SKIP_TRANSLATION=1 rails app:template LOCATION=https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb\n```\n\n*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.\n\nChange directories to your new application:\n\n```\n$ cd app-name\n```\n\nRun the database migrations:\n\n```\n$ SKIP_TRANSLATION=1 rake db:migrate\n```\n\nStart Solr (possibly using `solr_wrapper` in development or testing):\n\n```\n$ solr_wrapper\n```\n\nand the Rails development server:\n\n```\n$ bin/dev\n```\n\nGo to http://localhost:3000 in your browser.\n\n## Configuration\n\n### Default ActionMailer configuration\n\nSpotlight 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](https://guides.rubyonrails.org/v7.2/action_mailer_basics.html#action-mailer-configuration)).\n\nSee the [Spotlight wiki](https://github.com/projectblacklight/spotlight/wiki) for more detailed information on configuring Spotlight.\n\n## Translations\n\nSpotlight ships with [`i18n-tasks`](https://github.com/glebm/i18n-tasks) to help manage translations. To run a translation health check:\n\n```sh\nbundle exec i18n-tasks health\n```\n\nSee [developer-facing instructions for enabling translation](https://github.com/projectblacklight/spotlight/wiki/Translations) on the wiki.\n\n## Updating the JavaScript bundle\n\nThe JavaScript is built by npm from sources in `app/javascript` into a bundle\nin `app/assets/javascripts/spotlight/spotlight.js`. This file should not be edited\nby hand as any changes would be overwritten.  When any of the JavaScript\ncomponents in the gem are changed, this bundle should be rebuilt with the\nfollowing steps:\n1. [Install npm](https://www.npmjs.com/get-npm)\n2. Run `npm install` to download dependencies\n3. Run `npm run prepare` to build the bundle\n4. If you are releasing a new version of the gem, follow the release instructions below.\n\n## Releasing a new version and publishing the JavaScript\n\nYou only need to update `package.json` and prepare/publish the JavaScript package for npm if there are changes to the JavaScript.\n1. Edit `version.rb` and `package.json` to set the new version\n2. Run `npm run prepare` to build the JavaScript bundle\n3. Run `npm i --package-lock-only` to update the version in `package-lock.json`\n4. Commit the changes e.g. `git commit -am \"Bump version to X.X.X\"`\n5. Push the release to rubygems and GitHub: `bundle exec rake release`\n6. Run `npm publish` to push the JavaScript package to https://npmjs.org/package/spotlight-frontend\n\nSee [Updating the JavaScript bundle](#updating-the-javascript-bundle) above for more details.\n\n## Developing Spotlight\n\n### Branches\n\n* The `main` branch is for development of the upcoming 5.0 release.\n* The `4.x` series is on the [release-4.x](https://github.com/projectblacklight/spotlight/tree/release-4.x) branch for backports of features and bug fixes.\n\n### Tooling\n\n* Spotlight is a Rails engine and needs to be used in the context of a Rails application. We use [engine_cart](https://github.com/cbeer/engine_cart) to create an internal test application at `.internal_test_app/`. \n* Spotlight relies on Solr for its integration tests and to run a development instance. [solr_wrapper](https://github.com/cbeer/solr_wrapper) allows us to provide terse commands for development and testing. For more granular control, you can run Solr in Docker, then execute services and processes individually.\n* Spotlight's `rake spotlight:server` and `rake ci` tasks use engine_cart and Solr automatically, but you can refer to [engine_cart](https://github.com/cbeer/engine_cart) and [solr_wrapper](https://github.com/cbeer/solr_wrapper) documentation to work with these tools outside of those rake tasks.\n\n### Initial setup\n\n1. Install the [requirements above](#requirements). Note: You do not need to install Java if you plan to run Solr in Docker. \n2. Clone the spotlight repository locally and `cd` into it.\n3. Install the Ruby gems used by spotlight: `bundle install`.\n\nNote: if your system is confused by conflicting gem versions, you may need to add \"bundle exec\" to the beginning of each command below, e.g. `bundle exec rake engine_cart:generate`. This ensures that the command is run in the context of bundler's gem version management.\n\n### Run a development server\n\nAfter following one of the instructions below, visit http://localhost:3000. A Solr instance will be running on port 8983. When using importmap (the default configuration), JavaScript changes in development should not require [bundling](#updating-the-javascript-bundle) or a server restart.\n\n#### With solr_wrapper\n\nThe following rake task will build a Spotlight-based application, start Solr with solr_wrapper, and run the built-in rails server. In the process, you will be prompted to create an admin user and password.\n\n```sh\nrake spotlight:server\n```\n\nAlternatively, you can use [individual commands](#individual-commands) to start Solr separately and set everything else up.\n\n```sh\nsolr_wrapper # Run in separate tab\nrake engine_cart:generate\nrake spotlight:fixtures\ncd .internal_test_app\nbin/rails spotlight:initialize\nbin/dev\n```\n\n#### With Docker\n\nThe following will run Solr in Docker and then use individual commands to set up a running development server.\n\n```sh\ndocker compose up -d\nrake engine_cart:generate\nrake spotlight:fixtures\ncd .internal_test_app\nrake spotlight:seed_admin_user\nbin/dev\n```\n\n### Run tests\n\n#### With solr_wrapper\n\nThe following rake task will build a Spotlight-based application, start Solr, run the tests, and then shut down Solr when the tests are finished. Solr should not be running already when you run this.\n```sh\nrake\n```\n\n#### With Docker (or solr_wrapper, if Solr is started separately)\n\nIf you're using Solr on Docker, run `docker compose up -d` to start Solr if you haven't already. Once you have Solr running (either on Docker or with solr_wrapper), run the tests using the following commands:\n```sh\nrake engine_cart:generate\nrake spotlight:fixtures\ncd .internal_test_app \u0026\u0026 rake spec:prepare \u0026\u0026 cd - # not needed if you ran the dev server\nrspec\n```\n\nUsing rspec directly allows you to run individual test files / lines.\n\nThe `spec:prepare` task generates css assets for use by the tests. You can delete these assets with `rake assets:clobber`.\n\nOnce you are set up, you can also run `rubocop` to enforce consistent coding style.\n\n\n### Individual commands\n\n#### Using solr_wrapper\n\nStart Solr with solr_wrapper: \n```\nsolr_wrapper\n```\nReset Solr using solr_wrapper to a pristine state (e.g. remove Solr docs, core, etc.):\n```\nsolr_wrapper clean\n```\nNote: Sometimes solr doesn't shut down properly.  You can check by seeing if solr is running:\n```\nps -eaf | grep solr\n```\n\n#### Using test fixtures\n\nAdd fixture data to Solr:\n```\nrake spotlight:fixtures\n```\nDelete an existing solr index:\n```\nrails c\n\u003e Blacklight.default_index.connection.delete_by_query \"*:*\"\n\u003e Blacklight.default_index.connection.commit\n```\n\n#### Generating and running the test app\n\nBuild the test app: \n```\nrake engine_cart:generate\n```\nFrom `./internal_test_app`, create the initial admin user:\n\n*With [default credientials](https://github.com/projectblacklight/spotlight/blob/9acd4bf5d4f2806b6e76aa03c31176ea5f6943de/lib/tasks/spotlight_tasks.rake#L20-L21)*\n```\nrake spotlight:seed_admin_user\n```\n*With user-provided credientials*\n```\nbin/rails spotlight:initialize\n```\nFrom `./internal_test_app`, start Rails to run the test app:\n```\nbin/dev\n```\nFrom the project root, delete the test app (if you want to regenerate from scratch):\n```\n$ rake engine_cart:clean\n```\n## Spotlight Community\n\nSee [Contributing to Spotlight](/CONTRIBUTING.md) for general information about participation in the Spotlight community.\n\n### Where to find us\n\n- Join us on the [code4lib Slack](https://code4lib.org/irc)\n  - **#spotlight-development** - a developer-focused channel for Spotlight\n  - **#blacklight** - a developer-focused channel for discussing implementation, customization, and other software concerns in the larger [Blacklight community](http://projectblacklight.org/)\n  - **#spotlight-service** - a service-focused channel for people who support exhibit-builders at institutions already using Spotlight\n- Google Groups\n  - [Blacklight Development Google group](https://groups.google.com/forum/#!forum/blacklight-development)\n  - [Spotlight Community Group](https://groups.google.com/forum/#!forum/spotlight-community) (equivalent to #spotlight-service)\n","funding_links":[],"categories":["Ruby","ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectblacklight%2Fspotlight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojectblacklight%2Fspotlight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectblacklight%2Fspotlight/lists"}