The Technology Stack

The Technology Stack

Samvera Diagram_v2_may-14-2025,.jpg
(Click to enlarge image) A diagram of common components in Samvera applications and how they relate to each other

* Hyrax and Hyku include built-in support for using either Postgres, memory, or Fedora 6 for metadata storage. The options for file storage are disk storage, memory, or Fedora 6. Some applications may also optionally use Solr/Blacklight for secondary indexing of metadata. Hyku also supports Amazon S3 cloud storage out-of-the-box.

New applications can use any of these options, or use a custom adapter to connect to a different backend (see “External Adapters” in the Hyrax wiki). Older or legacy applications may use the Wings adapter to connect to Fedora 4, but this is not recommended for new applications, since Fedora 4 is end-of-life and the Wings adapter will be deprecated in a future Hyrax/Hyku release.

See the “Valkyrie” section below for a more detailed explanation of adapters and how they fit into the Samvera architecture.

Samvera Applications

Broadly, these are Ruby on Rails based applications, such as Hyrax, that follow Samvera conventions. Other Hyrax-based applications supported by the community include Hyku (Hyrax with multitenancy and other features) and Avalon (focused on audio/video materials).

While it is possible to create your own Samvera application by assembling the right components, and this has been a common practice in the Samvera community in the past, ongoing maintenance of home grown solutions will be more expensive than sharing maintenance costs with the rest of the community.

Valkyrie

Valkyrie is a gem that handles the transfer of data between a persistent data store (e.g. a database) and the Samvera application. It handles core functions like creating, reading, updating, and deleting files or metadata using “adapters.” By default, Valkyrie ships with adapters for the backends pictured above. But you can also write your own adapter if the default adapters don’t fit your needs.

Valkyrie gives organizations the flexibility to choose different backends, while sharing front-end logic and code. It can also make migration between backend systems easier by reading from one data store and writing to another. You can find a detailed rationale and FAQ on the Hyrax github wiki. In the past, older Samvera applications were locked into using Fedora 4 as the persistence layer and used Active Fedora as the middleware to connect to Fedora 4.

Instructions for configuration with various adapters can be found on the Valkyrie github README page.

Storage Adapter and Backends

The storage adapter connects the Samvera application to the place where your digital objects are stored or will be stored once uploaded to the application. Here is a list of possible backends that are supported by both Hyrax and Hyku, unless stated otherwise:

  • In-Memory - used primarily for testing and not recommended in production

  • Disk Storage - this may be a large NFS Share in production

  • Fedora 6 - repository software that supports OCFL (Oxford Common File Layout). Interested developers may want to explore Sirenia, a test/sample application compatible with Fedora 6.

  • S3 Cloud Storage (supported in Hyku only) - Samvera apps can use the Valkyrie-Shrine adapter/gem to connect to cloud storage. Although only Hyku comes bundled with S3 support, Hyrax can still be configured to use valkyrie-shrine.

Metadata Adapter and Storage

The metadata adapter connects the application to the metadata store. The metadata store acts as the primary, canonical source of metadata.

Some institutions may want to implement a secondary index for search/querying. For example, if your institution wants to store linked data in Fedora but use Solr for search, then you would use the metadata adapter for Fedora 6 and the indexing adapter for Solr (see below).

Here is a list of possible metadata stores that are supported by Hyrax & Hyku:

  • In-Memory - used primarily for testing and not recommended in production

  • Postgres (database) - interested developers may want to explore Koppie, a Hyrax test/sample application that uses Postgres for metadata storage.

  • Fedora 6 - repository software that supports Linked Data

Indexing Adapter and Storage (optional)

Currently, only Apache Solr is supported for this purpose. Solr is used with/by Blacklight to provide a search interface for metadata in Samvera applications.

Middleware & Plugins

Note: this list is non-exhaustive.

Hydra-Head

Hydra-Head is a Ruby-on-Rails gem containing the core code for a web application using the full stack of Samvera building blocks.

Blacklight

Much of our search and display behavior is inherited from Blacklight. Many Samvera institutions also run Blacklight applications separately from Samvera, to provide search and discovery for their collections. The Blacklight Project also has many of its own plugins, such as Spotlight, for building virtual exhibits, and GeoBlacklight, which enhances Blacklight for use with geospatial data.

Blacklight relies on RSolr, a ruby gem for connecting to Solr using the Solr API.

Hydra Derivatives

A gem to create derivatives for uploaded content. This might include, for example, generating thumbnails for large images, down-sampled audio and video for web steaming, or thumbnail snapshots of PDF documents.

Hydra Editor

Hydra-editor is a basic editor for Samvera objects. It provides the edit interface for works and collections.

Questioning Authority

Questioning Authority provides a set of uniform RESTful routes to query any controlled vocabulary or set of authority terms. Results are returned in JSON and can be used within the context of a Rails application or any other Ruby environment.

Questioning Authority - How do I use this?

Questioning Authority Wiki

RIIIF

The default IIIF server (see Github repo) that serves images to deep-zoom image viewers, such as Universal Viewer (default iiif viewer in Hyrax/Hyku).

Alternatives for RIIIF include node-iiif (NodeJS implementation), or serverless-iiif (AWS Serverless Application).

File Characterization

Hydra File Characterization uses fits and ffprobe to characterize files and extract metadata about them. It might tell you what kind of image encoding an image uses, along with it’s height and width, for example.

Browse-Everything

Browse-everything is a rails engine providing access to files in cloud storage. Currently there are drivers implemented for Dropbox, Skydrive, Google Drive, Box, and a server-side directory share.

Getting Started with BrowseEverything

Configuring BrowseEverything and using JavaScript methods

LDP

A ruby gem called ldp for implementing LDP (Linked Data Platform) interaction patterns with Fedora 6 or Fedora 4 (legacy).

Bixby

Bixby is a gem containing the default configuration settings for RuboCop used to enforce common Ruby style guidelines across Samvera community projects. (See how to use bixby.)

Legacy Components

The following components are not recommended in new Samvera applications because they are deprecated, or will be deprecated in the near future. They are documented for migration and historical purposes.

Active Fedora

ActiveFedora provides an Active Record-like interface and pattern to persist objects to Fedora 4.

Wings

Wings is the storage and metadata adapter for Fedora 4. It is “a toolkit integrating Valkyrie into Hyrax as a bridge away from the hard dependency on ActiveFedora.”

Notes from the Hyrax Github:

`Wings` is primarily an isolating namespace for code intended to be removed after a full transition to `Valkyrie` as the persistence middleware for Hyrax. Applications may find it useful to depend directly on this code to facilitate a smooth code migration, much in the way it is being used in this engine. However, these dependencies should be considered temprorary: this code will be deprecated for removal in a future release.