Skip to content

Latest commit

 

History

History
285 lines (192 loc) · 13.7 KB

developing-your-hyrax-based-app.md

File metadata and controls

285 lines (192 loc) · 13.7 KB
Raw

Developing Your Hyrax-based Application

Table of Contents

Introduction

A Hyrax-based application includes lots of dependencies. We provide a Docker image for getting started with your Hyrax-based application.

NOTE: The Docker image describes the canonical dependencies. In a way, it is executable documentation. The following documentation is our best effort to transcribe that executable documentation into a narrative. In other words, this documentation may drift away from the Docker details.

You can also try Running Hyrax-based application in local VM which uses Ubuntu.

During development, running only the dependent services in a container environment may be beneficial. This avoids potential headaches concerning file permissions and eases the use of debugging tools. The application generation instructions below use Lando to achieve this setup.

This document contains instructions specific to setting up an app with Hyrax v5.0.1. If you are looking for instructions on installing a different version, be sure to select the appropriate branch or tag from the drop-down menu above.

Prerequisites

Prerequisites are required for both creating a Hyrax-based app and contributing new features to Hyrax. After installing the prerequisites...

Hyrax requires the following software to work:

  1. Solr version >= 5.x (tested up to 8.11.1, which includes the log4j library update)
  2. Fedora Commons digital repository version >= 4.7.6 (if not using the Valkyrie Postgres adapter)
  3. A SQL RDBMS (PostgreSQL recommended)
  4. Redis, a key-value store
  5. ImageMagick with JPEG-2000 support
  6. FITS (tested up to version 1.5.0 -- avoid version 1.1.0)
  7. LibreOffice
  8. ffmpeg

NOTE: The Hyrax Development Guide has instructions for installing Solr and Fedora in a development environment.

Characterization

Servlet FITS

FITS can be run as a web service. This has the benefit of improved performance by avoiding the slow startup time inherent to the local option below.

A container image is available for this purpose: ghcr.io/samvera/fitsservlet

Local FITS

FITS can be installed on OSX using Homebrew by running the command: brew install fits

OR

  1. Go to http://projects.iq.harvard.edu/fits/downloads and download a copy of FITS (see above to pick a known working version) & unpack it somewhere on your machine.
  2. Mark fits.sh as executable: chmod a+x fits.sh
  3. Run fits.sh -h from the command line and see a help message to ensure FITS is properly installed
  4. Give your Hyrax app access to FITS by:
    1. Adding the full fits.sh path to your PATH (e.g., in your .bash_profile), OR
    2. Changing config/initializers/hyrax.rb to point to your FITS location: config.fits_path = "/<your full path>/fits.sh"

Derivatives

Install LibreOffice. If which soffice returns a path, you're done. Otherwise, add the full path to soffice to your PATH (in your .bash_profile, for instance). On OSX, soffice is inside LibreOffice.app. Your path may look like "/path/to/LibreOffice.app/Contents/MacOS/"

You may also require ghostscript if it does not come with your compiled version LibreOffice. brew install ghostscript should resolve the dependency on an OSX-based machine with Homebrew installed.

NOTE: Derivatives are served from the filesystem in Hyrax.

Transcoding

Hyrax includes support for transcoding audio and video files with ffmpeg > 1.0 installed.

On OSX, you can use Homebrew to install ffmpeg:

brew install libvpx ffmpeg

Otherwise, to compile ffmpeg yourself, see the ffmpeg compilation guide.

Once ffmpeg has been installed, enable transcoding by setting config.enable_ffmpeg = true in config/initializers/hyrax.rb. You may also configure the location of ffmpeg using config.ffmpeg_path.

Environments

NOTE: The following commands assume you're setting up Hyrax in a development environment (using the Rails built-in development environment). If you're setting up a production or production-like environment, you may wish to tell Rails that by prepending RAILS_ENV=production to the commands that follow, e.g., rails, rake, bundle, and so on.

Ruby

First, you'll need a working Ruby installation. You can install this via your operating system's package manager -- you are likely to get farther with OSX, Linux, or UNIX than Windows but your mileage may vary -- but we recommend using a Ruby version manager such as RVM or rbenv.

Hyrax supports Ruby 3.2. When starting a new project, we recommend using the latest Ruby 3.2 version.

Redis

Redis is a key-value store that Hyrax uses to provide activity streams on repository objects and users, and helps when modifying order-persisting objects by managing multi-threaded actions on data (preventing race conditions as a global mutex).

Starting up Redis will depend on your operating system, and may in fact already be started on your system. You may want to consult the Redis documentation for help doing this.

Rails

Hyrax requires Rails 6. We recommend the latest Rails 6.1 release.

# If you don't already have Rails at your disposal...
gem install rails -v 6.1.7.7

JavaScript runtime

Rails requires that you have a JavaScript runtime installed (e.g. nodejs or rubyracer). Either install nodejs or uncomment the rubyracer line in your Gemfile and run bundle install before running Hyrax's install generator.

