This is a deprecated document that might have some useful information.
Table of Contents
- What is Hyrax?
- Feature Documentation
- Getting started
- Creating a Hyrax-based app
- Managing a Hyrax-based app
What is Hyrax?
Hyrax is a front-end based on the robust Samvera 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.
- List of features: Feature Matrix
- Configuration and enabling features: Hyrax Management Guide
- Walk-through on using features: Hyrax Feature Guides
- For general information about Hyrax: Hyrax Site
The Samvera community is here to help. Please see our support guide.
This document contains instructions specific to setting up an app with Hyrax v3.4.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.
Note about Versions
Hyrax has far more tags than released versions. This section provides context and wayfinding on navigating that reality.
The history of Hyrax involves the merging of Sufia and Curation Concerns. Each of those projects had their own releases and tags. In preserving commit history of the work, we collectively brought along those past tags (for better or for worse).
This means that we have a mix of Hyrax releases and associated tags as well as tags for those other gems' releases. Which can be confusing.
When you include Hyrax in your Gemfile, and reference a version (eg.
gem "hyrax", "~> 2.7"), you are getting that version from Rubygems. When you reference a tag (eg.
gem "hyrax", github: "samvera/hyrax", ref: "v2.7.0") you are getting that information from Github. Both are reasonable and dependent on your situation. In the case of the former, you're likely wanting stable releases. In the case of the latter, you may be looking to use specific commits that include unreleased bug fixes.
The place to find the canonical Hyrax releases is at https://rubygems.org/gems/hyrax, there you can find a list of versions. Those versions map to tags in Hyrax (e.g. you can expect that the version in Rubygems and the tag in Hyrax have the same code). The release notes for those versions will be further described in Hyrax's releases. However, within the Hyrax releases, you'll also see other non-released Hyrax versions. These are likely the tags from the preceding gems (
NOTE: In our 2020-07-29 Samvera Tech call, some of the contributors discussed how to proceed with our current state. This section is our effort to provide wayfinding around the confusing tag proliferation in our repository.
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.
Hyrax requires the following software to work:
- Solr version >= 5.x (tested up to 8.7.0)
- Fedora Commons digital repository version >= 4.5.1 (tested up to 4.7.5)
- A SQL RDBMS (MySQL, PostgreSQL), though note that SQLite will be used by default if you're looking to get up and running quickly
- Redis, a key-value store
- ImageMagick with JPEG-2000 support
- FITS version 1.0.x (1.0.5 is known to be good, 1.1.0 is known to be bad: https://github.com/harvard-lts/fits/issues/140)
NOTE: The Hyrax Development Guide has instructions for installing Solr and Fedora in a development environment.
FITS can be installed on OSX using Homebrew by running the command:
brew install fits
- 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.
- Mark fits.sh as executable:
chmod a+x fits.sh
fits.sh -hfrom the command line and see a help message to ensure FITS is properly installed
- Give your Hyrax app access to FITS by:
- Adding the full fits.sh path to your PATH (e.g., in your .bash_profile), OR
config/initializers/hyrax.rbto point to your FITS location:
config.fits_path = "/<your full path>/fits.sh"
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.
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
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.,
bundle, and so on.
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 2.5, 2.6, and 2.7. When starting a new project, we recommend using the latest Ruby 2.7 version.
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.
Hyrax requires Rails 5. We recommend the latest Rails 5.2 release.
# If you don't already have Rails at your disposal... gem install rails -v 5.2.6
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
NOTE: The steps need to be done in order to create a new Hyrax based app.
Generate a new Rails application using the template.
rails _5.2.6_ new my_app -m https://raw.githubusercontent.com/samvera/hyrax/v3.0.2/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
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
- Create default collection types (e.g. Admin Set, User Collection)
To test-drive your new Hyrax application in development mode, spin up the servers that Hyrax needs (Solr, Fedora, and Rails):
And now you should be able to browse to localhost:3000 and see the application.
- This web server is purely for development purposes. You will want to use a more fully featured web server for production-like environments.
- You have the option to start each of these services individually. More information on solr_wrapper and fcrepo_wrapper will help you set this up. Start rails with
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
- 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
:inline. This adapter will execute jobs immediately (in the foreground) as they are received. This can be accomplished by adding the following to your
class Application < Rails::Application # ... config.active_job.queue_adapter = :inline # ... end
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
Rails.application.configure do # ... config.active_job.queue_adapter = :test # ... end
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 command:
This command also makes sure that Hyrax's built-in workflows are loaded for your application and available for the default administrative set.
NOTE: You will want to run this command the first time this code is deployed to a new environment as well.
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 Work
rails generate hyrax:work MovingImage
If your applications requires your work type to be namespaced, namespaces can be included in the by adding a slash to the model name which creates a new class called
MovingImage within the
rails generate hyrax:work My/MovingImage
You may wish to customize your work type now that it's been generated.
Hyrax 2 uses a WebSocket-based user notifications system, which requires Redis. To enable user notifications, make sure that you have configured ActionCable to use Redis as the adapter in your application's
config/cable.yml. E.g., for the
development Rails environment:
development: adapter: redis url: redis://localhost:6379
Using Rails up to version 5.1.4, ActionCable will not work with the 4.x series of the
redis gem, so you will also need to pin your application to a 3.x release by adding this to your
gem 'redis', '~> 3.0'
And then run
bundle update redis.
Note that the Hyrax Management Guide contains additional information on how to configure ActionCable in production environments.
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
- Setting up administrative users
- Metadata customization
- Virus checking
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.
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.
- The Hyrax user interface is translated into a number of languages, and many of these translations come from Google Translate. If you are a native or fluent speaker of a non-English language, your help improving these translations are most welcome. (Hyrax currently supports English, Spanish, Chinese, Italian, German, French, and Portuguese.)
- Do you see English in the application where you would expect to see one of the languages above? If so, file an issue and suggest a translation, please.
- Contribute a user story.
- Help us improve Hyrax's test coverage or documentation coverage.
- Refactor away code smells.
Reporting Security Issues
To report a security vulnerability, email [email protected] and the Steering Group will coordinate the community response. In your message, please document to the best of your ability cases (relevant software versions, conditions, etc.) where the vulnerability is applicable, the potential negative effects, and any known workarounds or fixes to mitigate the risk. Steering will communicate this to the Partners and the rest of the community in a timely fashion.
Workflow Relationship Diagram
This software has been developed by and is brought to you by the Samvera community. Learn more at the Samvera website.