text: Table of Contents
  - What is Hyrax?
  - Getting started
  - Creating a Hyrax-based app
  - Managing a Hyrax-based app
  - License
  - Contributing
  - Development
  - Release process
  - Acknowledgments
  What is Hyrax?
  Hyrax is a front-end based on the robust Samvera.
  Feature list
  Hyrax has many features. Read more about what they are and how to turn them on. See the Hyrax Management Guide to learn more.
  For non-technical documentation about Hyrax, see the Hyrax documentation site.
  The Samvera community is here to help. Please see our support guide.
  Getting started
  This document contains instructions specific to setting up an app with Hyrax v2.5.0. 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...
  - 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 7.0.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:)
  - LibreOffice
  - ffmpeg
  NOTE: The Hyrax Development Guide has instructions for installing Solr and Fedora in a development environment.
  Characterization
  FITS can be installed on OSX using Homebrew by running the command:
  brew install fits
  OR
  - Hyrax app access to FITS by:
  - Adding the full fits.sh path to your PATH (e.g., in your .bash_profile), OR
  - Changing
  config/initializers/hyrax "/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 here that the following commands assume you're setting up Hyrax.
  Hyrax supports Ruby 2.3 and up. When starting a new project, we recommend using the latest Ruby 2.7 version.
  Redis
  Redis is a key-value store that Hyrax
  Hyrax 2.x supports Rails 5.1 and 5.2. We recommend the latest Rails 5.2 release.
  # If you don't already have Rails at your disposal... gem install rails -v '5.2.4.3'
  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
  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.4.3_ new my_app -m
  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
  - Create default collection types (e.g. Admin Set, User Collection)
  Start servers
  To test-drive your new Hyrax application in development mode, spin up the servers that Hyrax needs (Solr, Fedora, and Rails):
  bin/rails hydra:server
  And now you should be able to browse to localhost:3000 and see the application.
  Notes:
  - 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
  rails s.
  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 adding the following to your
  config/environments/development.rb
  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
  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 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:
  bin/rails hyrax:default_admin_set:create
  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
  or
  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
  My namespace:
  rails generate hyrax:work My/MovingImage
  You may wish to customize your work type now that it's been generated.
  Enable notifications
  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
  Gemfile:
  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
  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.
  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,.
  Development
  The Hyrax Development Guide is for people who want to modify Hyrax itself, not an application that uses Hyrax. See especially the Quick Start guide and instructions for running the Hyrax test suite.
  Reporting Security Issues
  To report a security vulnerability, email [email protected].
  Workflow Relationship Diagram
  Release process
  See the release management process.
  Acknowledgments
  This software has been developed by and is brought to you by the Samvera community. Learn more at the Samvera website.
  