Hyrax

Hyrax is a Ruby on Rails Engine that serves as the core framework for building institutional repositories, digital libraries, and research data platforms. It is not a standalone web application; instead, developers mount the Hyrax engine inside their own Rails app to inherit its domain model, workflows, and administrative UI. This design promotes rapid prototyping while keeping the freedom to extend or replace any component with custom logic.

Technical Stack & Architecture

Hyrax is built atop the Ruby on Rails 7 ecosystem, leveraging ActiveRecord for persistence and ActionCable for real‑time features. The engine ships with a comprehensive set of Rails generators that scaffold repository objects, workflows, and metadata schemas. Data is stored in a relational database (PostgreSQL or MySQL) via ActiveRecord, while large binary assets are off‑loaded to ActiveStorage and backed by cloud or on‑prem storage services such as Amazon S3, Azure Blob, or local file systems. The front‑end is composed of Rails views and partials that can be overridden, or replaced with a modern JavaScript framework (React/Vue) using the react-rails gem.

Hyrax’s modular architecture is driven by a plugin system: each feature (e.g., Hyrax::Workflow, Hyrax::BatchUpload) is a separate Rails engine that can be enabled or disabled through the admin dashboard. This plug‑in model allows developers to cherry‑pick only the capabilities they need, reducing bloat and simplifying maintenance.

Core Capabilities & APIs

• Object Types – Define custom ActiveRecord models (Collection, Work) and associate them with metadata schemas via the Valkyrie gem.
• Workflows – Declarative workflow engine (Hyrax::Workflow) that supports multi‑step, role‑based approvals and event callbacks.
• Metadata & Search – Full‑text search powered by Elasticsearch (via the searchkick gem) with faceted filtering, and metadata editing via JSON‑API compliant endpoints.
• Ingest & Validation – File ingestion pipelines using ActiveStorage callbacks, with optional validation hooks (checksum, file type).
• API – RESTful JSON API endpoints for CRUD operations on works and collections, plus a GraphQL interface (hyrax-graphql) for advanced querying.
• Hooks & Callbacks – Rails callbacks (after_create, before_destroy) and custom event hooks that allow integration with external services (e.g., DOI minting, ORCID linking).

Deployment & Infrastructure

Hyrax is designed for self‑hosting in a wide range of environments. A typical deployment stack includes:

1. Rails + Puma – Web server, containerized via Docker or deployed on a VM/Heroku‑like platform.
2. PostgreSQL/MySQL – Core relational database; migrations are managed through Rails’ rake db:migrate.
3. Elasticsearch – Search backend; can be run in a separate container or managed service.
4. ActiveStorage – Storage backend; supports local disk, S3, or GCS.
5. Redis – Optional for background jobs (Sidekiq) and ActionCable.

The project includes Docker Compose files and a CONTAINERS.md guide that shows how to spin up the full stack locally. For production, Kubernetes manifests are available in the k8s/ directory, allowing horizontal scaling of web workers and background jobs. Hyrax’s modularity means you can run a minimal instance with only the web server and database, or a full‑featured deployment with search, ingest pipelines, and analytics.

Integration & Extensibility

Hyrax exposes a rich API surface that developers can consume or extend:

• Custom Engines – Write your own Rails engine and mount it alongside Hyrax; the routing system will resolve conflicts automatically.
• Webhooks – Trigger external services on events (after_publish, before_destroy) via the built‑in webhook controller.
• External Services – Integrate with ORCID, Crossref, and institutional authentication providers (Shibboleth, SAML) through the devise and omniauth gems.
• UI Customization – Override views, partials, and JavaScript assets; use the hyrax-frontend gem to swap out the default UI for a SPA.
• Testing Hooks – The engine ships with RSpec test helpers and fixtures, enabling rapid unit and integration testing.

Developer Experience

Hyrax’s documentation is organized around Wiki pages, a RubyDoc API site, and live examples in the hyku repository (a Hyrax‑based application). The community maintains a Slack channel, mailing list, and issue tracker that is responsive to pull requests. Licensing under Apache 2.0 removes barriers for commercial use, and the project’s continuous integration (CircleCI) ensures that new releases are thoroughly tested.

Use Cases

• Academic Libraries – Deploy a compliant institutional repository with DOI minting, embargo workflows, and granular access control.
• Research Data Centers – Use Hyrax as a data curation platform, integrating with ORCID and metadata standards (Dublin Core, MODS).
• Consortia Platforms – Leverage the Hyku fork (a Hyrax‑based repo) to provide a shared, community‑driven repository for multiple institutions.
• **Open