How to Get Started

Jennifer Lindner edited this page Nov 15, 2016 · 51 revisions

Getting Started Building Your Own Hydra Application

Before You Begin

This document is a work in progress. We are actively seeking feedback. If you run into anything that is incorrect or confusing, please email the hydra-tech mailing list and let us know.

What you will learn from this document

  1. Set up a Hydra Head (a Rails app that uses the hydra-head plugin) and run it
  2. Understand how Hydra fits into and uses Rails MVC (Model, View, Controller) structures

If you get stuck

Try asking questions on the hydra-tech mailing list, or in the #projecthydra IRC channel on Freenode.

Set up a new Hydra Head

Make sure you have looked over the prerequisites .

See the README for instructions on creating a new Hydra Head.

We will be using both RSpec and Cucumber in this Tutorial, so make sure to follow the instructions in the “RSpec and Cucumber for Testing” section of Tools for Developing and Testing Your Application

Starting the App out of the Box

(1) Migrate the development databases.

From the rails application root directory, run

  rake db:migrate

Don’t worry if you’ve already run the migrations. It’s safe to re-run rake db:migrate.

(2) Start Jetty, pre-configured with Fedora and Solr

Stop any copies of jetty (or anything else using port 8983) before running this command.
(Note that java 1.6 must be invoked by the “java” command or Fedora won’t work.)

You may already have installed jetty as a submodule per the Hydra-Jetty section of Tools for Developing and Testing Your Application

  git clone git:// jetty
  rake hydra:jetty:config 
  rake jetty:start

Note: If you are using a pre-5.0 version of hydra-head or a pre-existing code base, your solr_conf and fedora configs will be incompatible with the copies of Fedora and Solr in the latest version of hydra-jetty. To fix this, you can either update your solr_conf and fedora configs (grab them from the master branch of hydra-head) or pin your submodule to the 4.x branch of hydra-jetty.

  # !!! Don't do this if you don't need to !!!
  cd jetty
  git checkout 4.x
  cd ..
  git add jetty
  git commit -m"pinning hydra-jetty to 4.x branch"

This will start up a pre-configured jetty instance running Fedora and Solr on port 8983.

Ensure Solr is running. You should see a Solr admin page here: http://localhost:8983/solr/development/admin/ . You should be able to click on the Statistics link (or go to http://localhost:8983/solr/development/admin/stats.jsp) and there should be more than 0 documents in the index if you loaded any fixtures. Or look for documents in http://localhost:8983/solr/development/select?q={!defType=dismax}*:* if you have any fixtures loaded. (If the solr links does not work, try http://localhost:8983/solr/)

Ensure Fedora is running. You should see the Fedora Repository Information View here: should show the Fedora Repository Information View. The following query should return objects: http://localhost:8983/fedora/objects?pid=true&title=true&terms=&query==

(3) Start the Rails Application

  rails server

To ensure the rails app is running, go to http://localhost:3000/

On some systems, the http://localhost:3000 address will be broken because WEBrick binds to rather than  To get around this, you can tell the server which address to bind to using the -b flag. ie. “rails server -b”

If Rails still does not seem to be working properly, consult the output on the command line to see if there are any errors.

Tutorial: Dive Into Hydra

Dive Into Hydra is a tutorial for an initial Hydra head setup, simple models, and solr indexing. Very helpful for beginners.

Hydra and Rails MVC (Model, View, Controller)

In an MVC framework, the Model defines the attributes and behaviors of your various objects, allowing you to persist those objects and retrieve them. By default, Rails Models uses ActiveRecord to persist & retrieve objects using SQL databases. With Hydra, we use ActiveFedora to connect with Fedora and Solr instead of a SQL database.

Controllers handle requests from clients (ie. HTTP requests from a web browser), loading the necessary information and rendering the appropriate responses (ie. HTML pages returned to the browser). They use your Models to load the information and they use your Views to render the response. In this way, Controllers are like connectors or coordinators — they coordinate the flow of activity in your application when it receives requests.

Making local changes to your Hydra Application

In order to make it easy to get any new functionality added to the hydra stack while retaining your Hydra application’s localizations, your local hydra application code should be set up to override the upstream Hydra stack code.

Luckily, rails engines has made this easy – the Hydra code is organized so your localizations are kept separate from the core hydra application code.

Moreover, to ensure your localizations won’t be broken by upgrading the Hydra core code, 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.

Initial Modifications to Your Own Hydra Application

YOUR Hydra Application – Initial Modifications explains how to make two basic changes to your hydra rails application and how to write the appropriate tests for them. You should review the Initial App Mods document before continuing this tutorial.

Adding a new Content Type, Fedora 3 and Fedora 4

Fedora 3 Content Type Example: Journal Article steps through adding the Journal Article content type to a Hydra Application with a Fedora 3 data store, including all the parts needed in each of the MVC pieces. Dive Into Hydra: Build a Book Model covers adding content to a Hydra App with a Fedora 4 data store.

Hydra Modeling Conventions

See Hydra Modeling Conventions

For Further Information

See Reference for more links.