Hydra-Head is a Rails Engines plugin containing the core code for a Hydra application. The full hydra stack includes the following:
- Blacklight (a rails engines plugin) for the User Interface
- Solr (a java application, also ported to other languages) for the Search Engine
- ActiveFedora (a ruby gem) to let the rails application talk to fedora
- OM (a ruby gem) to streamline the metadata configuration
- Solrizer (a ruby gem) to write content to the Solr index
- SolrizerFedora (a ruby gem) to write Fedora content to the Solr index.
- HydraHead (a rails engines plugin) to glue it all together
For a more thorough overview of the Hydra framework, see HYDRA_OVERVIEW.textile.
This is a Ruby on Rails 3 gem.
Use RVM (for your own Sanity)
This isn’t absolutely required, but working without RVM makes life really difficult.
See https://rvm.beginrescueend.com/rvm/install/ for instructions on installing and running RVM.
After installing RVM, set it up to use rvmrc files when they’re available. This will cause RVM to automatically switch Ruby versions and gemsets when you cd into different code bases. Currently all Hydra software uses Ruby Enterprise Edition 1.8.7 (ree-1.8.7) and each component or Hydra Head uses its own gemsets (ie. hydra-head uses a gemset called hyhead, hypatia uses a gemset called hypatia so that you can install a different set of dependencies for each. )
For information about using and setting up RVM to use .rvmrc files, see http://beginrescueend.com/workflow/rvmrc/
Make sure you have the right version of Ruby
Currently all Hydra software uses Ruby Enterprise Edition 1.8.7 (ree-1.8.7)
If you are using RVM, you can install ree-1.8.7 with the following call:
rvm install ree-1.8.7
If you are not using RVM, consult the appropriate online documentation for installing Ruby on your operating system.
Install Rails, Bundler and Devise
Currently hydra-head is compatible with Rails 3.0.x and incompatible with Rails 3.1
gem install 'rails' --version '~>3.0.10' gem install 'bundler'
Generate a new rails application:
rails new my_hydra_head cd my_hydra_head
Init the git Repository
First, put a .gitignore file into the root of your project to keep your repository clean. You could start with the .gitignore file from the hydra-head gem
Now init the git repository and add the initial set of files
git init git add . git commit -m"Initial Commit: empty rails app"
First, add them to the Gemfile of your application:
source 'http://rubygems.org' gem 'rails', '~>3.0.10' gem 'blacklight', '~> 3.0.0' gem 'hydra-head', '~> 3.1.0' # 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-ruby', :require => '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 'solrizer-fedora', '>=1.0.1' 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!)
To install all of the dependencies, run:
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:
gem install blacklight gem install hydra-head -v 3.1.4
Then re-run bundle install and it will run slightly faster.
Advanced usage: Running against the freshest version of the hydra-head code from Github
We don’t recommend this for new users or for production applications, but it is very useful during active development.
If you are in a position where you want/need to run your application with the very latest hydra-head code from Github, this is easy to do. Simply update the line in your Gemfile that lists hydra-head as a dependency and enter this instead:
gem "hydra-head", :git => "git://github.com/projecthydra/hydra-head.git", :branch=>'rails3'
After updating the Gemfile, re-run ‘bundle install’.
You can also do this with other gems. For example, if you want to force your app to use the latest active-fedora code from the “HYDRA-721” branch on GitHub, you can put this in your Gemfile:
gem "active-fedora", :git=>'git://github.com/mediashelf/active_fedora.git', :branch=>'HYDRA-721'
Run the generators and migrations:
Run the blacklight generator
rails g blacklight --devise
Run the hydra-head generator
rails g hydra:head -df
Run the database migrations
rake db:migrate rake db:test:prepare
Add all the generated code to the Git repository
git add . git commit -m"Ran Blacklight, Hydra-Head, and Cucumber Generators"
Congratulations. You’ve set up the code for your Hydra Head.
Read the next section on Tools for Developing and Testing, then read How to Get Started to get a sense of what you can do with your Hydra Head.
Tools to Help You Develop and Test your Application
The Hydra Jetty
The Hydra project provides a copy of Jetty with Fedora and Solr pre-installed. This is useful for running tests against and for running your code against while you’re actively working on your hydra head.
Most projects add hydra jetty to their code as a git submodule
git submodule add git://github.com/projecthydra/hydra-jetty.git jetty git commit -m"added jetty submodule"
Now that you’ve added the submodule to your git repository, whenever you grab a new working copy of the code, you can get hydra-jetty by running:
git submodule init git submodule update
Important: To apply the your application’s solrconfig.xml and schema.xml to the copy of solr in hydra-jetty, run this:
Now you’re ready to start jetty. We’ve written a useful gem that gives you rake tasks for starting and stopping jetty. Make sure you have jettywrapper in your Gemfile
Now that you have jettywrapper installed, to start jetty userake jetty:start
To stop jettyrake jetty:stop
For more information about using jettywrapper, see http://hudson.projecthydra.org/job/jettywrapper/Documentation/
RSpec and Cucumber for Testing
We STRONGLY recommend that you write tests for every local change you make. This will allow you to ensure that upgrading the core code doesn’t break any local changes you have made.
(when should it be a feature rather than a spec)
very basic rule: if it’s testing something created with view, use a cucumber feature to test. If it’s not created by view code, use a spec to test.
RSpec for Functional Tests
Most Ruby projects use either RSpec or Shoulda to write and run their Functional Tests. We use RSpec for all of the Hydra software.
To set up all the files you need to use rspec to test your Rails application, simply run the rspec generator. This will create a directory called “spec” and put all of the necessary files into it.rails g rspec:install
Cucumber to Test User Experience
If you will be writing cucumber tests, run the cucumber generator. This will create a directory called “features” and populate it with all the basic parts you need to run Cucumber tests on your Rails application.rails g cucumber:install
(optional) Move everything into the test_support Directory
Within the blacklight and hydra-head code bases, we have started putting all of our test-related code into a directory called test_support. If you want to follow this convention, move the generated spec and features directories into test_support, so that you have:test_support/ features/ fixtures/ spec/
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
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.