/hydra-tutorial

Primary LanguageRuby

Important Notice

This tutorial is currently BROKEN

We are in the process of updating the tutorial to work with hydra-head 5, which was released December 17 2012.

Some of the improvements built into the next release:

  • compatibility with hydra-head 5.x
  • compatibility with Capybara 2.x (this will make the "integration" tests work again)
  • fixes to make jetty run more smoothly
  • updates to instructions about how to use CanCan for access controls

The new version will be out before January 1st 2013.

Hydra Tutorial Application

The tutorial will:

  • Install all Hydra / Rails application prerequisites.
  • Generate a new rails application.
  • Walk through building a Hydra model:
    • First, as an ActiveFedora::Base object with an XML datastream.
    • Then, with a simple OM terminology for a basic, contrived schema
    • Finally, with a simple MODS-based terminology.
  • Wire the model into Rails using standard Rails scaffolding.
  • Add blacklight and hydra-head gems for object discovery.
  • Add some basic Rspec and Capybara tests.

At the end of the tutorial, you will have a working Hydra Head for adding MODS-based metadata records.

Throughout the process, there are several prompts to poke around the Rails console and/or in a browser. In addition, Git is used to help you track changes in the code from one step of the tutorial to the next.

In subsequent releases of the tutorial, we will try to wire in file uploads, collections, more complete test example, etc.

Pre-requisites

This tutorial depends on the following:

  • A Unix-like operating system.
  • Ruby 1.8.7 or higher (but 1.9 is recommended).
  • Java 1.5 or higher (to run Solr under a Java servlet container).
  • RVM (recommended).
  • Git (recommended).

ActiveFedora, Hydra, and Rails require some gems that compile binaries and rely on installed system libraries like libxml, libxslt, and sqlite. If these aren't installed, the tutorial will not function properly. If something seems wrong, try running bundle install directly inside the tutorial directory, and watch the output carefully.

Setup

Install rvm to get Ruby:

$ curl -L https://get.rvm.io | bash -s stable --ruby
$ rvm install 1.9.3 # (See https://rvm.io/rvm/install/ )

Consider using a hydra-specific gemset.

$ rvm use 1.9.3@hydra-tutorial --create

Install the hydra-tutorial gem:

$ gem install hydra-tutorial

Running the tutorial

Run the tutorial one step at a time -- specifically, run the next step in the tutorial:

$ hydra-tutorial

Run all remaining steps in the tutorial:

$ hydra-tutorial --run-all

Reset the tutorial back to the beginning:

$ hydra-tutorial --reset
$ rm -rf hydra_tutorial_app   # Or rename the directory.

Other options relevant to users:

--no-git   # Do not create Git commits for each tutorial step.
--diff     # Run git diff: previous vs. current code.
--app FOO  # Set the name of the Rails application subdirectory.
           # The default is hydra_tutorial_app.

Known issues

If the tutorial bombs with the execJs: 'Could not find a JavaScript runtime' error, you may need to install a Javascript runtime such as node.js.

Developer notes

You can run the entire tutorial non-interactively from the root of the Git project checkout:

$ bin/hydra-tutorial --run-all --quick