Hydra Stack - The Hierarchy of Promises


What goes into a Well Designed Software Stack?

A well designed stack: Pragmatic, Reusable and Specific from the bottom up.

Separation of Concerns:

Each component in the stack should only be concerned with pragmatically fulfilling its functionality in the best possible way. This increases your options for re-using the components in unexpected ways and for replacing a component with minimal overhead.

Best of Breed:

Assemble a full stack of components that are each the best option for the tasks they fulfill.

From the Bottom Up:

The rest of this page describes the Hydra stack bottom-up from the low-level storage to the search and discovery interface.

Persistence Layer

File System


  • A place to store files
  • Interchangeable with any filesystem or filesystem emulator (e.g. iRODS)

Fedora: Digital Repository as Web Service

  • Abstraction layer on top of File System
  • Data Model (LDP)
  • Repository-level security
  • Versioning
  • Preservation support & object history


  • If you pass content or metadata to Fedora via the Fedora APIs, they will be persisted
  • You can retrieve content and metadata from Fedora using its APIs and unique, persistent identifiers
  • If you provide security policies, Fedora will enforce those policies (WebACL)
  • Fedora will send messages about interactions, allowing you to maintain a secondary index.

Triplestore (optional)

An RDF-based graph of Fedora object relationships.

SQL Database (minimally relevant)

Fedora may use a SQL database to store metadata with certain persistence backends, such as Modeshape.

Solr: Flexible, Faceted, Scalable Full Text Search Index

Flexible, Scalable full-text search index with support for facets.


  • If you populate the Solr index, you can perform complex faceted search queries
  • You can configure your indexes in many ways to optimize for specialized searches
  • You can include full text information in your search indexes and inspect that information when evaluating queries

SolrWrapper & FcrepoWrapper (optional)

SolrWrapper and FedoraWrapper are provided as convenient command line interfaces for launching Solr and Fedora.

Application Layer


Client API for consuming Fedora’s REST API via Ruby.


  • Ruby API methods for consuming any/all of Fedora’s LDP API methods
  • You can include LDP into your applications as a Ruby Gem (one line)

ActiveFedora: ActiveModel Pattern for Fedora

ActiveFedora is a Ruby gem that applies the ActiveModel pattern to working with Fedora objects. It also uses a "convention over configuration" approach to applying best practices for working with Fedora and digital repositories.


  • You can use ActiveModel syntax to model and CRUD Fedora content
  • You can use OM to tell ActiveFedora how to CRUD your XML metadata
  • You can use ActiveFedora’s ActiveFedora::Base class to tell ActiveFedora how to CRUD RDF metadata
  • You can tell ActiveFedora where to find Fedora and Solr by putting information into your application’s fedora.yml and solr.yml files
  • The ActiveFedora API methods will work as described, allowing you fine-grained access to trigger, manage, or override various parts of the Fedora & Solr CRUD operations
  • You can override most of the API methods in your own applications
  • You can include ActiveFedora into your applications as a Ruby Gem (one line)

OM (Opinionated Metadata): DSL for XML Metadata


  • You can use the OM syntax to create a custom vocabulary for referring to fields (a DSL) to CRUD XML metadata
  • The OM API methods allow you fine-grained access to trigger, manage, or override various parts of the XML CRUD operations
  • You can override most of the API methods in your own applications
  • You can include OM into your applications as a Ruby Gem (one line)


Basic API Interface: Connect, Index Object, Index All, Create Document
Solr Field name Mapper
TerminologyBasedSolrizer - provides a “to_solr” method for OM documents


  • There is an API Interface that system-specific implementations will conform to
  • The Solrizer API methods allow you to generate Solr fields based on configured mappings and to convert XML files into Solr documents based on OM terminologies
  • You can trigger any Solrizer implementation using Solrizer API interface or rake tasks
  • You can include Solrizer into your applications as a Ruby Gem (one line)

Rails Layer

Ruby on Rails

Not a Hydra component, but central to creation of Hydra Heads.


  • If you use Ruby on Rails, you will be more productive, your applications will be awesome, and your developers will be happier

Blacklight Rails Plugin

