hweng/hyrax

Hyrax is a front-end based on the robust Hydra framework, providing a user interface for common repository features

Code:

Docs:

Jump in:

Table of Contents

• What is Hyrax?
  • Feature list
• Help
• Getting started
  • Prerequisites
    • Characterization
    • Derivatives
  • Environments
  • Ruby
  • Redis
  • Rails
    • JavaScript runtime
• Creating a Hyrax-based app
  • Generate a work type
  • Start servers
  • Start background workers
  • Create default administrative set
• Managing a Hyrax-based app
  • Toggling features
• License
• Contributing
• Development
• Release process
• Acknowledgments

What is Hyrax?

Hyrax is a front-end based on the robust Hydra framework, providing a user interface for common repository features. Hyrax offers the ability to create repository object types on demand, to deposit content via multiple configurable workflows, and to describe content with flexible metadata. Numerous optional features may be turned on in the administrative dashboard or added through plugins. It is implemented as a Rails engine, so it may be the base of, or added to, a Rails application. Hyrax is the consolidation of Sufia and the CurationConcerns gems and behaves in much the same way.

Feature list

Hyrax has many features. Read more about what they are and how to turn them on. See the Sufia Management Guide to learn more.

For non-technical documentation about Hyrax, see the Hyrax documentation site.

Help

If you have questions or need help, please email the Hydra community tech list or stop by the #dev channel in the Hydra community Slack team.

Getting started

This document contains instructions specific to setting up an app with Hyrax v1.0.0.alpha. 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 are required for both Creating a Hyrax-based app and Contributing new features to Hyrax. After installing the Prerequisites:

• If you would like to create a new application using Hyrax follow the instructions for Creating a Hyrax-based app.
• If you would like to create new features for Hyrax follow the instructions for Contributing and Development.

Prerequisites

Hyrax requires the following software to work:

1. Solr version >= 5.x (tested up to 6.4.1)
2. Fedora Commons digital repository version >= 4.5.1 (tested up to 4.7.1)
3. A SQL RDBMS (MySQL, PostgreSQL), though note that SQLite will be used by default if you're looking to get up and running quickly
4. Redis, a key-value store
5. ImageMagick with JPEG-2000 support
6. FITS version 0.8.x (0.8.5 is known to be good)
7. LibreOffice

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

Characterization

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 a mac.

NOTE: Derivatives are served from the filesystem in Hyrax.

Environments

Note here that 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.

We recommend either Ruby 2.3 or the latest 2.2 version.

Redis

Redis is a key-value store that Hyrax uses to provide activity streams on repository objects and users, and to prevent race conditions as a global mutex when modifying order-persisting objects.

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

We recommend the latest Rails 5.0 release.

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

JavaScript runtime

Rails requires that you have a JavaScript runtime -- for example, nodejs -- installed. Either install nodejs or uncomment the rubyracer line in your Gemfile and run bundle install before running Hyrax's install generator.

Creating a Hyrax-based app

Generate a new Rails application using the template.

rails new my_app -m https://raw.githubusercontent.com/projecthydra-labs/hyrax/master/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
• Loading all of Hyrax's database migrations into your application's database
• Loading Hyrax's default workflows into your application's database

Generate a work type

Hyrax allows you to specify your work types by using a generator. 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 Work

or

rails generate hyrax:work MovingImage

Namespaces can be included in the work My::MovingImage by adding the path.

rails generate hyrax:work My/MovingImage

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

Start servers

To test-drive your new Hyrax application in development mode, spin up the servers that Hyrax needs (Solr, Fedora, and Rails):

rake hydra:server

And now you should be able to browse to localhost:3000 and see the application. Note that this web server is purely for development purposes; you will want to use a more fully featured web server for production-like environments.

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 testing and 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 adding the following to your config/application.rb

class Application < Rails::Application
  # ...
  config.active_job.queue_adapter = :inline
  # ...
end

For production applications you will want to use a more robust message queue system such as Sidekiq or Resque. The Sufia Development Guide has a detailed walkthrough of [installing and configuring Resque](https://github.com/projecthydra/sufia/wiki/Background-Workers-(Resque-in-Sufia-7). Initial Sidekiq instructions for ActiveJob are available on the Sidekiq wiki.

Load workflows

Load workflows from the json files in config/workflows by running the following rake task:

rake hyrax:workflow:load

Create default administrative set

After Fedora and Solr are running, create the default administrative set -- into which all works will be deposited unless assigned to other administrative sets -- by running the following rake task:

rake hyrax:default_admin_set:create

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

Managing a Hyrax-based app

The Sufia 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

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.

License

Hyrax is available under the Apache 2.0 license.

Contributing

We'd love to accept your contributions. Please see our guide to contributing to Hyrax.

If you'd like to help the development effort and you're not sure where to get started, you can always grab a ticket in the "Ready" column from our Waffle board. There are other ways to help, too.

• Contribute a user story.
• Help us improve Hyrax's test coverage or documentation coverage.
• Refactor away code smells.

Development

The Sufia Development Guide is for people who want to modify Hyrax itself, not an application that uses Hyrax.

Release process

See the release management process.

Acknowledgments

This software has been developed by and is brought to you by the Hydra community. Learn more at the Project Hydra website.