How to Get Started
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.
- Set up a Hydra Head (a Rails app that uses the hydra-head plugin) and run it
- Understand how Hydra fits into and uses Rails MVC (Model, View, Controller) structures
We maintain a reference copy of the Hydra Head that is described in this Tutorial. It contains working versions of all the Models, Controllers, Views, and tests that you will be creating. If you get stuck, take a look at those files for ideas. We also maintain a Hudson build for this reference copy in order to ensure that all of the tests pass.
The code: http://github.com/projecthydra/hydra-tutorial-application
The Hudson Build: http://hudson.projecthydra.org/job/hydra-tutorial-app/
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
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.
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://github.com/projecthydra/hydra-jetty.git jetty rake hydra:jetty:config rake jetty:start
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.
Ensure Fedora is running. You should see the Fedora Repository Information View here: http://127.0.0.1:8983/fedora/describe should show the Fedora Repository Information View. The following query should return objects: http://localhost:8983/fedora/objects?pid=true&title=true&terms=&query==
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 0.0.0.0 rather than 127.0.0.1. To get around this, you can tell the server which address to bind to using the -b flag. ie. “rails server -b 127.0.0.1”
If Rails still does not seem to be working properly, consult the output on the command line to see if there are any errors.
Now that you’ve set up an empty Hydra Head, you might want to walk through the Out of the Box Tour. That page simply tours through what comes out of the box with hydra-head and lets you run the hydra-head tests within your app in case you want to confirm that everything was installed properly.
Otherwise, to learn how to actually create a Rails app using hydra-head, continue reading on this page.
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 App Mods 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.
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.
Content Type Example: Journal Article steps through adding the Journal Article content type to a Hydra Application, including all the parts needed in each of the MVC pieces.
Hydra objects, content models(cModels) and disseminators
- descMetadata (required): Descriptive Metadata like MODS or DC. MODS is recommended
- rightsMetadata (recommended): Rights, License, and Permissions information. Hydra rightsMetadata XML is recommended.
h4. Understanding Parts (Where will my uploaded files go?)
A primitive is a fundamental atom object that bears an actual file payload. They are single, (near-) universal content types which may either stand-alone or be incorporated into higher order content types (in a book or ETD, e.g.).
Higher Level Objects represent higher-level, molecular objects that may have primitives and/or other Higher-level objects as children.
isPartOf — Hydra reserves this predicate for use in representing part-whole relationships between objects. This occurs most often when representing which Primitives (ie. an uploaded PDF) are part of a Higher Level object (ie. a MODS Article)
See Reference for more links.