Blacklight allows you to rapidly build and customize rich, faceted search & discovery interfaces for arbitrary content. Originally developed as an Open Public Access Catalog (OPAC) for Library MARC records, it is now used across many institutions to expose search interfaces for a plethora of rich, heterogeneous content. Key parts:

  • Catalog Controller
  • Blacklight config
  • Facets
  • Blacklight API: Query Solr, inject/modify query parameters
  • Blacklight View Helpers:
    • View helpers are a Rails convention. They are methods that you can use, as you see fit, to display dynamically generated information within your view templates. Using view helpers allows application developers to implement business logic behind stable, tested helper methods while keeping your view templates simple and straightforward.
  • Blacklight UI: Layout, Pagination
  • User tracking & UI: From Devise by default


  • If you include Blacklight in your application and configure it, you will have a full faceted search & discovery interface for the content in your Solr index
  • Blacklight handles features like pagination of search results, saving searches, etc. for you
  • You can include Blacklight into your applications as a Ruby Gem (one line)

Hydra-Head Rails Plugin

Unlike the other Hydra components, the hydra-head plugin is a loose conglomeration of functionality that falls under the heading “everything you need to build an and-user facing repository application”. It incorporates Blacklight and ActiveFedora into a Rails application and gives you all of the tools for building custom user experiences around on everyday repository CRUD activities.


  • Will put together all of the other pieces for a basic HydraHead Rails engine

Hydra Controller (mixin)

Extends your Rails Controllers with the basic methods needed to use ActiveFedora objects, Hydra Access Controls, Hydra View Helpers, etc.

Hydra Access Controls

Hydra’s Access Controls gem allows you to gracefully handle the complex problem of Authentication and Authorization for digital repositories. If you want to create Hydra-compliant objects, you can easily “include” Access Control into your custom models. Key parts:

  • rightsMetadata: Simple, extensible vocabulary for asserting (and preserving) access control information for digital repository content
  • Default (database-backed) Users & Groups
  • Clear ways to replace default Users & Groups with institution-specific Authentication & Groups (e.g. Shibboleth, LDAP, CAS, OpenAuth, etc.)
  • Access Controls Enforcement, including Gated Discovery on Search
  • Customizable Access Controls Evaluation for search, read, download, and edit
  • Uses Can-Can to evaluate and enforce rightsMetadata statements

Note: Hydra’s AccessControls do not currently integrate with Fedora’s built-in XACML Security, though some Hydra participants are pursuing work that would achieve that connection.


  • If you put rightsMetadata on an object, Hydra will control access based on those assertions
  • Content will only appear in search results for a user if the user has permission to discover them (Gated Discovery)
  • You can replace the Authentication portion of Hydra Access Controls with another system while continuing to use all other parts of the Access Controls code

Hydra File Management

The file management and Fedora FileAsset object management code is being broken out into a separate gem as of June 2012. If you want to create Hydra-compliant objects, you can easily “include” FileManagement into your custom models

Hydra Rake Tasks


  • If you have the hydra-head gem included in your application, you can use the Hydra rake tasks to do common things like refresh fixtures, run Hydra-provided tests, etc.

Hydra View Helpers

These are all being deprecated in HydraHead release 5.x. Applications should use the Rails stack instead.

  • Overrides to misc Blacklight view helpers
  • Non-standard handling of JavaScript includes
  • Misc legacy view helpers specific to certain uses - displaying articles, listing Downloadables, rendering uploaders
  • Helpers for generating forms that work with (deprecated) Hydra AssetsController


  • ???

Hydra Submission Workflow (deprecated)

Relies on deprecated Hydra AssetsController. This may be resuscitated at a future date, but it isn't functional in Hydra 4.0 and won't be in Hydra 5.0.

A configurable, accessibility-oriented way to do multi-step submission of objects & metadata: i.e.

  1. Provide Title & Author
  2. Upload Files
  3. Select License
  4. Save/Submit.

Can be presented as a single page using the accompanying submission workflow JavaScript.

Other Tools (Not Part of Stack)

Some tools that are central to our work process but not actually part of the Hydra Stack: