Deploying Samvera Hyrax

Introduction

Samvera Hyrax is an open-source digital repository framework used by libraries, archives, and museums worldwide to manage, preserve, and provide access to digital collections. Built on Ruby on Rails with Fedora and Solr, Hyrax provides a complete solution for institutional repository needs.

The Samvera community develops Hyrax collaboratively, incorporating best practices from digital preservation, library science, and software engineering. Institutions use Hyrax for everything from thesis and dissertation repositories to research data management and special collections access.

Key highlights of Samvera Hyrax:

Digital Asset Management: Organize and manage digital collections
Preservation Ready: Built-in support for digital preservation standards
Flexible Metadata: Configurable metadata schemas and profiles
Access Control: Embargo, lease, and granular permissions
Multi-Tenancy: Host multiple repositories on one installation
Workflow Engine: Configurable mediated deposit workflows
Batch Ingest: Import large collections efficiently
IIIF Support: International Image Interoperability Framework
DOI Integration: Assign persistent identifiers
Search and Discovery: Solr-powered faceted search
Community Driven: Active development community

This guide walks through deploying Samvera Hyrax on Klutch.sh using Docker, configuring the repository, and managing digital collections.

Why Deploy Hyrax on Klutch.sh

Deploying Hyrax on Klutch.sh provides several advantages for digital repositories:

Simplified Deployment: Klutch.sh builds your Hyrax configuration without complex setup.

Persistent Storage: Attach volumes for Fedora repository, Solr index, and uploaded files.

HTTPS by Default: Secure access with automatic SSL certificates.

Scalable Resources: Allocate CPU and memory for indexing and access workloads.

GitHub Integration: Version control your customizations.

Always-On Access: 24/7 availability for researchers and the public.

Prerequisites

Before deploying Hyrax on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository
Basic familiarity with Docker and Ruby on Rails
PostgreSQL database
Redis for background jobs
(Optional) A custom domain for your repository

Deploying Hyrax on Klutch.sh

Create Your Repository

Create a new GitHub repository for your Hyrax deployment. Add a Dockerfile:

FROM ruby:3.1

RUN apt-get update && apt-get install -y \
    nodejs \
    npm \
    imagemagick \
    ffmpeg \
    libreoffice \
    && rm -rf /var/lib/apt/lists/*

RUN npm install -g yarn

WORKDIR /app

COPY Gemfile Gemfile.lock ./
RUN bundle install

COPY . .

RUN bundle exec rails assets:precompile

ENV RAILS_ENV=production
ENV RAILS_SERVE_STATIC_FILES=true
ENV RAILS_LOG_TO_STDOUT=true

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:3000/ || exit 1

CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]

Generate Hyrax Application

Create your Hyrax application locally:

rails new my_repository -m https://raw.githubusercontent.com/samvera/hyrax/main/template.rb

Push to GitHub

Commit and push your Hyrax application to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app. Connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 3000

Set Environment Variables

Configure essential settings:

Variable	Value
`RAILS_ENV`	`production`
`SECRET_KEY_BASE`	Generate with `rails secret`
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`FEDORA_URL`	Fedora repository URL
`SOLR_URL`	Solr server URL

Attach Persistent Volumes

Add volumes for data:

Mount Path	Recommended Size	Purpose
`/app/storage`	500+ GB	Uploaded files
`/app/derivatives`	100 GB	Generated derivatives

Deploy Your Application

Click Deploy to start the build process.

Initialize Database

Run migrations after deployment:

bundle exec rails db:migrate

Service Dependencies

Fedora Repository

Hyrax requires Fedora for object storage:

Deploy Fedora 6 as a separate service
Configure FEDORA_URL environment variable
Ensure persistent storage for repository data

Solr

Configure Solr for search:

Deploy Solr with Hyrax config
Configure SOLR_URL environment variable
Maintain index persistence

Redis

Enable background processing:

Deploy Redis server
Configure REDIS_URL
Run Sidekiq workers

Initial Configuration

Creating Admin User

Set up administrator access:

# Rails console
User.create!(
  email: 'admin@example.com',
  password: 'secure_password',
  admin: true
)

Repository Configuration

Configure repository settings:

Access admin dashboard
Configure appearance
Set up content types
Configure features

Work Types

Built-in Types

Hyrax includes default work types:

GenericWork: General-purpose content
Image: Image files with IIIF support
Document: Text documents and PDFs

Custom Work Types

Create specialized types:

rails generate hyrax:work ResearchDataset

Configure metadata and behaviors in the generated files.

Metadata Configuration

Core Metadata

Default fields include:

Title, creator, contributor
Date, description, keyword
Rights, license
Subject, language

Custom Metadata

Add fields to work types:

class ResearchDataset < ActiveFedora::Base
  property :methodology, predicate: ::RDF::Vocab::DC.methodology
  property :funding_source, predicate: ::RDF::Vocab::DC.contributor
end

Deposit Workflows

Self-Deposit

Enable direct deposit:

Configure work types
Set permissions
Users deposit directly
Items published immediately

Mediated Deposit

Implement review workflow:

Configure workflow in admin
Assign reviewers
Depositors submit for review
Reviewers approve or reject

Access Control

Visibility Options

Control content access:

Visibility	Description
Public	Available to everyone
Institution	Authenticated users only
Private	Owner and designated users

Embargo and Lease

Time-based access control:

Embargo: Private until date, then public
Lease: Public until date, then private

Collections

Creating Collections

Organize works into collections:

Navigate to Collections
Create new collection
Add metadata
Add works to collection

Collection Types

Configure collection behaviors:

Exhibit collections
Administrative sets
User-created collections

Batch Operations

Batch Import

Import multiple items:

Prepare CSV metadata
Upload files
Run batch ingest
Monitor progress

Batch Export

Export collections:

Export metadata as CSV
Download original files
Include derivatives

IIIF Integration

Image Viewing

Configure IIIF for images:

Enable UniversalViewer
Configure image server
Support zoom and pan

Manifests

Generate IIIF manifests:

Collection manifests
Work manifests
Annotation support

Customization

Theming

Customize appearance:

config.banner_image = 'custom_banner.jpg'
config.institution_name = 'Your Institution'

Branding

Add institutional branding:

Logo placement
Color schemes
Footer content

Preservation

File Characterization

Automatic file analysis:

FITS integration
Format identification
Technical metadata

Fixity Checking

Verify file integrity:

Scheduled checks
Report generation
Alert on changes

Troubleshooting

Solr Issues

Verify Solr connection
Check collection exists
Review index configuration
Reindex if needed

Fedora Problems

Check Fedora availability
Verify credentials
Review transaction logs
Monitor storage

Background Jobs

Check Sidekiq status
Review job queue
Monitor Redis connection
Check worker logs

Additional Resources

Conclusion

Deploying Samvera Hyrax on Klutch.sh provides a professional digital repository platform for your institution. With comprehensive features for digital asset management, preservation, and access, Hyrax meets the needs of libraries, archives, and research institutions. Combined with Klutch.sh’s reliable hosting and scalable storage, you can build and maintain collections that serve researchers and the public for the long term.