Find - Frontend

See the README for the Rails app for more information about the application.

We are working to support development in a Vagrant environment as well as a development environment using local Ruby and docker services. Choose your poison.

1. Relation to other Projects
2. Developing
   1. Working with the Vagrant environment
      1. Vagrant Services
      2. Starting
      3. Stopping
      4. Destroying
      5. SSH
      6. Interacting with the Rails Application
      7. Loading Sample Data
   2. Working with local services in Docker
      1. Initializing
3. Working with a remote Solr index

Relation to other Projects

In deployed environments, Find is configured to point at a Solr index that is built and maintained by the catalog-indexing app.

Developing

Working with the Vagrant environment

Caveat: The vagrant development environment has only been tested in the local environments our developers currently have. This currently includes Linux, Intel-based Macs and M1 Macs.

In order to use the integrated development environment you will need to install Vagrant [do not use the Vagrant version that may be available for your distro repository - explicitly follow instructions at the Vagrant homepage] and the appropriate virtualization software. If you are running Linux or Mac x86 then install VirtualBox, if you are using a Mac with ARM processors then install Parallels.

You may need to update the VirtualBox configuration for the creation of a host-only network. This can be done by creating a file /etc/vbox/networks.conf containing:

* 10.0.0.0/8

Vagrant Services

1. The Find Rails app
2. Solr
3. Postgres
4. Chrome (for running system tests)

Starting

From the vagrant directory run:

if running with Virtualbox:

vagrant up --provision

if running with Parallels:

vagrant up --provider=parallels --provision

This will run the vagrant/Vagrantfile which will bring up an Ubuntu VM and run the Ansible script which will provision a single node Docker Swarm behind nginx with a self-signed certificate to mimic a load balancer. Your hosts file will be modified; the domain catalog-find-dev.library.upenn.edu will be added and mapped to the Ubuntu VM. Once the Ansible script has completed and the Docker Swarm is deployed you can access the application by navigating to https://catalog-find-dev.library.upenn.edu/.

Stopping

To stop the development environment, from the vagrant directory run:

vagrant halt

Destroying

To destroy the development environment, from the vagrant directory run:

vagrant destroy -f

SSH

You may ssh into the Vagrant VM by running:

vagrant ssh

Interacting with the Rails Application

Once your vagrant environment is set up you can ssh into the vagrant box to interact with the application:

1. Enter the Vagrant VM by running vagrant ssh in the /vagrant directory
2. Start a shell in the find container:

  docker exec -it catalog-find_catalog_find.1.{whatever} sh

Loading Sample Data

To index some same records into the Solr instance:

1. Start a shell in the find app, see interacting-with-the-rails-application
2. Run rake tasks:

bundle exec rake tools:index_sample_file

Working with local services in Docker

Important Note: The available Vagrant environment relies on a Bundler configuration that houses the installed gems in the vendor/bundle directory. If you want to use local services, and a local Ruby interpreter (via rbenv, asdf or somesuch), you'll need to instruct bundler to ignore this configuration when running commands with bundle (including bundle exec).

To ignore the vagrant-specific Bundler config in a terminal session, run export BUNDLE_IGNORE_CONFIG=true. Alternatively, you can prepend the environment variable with each command; e.g. BUNDLE_IGNORE_CONFIG=true bundle exec rails c.

Initializing

Guidance for working in this environment - with the above provision - can be found in the Rails App README file.

Working with a remote Solr index

1. Using Wireguard VPN...
2. Get a deployed Solr collection URL complete with included basic auth credentials. Somethings like: http://staging-admin:staging-solr-pw@catalog-manager-stg01.library.upenn.int/solr1/catalog-staging.
3. Add a local settings file at rails_app/config/settings.local.yml that defines a solr_url setting with the deployed Solr URL.
4. In the Vagrant environment, restart the Rails server by running touch tmp/restart.txt command in the running catalog-find_catalog_find container.
5. DO NOT run any SolrTools methods that are going to modify the deployed Solr collection!

Design System

In the Settings file, the pennlibs_web_version value controls the version of the Penn Libraries design system assets (Javascript and Stylesheet) that will be loaded in the application layout. Currently this configuration allows for minor and patch releases to be effective automatically, but it can be modified to pin a specific release.