This application is the front end for the Penn Libraries catalog. It uses
Blacklight to facilitate searching and display of records from a Solr
index. Records are harvested from our ILS (Alma) by the
catalog-indexing app, and parsing of MARC is handled
by the pennmarc gem
(docs).
High-level information about this repo and the available working environments can be found at the top-level README.
Your development machine will need the following:
I suggest installing Ruby via rbenv or asdf. There is
plenty of guidance available on the open web about installing and using these tools. The .ruby-version and
.tool-versions files in this repo explicitly define the version of Ruby to be installed.
Important Note: The available Vagrant environment relies on a Bundler configuration that houses the installed gems in the
vendor/bundledirectory. If you want to use local services, and a local Ruby interpreter (viarbenv,asdfor somesuch), you'll need to instruct bundler to ignore this configuration when running commands withbundle(includingbundle exec).To ignore the vagrant-specific Bundler config in a terminal session, run
export BUNDLE_IGNORE_CONFIG=true. Alternatively, you cna prepend the environment variable with each command; e.g.BUNDLE_IGNORE_CONFIG=true bundle exec rails c.
Docker compose is required to run the application services. For 🌈 linux users 🌈 this is free and straightforward. Install docker engine and then add the compose plugin.
For Mac users, the easiest and recommended way to get Docker Compose is to install Docker Desktop. While this is enough to get the application running, you should request membership to the Penn Libraries Docker Team license from the IT Helpdesk for full functionality.
Building the Vagrant environment should pull in the needed development key. If using the Vagrant environment for development, all secret values will be pulled from Vault.
Settings files are, and should continue to be, structured to support credentials being made available by different means. For example, the Alma API keys is available via DockerSecrets in the Vagrant environment, but via the encrypted credential file when not using the Vagrant environment.
New credential values added to the Settings should be added BOTH to the Penn Vault as well as the encrypted Rails development.yml.enc file. This can be done with:
EDITOR=nano bundle exec rails credentials:edit -e developmentHelpful Rake tasks have been created to wrap up the initialization process for the development environment. Prior to
starting this app, ensure you have a copy of the Solr configset and some sample data from another developer or by
running the appropriate commands in the catalog-indexing project and copying those files into the solr directory.
For more information, see Loading Data.
# start the app docker services, provision Solr collections and databases if not present, and run database migrations
rake tools:start
# stop docker services
rake tools:stop
# remove docker containers
rake tools:clean
The rake tools:start command should ensure that the latest Solr config and sample data set ae loaded. Prior to running
this task, ensure you have a copy of the Solr configset as a zip file as well as a sample records jsonl file in the
solr directory. If the Solr container doesn't already have collections created, the tools:start command will attempt
to create new collections using the newest configset_*.zip file in the solr directory, then load the records in the
newest solrjson_*.jsonl file in the solr directory.
bundle installFor MacOS users the pg gem may fail to install with an error concerning the libpq library.
Refer to this gist to address this issue.
bundle exec rails serverView the app at localhost:3000
In order for Rubymine to properly identify your Rails executable, you should open the project in the rails_app directory. Additionally, you will have to edit your run configuration to include the following environment variable: BUNDLE_IGNORE_CONFIG=true. Details about this can be found in the top-level README.
Assuming you have configured your Ruby SDK (to use rbenv or asdf) in RubyMine, you should be able to run the Rails server from the IDE. If you'd like to run the server in debugging mode, Rubymine will prompt you to install the necessary debugging gems if you have not already done so.
In order to mitigate the potential for issues when updating Blacklight versions, all overridden Blacklight classes and templates should include documentation about the version from which the copied class or overriden template started from. This should help to ensure that our overrides continue to function as expected as we update Blacklight.
When updating Blacklight, it is recommended to review each override and adapt to any changes in the latest version of the source file of the override, if needed. If no changes are needed, update the referenced version number in the override file documentation to reflect that it was reviewed for compatibility with the version of Blacklight being updated to.
It can be helpful to use GitHub's comparison tool with the original and target versions specified, so that all changed files are easily reviewable.
In order to contribute productively while fostering the project values, familiarize yourself with the established Gitlab Collaboration Workflow as well as the Ruby on Rails Development Guidelines.
When adding new features, be sure to consider the need for test coverage.
Run the full application test suite with:
bundle exec rspecThis application uses Rubocop to enforce Ruby and Rails style guidelines. We centralize our UPenn specific configuration in upennlib-rubocop.
If there are rubocop offenses that you are not able to fix please do not edit the rubocop configuration instead regenerate the rubocop_todo.yml using the following command:
rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit 10000To change our default Rubocop config please open an MR in the upennlib-rubocop project.