NOTE: nodejs is preinstalled on most Mac computers and doesn't require a gem. To test if nodejs is already installed, execute node -v in the terminal and the version of nodejs will be displayed if it is installed.

Creating a Hyrax-based app

Create a new Hyrax-based application by following these steps in order.

NOTE: Starting with Hyrax v5, the generated application will use Valkyrie for repository persistence. Use of ActiveFedora (instead of Valkyrie) is deprecated, but it should still be possible to reconfigure the generated application to use it.

Development Prerequisites

These instructions assume the use of Lando and Docker to manage the backend services needed by your Hyrax application. Follow the Lando installation instructions before proceeding, or have alternate providers for the services listed in the generated .lando.yml:

  • Solr
  • Postgres
  • Redis
  • FITS servlet
  • Fedora (if not using Postgres)

Generate the application

Generate a new Rails application using the template.

NOTE: HYRAX_SKIP_WINGS is needed here to avoid loading the Wings compatibility layer during the application generation process.

HYRAX_SKIP_WINGS=true rails _6.1.7.7_ new my_app --database=postgresql -m https://raw.githubusercontent.com/samvera/hyrax/hyrax-v5.0.1/template.rb

Generating a new Rails application using Hyrax's template above takes cares of a number of steps for you, including:

  • Adding Hyrax (and any of its dependencies) to your application Gemfile, to declare that Hyrax is a dependency of your application
  • Running bundle install, to install Hyrax and its dependencies
  • Running Hyrax's install generator, to add a number of files that Hyrax requires within your Rails app, including e.g. database migrations

Start Services

Start the background services managed by Lando. The

cd my_app
lando start

Run Migrations/Seeds

This performs the following actions:

  • Loading all of Hyrax's database migrations into your application's database
  • Create default collection types (e.g. Admin Set, User Collection)
  • Loading Hyrax's default workflows into your application's database
rails db:migrate
rails db:seed

NOTE: You will want to run these commands the first time this code is deployed to a new environment as well.

This creates the default administrative set -- into which all works will be deposited unless assigned to other administrative sets. This command also makes sure that Hyrax's built-in workflows are loaded for your application and available for the default administrative set.

Generate a work type

Using Hyrax requires generating at least one type of repository object, or "work type." Hyrax allows you to generate the work types required in your application by using a Rails generator-based tool. You may generate one or more of these work types.

Pass a (CamelCased) model name to Hyrax's work generator to get started, e.g.:

rails generate hyrax:work_resource MovingImage

If your applications requires your work type to be namespaced, namespaces can be included by adding a slash to the model name which creates a new class called MovingImage within the My namespace:

rails generate hyrax:work_resource My/MovingImage

You may wish to customize your work type now that it's been generated.

Start Hyrax web server

Test-drive your new Hyrax application in development mode:

rails s

And now you should be able to browse to localhost:3000 and see the application.

NOTE:

  • This web server is purely for development purposes. You will want to use a more fully featured web server for production-like environments.
  • For a fresh start, the data persisted in Lando can be wiped using lando destroy.

Start background workers

Many of the services performed by Hyrax are resource intensive, and therefore are well suited to running as background jobs that can be managed and executed by a message queuing system. Examples include:

  • File ingest
  • Derivative generation
  • Characterization
  • Fixity
  • Solr indexing

Hyrax implements these jobs using the Rails ActiveJob framework, allowing you to choose the message queue system of your choice.

For initial development, it is recommended that you change the default ActiveJob adapter from :async to :inline. This adapter will execute jobs immediately (in the foreground) as they are received. This can be accomplished by modifying the .env file:

HYRAX_ACTIVE_JOB_QUEUE=inline

For testing, it is recommended that you use the built-in :test adapter which stores enqueued and performed jobs, running only those configured to run during test setup. To do this, add the following to config/environments/test.rb:

Rails.application.configure do
  # ...
  config.active_job.queue_adapter = :test
  # ...
end

For production applications you will want to use a more robust message queue system such as Sidekiq. The Hyrax Development Guide has a detailed walkthrough of installing and configuring Sidekiq.

Create an Admin User

To access all of Hyrax's features you must be signed in as a user in the admin role. The default role management system uses the config/role_map.yml file to assign users to roles. For example:

development:
  admin:
    - [email protected]

Managing a Hyrax-based app

The Hyrax Management Guide provides tips for how to manage, customize, and enhance your Hyrax application, including guidance specific to:

  • Production implementations
  • Configuration of background workers
  • Integration with e.g., Dropbox, Google Analytics, and Zotero
  • Audiovisual transcoding with ffmpeg
  • Setting up administrative users
  • Metadata customization
  • Virus checking
  • Workflows

Toggling Features

Some features in Hyrax can be flipped on and off from either the Administrative Dashboard or via a YAML configuration file at config/features.yml. An example of the YAML file is below:

assign_admin_set:
  enabled: "false"
proxy_deposit:
  enabled: "false"

If both options exist, whichever option is set from the Administrative Dashboard will take precedence.