README

Blacklight Discovery

• Ruby version 2.7.4

• Rails version 5.1.7

• Blacklight 7.4.1

Local Development

Running locally

1. Clone the git repo: git clone git@github.com:emory-libraries/blacklight-catalog.git
2. cd ./blacklight-catalog
3. Install the required gems:
   1. gem install bundler:2.1.4
   2. bundle install
4. Since we're now using MySQL for the database, run rails db:create. If you run into errors here, it may be one of two things:
   1. Your local ENV variables may not be set correctly. If so, reach out to an already up and running developer for help.
   2. You may have MySQL already configured on your system and set to your own username and passwords. In this case, assign that information into the necessary ENV variables and try the create command above once more.
5. If you are still experiencing problems setting up the database, reach out to a software engineer for a screenshare meeting.
6. Migrate the database: rails db:migrate
7. Launch development instance of solr in the same folder but a separate terminal window/tab: bundle exec solr_wrapper
8. First time running this application locally? Give yourself some test objects by following the directions here
9. Start the application: rails server
10. You should now be able to go to http://localhost:3000/catalog and see the application
11. In order to be able to sign into the application locally, the environment variable DATABASE_AUTH=true must be set in your development environment. You must create a user via the rails console:

    bundle exec rails c
    u = User.new
    u.uid = "user"
    u.display_name = "User Name"
    u.email = "email@testdomain.com"
    u.password = "password"
    u.password_confirmation = "password"
    u.save

Running Rspec tests locally

1. A separate instance of Solr must be up and running before tests can be run. To do so, run the following command inside your cloned folder: solr_wrapper --config config/solr_wrapper_test.yml
2. In a new tab/window within the same folder, run bundle exec rspec. All tests should be passing

Creating Solr test objects

1. Save the output of the following to a Ruby file in spec/support/solr_documents

   bundle exec rails c
   solr = Blacklight.default_index.connection
   response = solr.get 'select', params: { q: 'id:YOUR_ID' }
   document = response["response"]["docs"].first
   document.deep_symbolize_keys!

2. Remove :score and :_version_ lines (will not re-save to solr if these are included)
3. Assign to a global variable and add .freeze to the end of the hash

Using Docker (Experimental)

1. Install Docker using these instructions
2. Clone the git repository
3. cd into the blacklight-catalog repository
4. Copy docker-compose-sample.yml into docker-compose.yml and set credentials
5. Set env variables from dotenv-sample in a new file .env.development. Reach out to a colleague for guidance setting this file since some credentials require additional approvals. Ensure credentials in .env.development match credentials in docker-compose.yml.
6. Run docker compose up
7. Access the application through http://localhost:3000

Troubleshooting

• Error RSolr::Error::Http - 404 Not Found occurs while running tests.
  • Solution: The test Solr instance isn't running. You'll know that that Solr is up once you see this complete line: Starting Solr 7.7.1 on port 8985 ... http://127.0.0.1:8985/solr/

Run jmeter page load times test

1. Install and run Apache Jmeter in GUI mode.
2. Open jmeter/blacklight_catalog.jmx from the file menu.
3. Hit the green forward arrow to start the tests running.
4. View the immediate results in "View Results Tree" (green with a checkmark for successes, red with an x for failures).
5. If the test suite is ran more than once, results will build in "Aggregate Graph".

Profiling and Flamegraphs

In development mode, this app uses gems rack-mini-profiler and stackprof for profiling and generating flamegraphs. To generate a flamegraph, add ?pp=flamegraph to any page you visit locally, e.g. http://localhost:3000/?pp=flamegraph will generate a flamegraph for the home page.