Developer Resources - Hyrax-Valkyrization Community Effort - September 6th - 16th, 2022

Hyrax-Valkyrization MVP

The goal was to have a functional MVP (minimal viable product) prior to this Community Effort. The MVP for Hyrax using a postgres Valkyrie adapter is defined as: CRUD (i.e. create, read, update, delete) operations for the major components (i.e. admin sets, collections, works, file sets, files) can be successfully accomplished through the UI. This includes additional functionality that is required to load the forms that support these operations.

The status of the MVP organized by major component is described in Issues #5326. Any incomplete functionality for the MVP has the highest priority.

What to work on?

The Project Board lists issues related to the Valkyrization effort and includes columns:

Ready - issues that are ready to be worked on (no known blockers) and are not already assigned to a developer
In Progress - issues currently being worked on - when you move an issue to this column, assign it to yourself and any other developers working on it with you
Ready for Review - there is a PR that fixes the issue, tests are green (passing), and it is ready for review
DONE - completed issues

There are two additional columns that are used by organizers.

Back Log - issues with known blockers OR issues that are older and needing review
Archived - issues closed prior to this community effort

NOTE: You can also see issues related to this effort using the Valkyrization label on the GitHub Issues page for Hyrax

Testing Github Issues

Demo/testing site running the current version of Hyrax with a Valkyrie (Postgres) back end: https://nurax-pg.curationexperts.com/

Nurax-pg feature testing spreadsheet - Identifies feature tests and where things are breaking or stop working currently with Valkyrized Hyrax

Getting Valkyrized Hyrax up and running locally using Docker

First, make sure you have installed Docker and Docker Compose v2. Then clone the Hyrax repository.

Within your cloned repository (the hyrax directory) is a .koppie directory that contains a test and development application called Koppie. This is similar to Dassie, but with no Fedora server loaded, and any forwarded network ports are incremented from the Dassie value.

Starting Koppie from the hyrax directory using docker compose

Build docker images for Koppie: docker compose -f docker-compose-koppie.yml build
Start Koppie: docker compose -f docker-compose-koppie.yml up
Load localhost:3001 in a browser.

Koppie runs as a different project than Dassie, so it should be possible to run both concurrently (assuming your workstation has enough RAM).

Running Commands (for testing changes, for example)

Currently Koppie should not be used for running specs, Dassie should be used instead until the specs can be updated for a valkyrie only environment.

Run specs on Dassie

The following shows an example of running rspec on the catalog_controller:

docker compose up
docker compose exec app sh
cd /app/samvera/hyrax-engine/
bundle exec rspec ./spec/controllers/catalog_controller_spec.rb

You may have to run bundle install from inside the the hyrax-engine directory

Run rails console on Koppie

docker compose -f docker-compose-koppie.yml up
docker compose -f docker-compose-koppie.yml exec app bundle exec rails c

Troubleshooting

If the postgres service logs show permissions errors, there may be old data from alternate versions of the postgres image. The old data volumes can deleted by using docker compose -f docker-compose-koppie.yml down -v
Errors such as exec /app/samvera/hyrax-entrypoint.sh: no such file or directory in the app, sidekiq and db_migrate services may indicate an outdated cached hyrax-base image layer was used to build the koppie image. Try docker compose -f docker-compose-koppie.yml build --no-cache to rebuild all the image layers.
- It was also seen on a Windows 10 host and was resolved by using the git --core.autocrlf option when cloning the repo.

Reference Documentation

References for Hyrax Development:

Hyrax Development Guide - for development setup with solr_wrapper, fedora_wrapper, etc
FAQ for Dassie Docker Test App - for development setup using docker environment
Hyrax Valkyrie Usage Guide

References for Understanding Hyrax & Valkyrie Code: