h1. Hydra-Head

Hydra-Head is a Rails Engines plugin containing the core code for a Hydra application.  The full hydra stack includes the following:

- "Blacklight":http://projectblacklight.org/  (a rails engines plugin) for the User Interface
- "Solr":http://lucene.apache.org/solr/ (a java application, also ported to other languages) for the Search Engine 
- "ActiveFedora":https://github.com/mediashelf/active_fedora (a ruby gem) to let the rails application talk to fedora 
- "OM (Opinionated Metadata)":https://github.com/mediashelf/om (a ruby gem) to streamline the metadata configuration
- "Solrizer":https://github.com/projecthydra/solrizer (a ruby gem) to write content to the Solr index
- "SolrizerFedora":https://github.com/projecthydra/solrizer-fedora (a ruby gem) to write Fedora content to the Solr index.
- Hydra-Head (a rails engines plugin) to glue it all together 

For a more thorough overview of the Hydra framework, see "HYDRA_OVERVIEW.textile":https://github.com/projecthydra/hydrangea/blob/master/HYDRA_OVERVIEW.textile.  If you're looking to develop an application based on Hydra-Head, you might also be interested in "install prerequisites":https://github.com/projecthydra/hydra-head/blob/master/INSTALL_PREREQ.textile

This is a Ruby on Rails 3 gem.

h2. Installation/Setup

h3. Ruby

Currently all Hydra software uses Ruby 1.8.7 (and not 1.9). 

h3. Install Rails, Bundler and Devise

Currently hydra-head is compatible with Rails 3.0.x and incompatible with Rails 3.1.

<pre>
gem install 'rails' --version '~>3.0.11'
gem install 'bundler'
</pre>
  
h3. Generate a new rails application:

<pre>
rails new my_hydra_head
cd my_hydra_head
</pre>

h3. Install Dependencies

First, add them to the "Gemfile":http://gembundler.com/gemfile.html of your application:

<pre>
  source 'http://rubygems.org'

  gem 'rails', '~>3.0.11'

  gem 'blacklight', '~> 3.1.2'
  gem 'hydra-head', '~> 3.2.0'
  gem 'solrizer-fedora', '>=1.0.1'

  # We will assume that you're using sqlite3 for testing/demo, 
  # but in a production setup you probably want to use a real sql database like mysql or postgres
  gem 'sqlite3'

  #  We will assume you're using devise in tutorials/documentation. 
  # You are free to implement your own User/Authentication solution in its place.
  gem 'devise'

  # For testing.  You will probably want to use all of these to run the tests you write for your hydra head
  group :development, :test do 
         gem 'ruby-debug'
         gem 'rspec'
         gem 'rspec-rails', '>=2.5.0'
         gem 'mocha'
         gem 'cucumber-rails'
         gem 'database_cleaner'
         gem 'capybara'
         gem 'bcrypt-ruby'
         gem "jettywrapper"
  end # (leave this comment here to catch a stray line inserted by blacklight!)
</pre>

To install all of the dependencies, run:

<pre>
bundle install
</pre>

On some systems, you will have to install system libraries that various gems rely on.  For example, in order to install the curl gem on ubuntu you have to first install libcurl4-openssl-dev and then re-run bundler.

Even if all of the dependencies are satisfied, this will take a _very_ long time the first time you run it.  IF you become impatient, hit Ctl+C then enter this:

<pre>
  gem install blacklight
  gem install hydra-head -v 3.2.0
</pre>

Then re-run bundle install and it will run slightly faster.

h3. Run the generators and migrations:

Run the blacklight generator

<pre>rails g blacklight --devise</pre>

Run the hydra-head generator

<pre>rails g hydra:head -df</pre>

Run the database migrations

<pre>
rake db:migrate
rake db:test:prepare
</pre>

h3. You're done.

Congratulations.  You've set up the code for your Hydra Head.  

Read "Tools for Developing and Testing":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.Tools.html, then read "How to Get Started":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.HOW_TO_GET_STARTED.html to get a sense of what you can do with your Hydra Head.

h2. Modifying and Testing the hydra-head Gem 

For those developers who want to or need to work on the hydra-head gem itself, see the "Instructions for Contributors":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.TESTING.html

h2. Acknowledgements

h3. Design & Strategic Contributions

The Hydra Framework would not exist without the extensive design effort undertaken by representatives of repository initiatives from Stanford University, University of Virginia, University of Hull and MediaShelf LLC.  Contributors to that effort include Tom Cramer, Lynn McRae, Martha Sites, Richard Green, Chris Awre, and Matt Zumwalt.  

Thorny Staples from Fedora Commons & DuraSpace deserves special thanks for putting all of these people in the same room together.