Hydra Tutorial

General Installation

For this tutorial we'll be using a Vagrant managed VM bundled with the sample application we'll be working on. While I initially intended to use a Cloud 9 environment, it turns out running both a Jetty servlet with Fedora/Solr installed and a rails server requires more than 512 MB of memory.

To begin, ensure that you are using Vagrant version 1.7.2 and VirtualBox 4.3.28 on your local machine. Once these dependencies are in place, run the following commands in a directory of your choosing to clone down the project, start the VM, and ssh in.

$ git clone https://#{YOUR_BITBUCKET_USERNAME}@bitbucket.org/jbuckle_/sample_hydra_app.git
$ cd sample_hydra_app 
$ vagrant up 
$ vagrant ssh

Note that all commands from hereon out assume that you are ssh'd into your VM unless explicitly stated otherwise.

Before proceeding, we have to install the correct version of Ruby and perform some Rails-but-not-Hydra specific installation steps. These are listed below:

~ $ rbenv install 2.0.0-p481 
~ $ cd /vagrant 
/vagrant $ sudo yum install unzip --assumeyes
/vagrant $ sudo yum install java-1.8.0-openjdk --assumeyes
/vagrant $ gem install bundler --no-ri --no-rdoc
/vagrant $ bundle install --without production
/vagrant $ rake db:schema:load
/vagrant $ rake test

If everything worked, your test suite should pass. There are two things that shouldn't seem familiar in the command block above. The first is the use of rbenv install. Rbenv is a tool for switching between ruby versions on a system. We are using rbenv here because it is what was already installed on the base box I found. The second interesting thing is the rake db:schema:load command. Unlike rake db:migrate, which alters the database by executing every pending migration in chronological order, the schema load command reads from Rails.root/db/schema.rb to generate the database in one pass. Because migrations are slow and flaky when run in large numbers, it is recommended that you get in the habit of using db:schema:load when creating a fresh database for an existing application.

Jetty Installation

The next step is to ensure that local versions of Fedora and Solr are available for use throughout the rest of the tutorial. Fortunately Hydra provides an easy way to do this. Run the following command -

/vagrant $ rails g hydra:jetty 

This invokes a rails generator that creates a jetty/ directory off your application root. This directory contains all of the code necessary to run a Jetty Servlet hosting Fedora and Solr. In addition, the inclusion of the jettywrapper gem in our Gemfile gives us access to a number of rake tasks that handle basic administration of this servlet. To see these, execute rake -T | grep ' jetty'[^1].

If everything has worked, you should now be able to execute the following command -

/vagrant $ rake jetty:start

and get some output indicating that jetty has started rather than an error message. To verify that everything is working correctly, we'll log into the rails console and run a single command that touches our new Solr instance. Note that you should wait 10-15 seconds after starting jetty to run these commands.

/vagrant $ rails console 
irb(main) > ActiveFedora::SolrService.query('*:*') 
.
.
.
[]
irb(main) > 

Assuming everything worked, you should get back an empty array (like above). Congratulations! You now have all of the infrastructure needed to do local development with Hydra[^2].

You are now ready to move on to the next step of the tutorial. Before beginning with the open-ended exercises that comprise the majority of the work you'll be doing, we'll walk through a number of finger exercises that familiarize you with the new components of the Hydra system.

Goto Finger Exercises

[^1]: We do a grep ' jetty' instead of the much more obvious/natural grep jetty to filter out the rake hydra:jetty:sometask tasks provided by the Hydra gem. The fact that a separate gem is required to get access to commands that start/stop the jetty server has caused me about five minutes of frustration on every new Hydra project I've started, including this one.

[^2]: In the interest of time, I actually did do a fair amount of work with the VM and the application codebase that readers of this tutorial were not obliged to replicate. I have compiled the steps I took and why they were necessary in [a separate wiki page](# TODO).