1. Context

Open

The Samvera Foundation community often receives a number of questions around Hyku and Hyrax features, customization capabilities, and ultimately which direction to go with their digital repository solution. 

This Q&A compilation addresses some of the most common questions we receive here at Notch8, and they are often covered in discussions within the Samvera Foundation Partners circle. It also includes some more customer-specific questions which may be helpful for institutions who would like to see what others may be asking about.

Open

NOTE: Notch8 is always looking for feedback and additional questions to add to this document.  If you have anything to add, please contact support@notch8.com, or find us on Samvera Slack!

2. Comprehensive Q&A

2.1. Core Architecture & Platform Concepts

2.1.1. Hyku vs. Hyrax vs. Hydra/Samvera

• Samvera Foundation (formerly Hydra) is the community/organization

• Hyrax is the underlying engine/framework

• Hyku is the application built on Hyrax with additional features

  • Hyku is a superset of Hyrax - all Hyrax features are included in Hyku, plus multi-tenancy and other features

• When to use Hyrax: Only if you have highly specialized needs, dedicated development resources for the foreseeable future (and can retain these resources for the foreseeable future), and need complete control to customize and potentially diverge from Samvera community direction and support.

2.1.2. Multi-Tenancy

Q: Is it reasonable to use separate tenants for different content collections?
A: Yes, separate tenants work well for managing collections with different:

• Access controls and permissions

• Branding/theming

• Target audiences

• Metadata requirements

Q: Can you specify different storage for different tenants?
A: Yes, you can specify different S3 buckets (or S3-compatible storage) per tenant.

2.1.3. Work Types

Q: What's the difference between GenericWork and Image work types?
A: GenericWork can handle any content type, while Image is optimized for image content with additional metadata fields (like "extent" for representing the number of images).

Q: When should you create custom work types?
A: Create custom work types when you need specific metadata fields and behaviors not covered by existing types. Most institutions have at least one custom work type. Consider:

• How different the metadata needs are

• Whether you need to restrict certain metadata fields from certain users

• The complexity of field types (controlled vocabularies require more work)

Q: How difficult is creating a custom work type?
A: It has become easier over time but still requires code changes. The process involves:

• Generating the work type model

• Creating associated forms and views

• Defining metadata fields

• Setting up indexing

2.2. Upcoming Versions & Roadmap

Q: How can we track progress on upcoming Hyku versions?
A: Track through:

• GitHub issues in the Hyku repository

• Samvera community Slack channels

• Regular Samvera community calls and working group meetings

• Release notes when published

Q: What's in the upcoming Hyku releases?
A: Key releases include:

• v6.1: Google Analytics 4 support and other improvements (imminent release)

• v6.2: Flexible metadata support (imminent, following closely after 6.1)

• v6.3: Feature Candidates: Clover IIIF Viewer support for A/V content, Human-readable URLs, file hierarchy viewer

• v7.0: Rails upgrade to 7.x and fold in latest Hyrax

2.3. Metadata & Search Functionality

2.3.1. Flexible Metadata

Q: How will flexible metadata work in upcoming versions?
A: Flexible metadata (v6.2) allows configuring metadata fields via a YAML file, making it easier to customize work types without coding.

Q: How will authority-controlled vocabularies be managed?
A: Authority-controlled vocabulary support is in development now and will enable mapping subject fields across different work types.

2.3.2. Search Capabilities

Q: Does Hyku support full-text search within PDFs?
A: Yes, Hyku uses Blacklight+Solr for search functionality and can perform full-text search of PDFs. It also highlights search terms and take users to the correct page in the PDF.

Q: How do facets work in Hyku?
A: Contrary to some assumptions, faceted search is built into Hyku through the Blacklight gem. In the current version, which fields get faceted requires code configuration, but the upcoming flexible metadata feature should make this configurable without code.

Q: What search features are available?
A: Hyku includes:

• Faceted search with dynamic updating

• Advanced search with boolean operators

• Field-specific searching

• Cross-collection searching

• Date range slider

2.4. Content Display & Management

2.4.1. Viewers

Q: What's the difference between PDF.js and Universal Viewer (UV)?
A:

• PDF.js: Specifically for PDF rendering, like opening a PDF in your browser

• Universal Viewer (UV): More comprehensive, supports multiple content types (images, PDFs, audio, video) and integrates with IIIF

• Clover IIIF Viewer for A/V content: Notch8 is targeting the integration of Clover for a future release. Project sponsors are welcome!

2.4.2. IIIF Support

Q: Does Hyku support IIIF?
A: Yes, Hyku supports IIIF out of the box when Universal Viewer is selected as the default viewer.

Q: How are IIIF manifests accessed?
A: IIIF manifests are accessible by appending "/manifest" to a work's URL. Adding a UI element to expose this link requires customization (not difficult but not built-in).

Q: Does Hyku support IIIF for collections?
A: Currently no, but this would be a relatively simple enhancement.

2.4.3. Multi-File Items

Q: How are multi-file items handled?
A: Works can have multiple files attached through a parent-child relationship. To end users, these relationships appear as a unified item with multiple viewable/downloadable components. The viewing experience depends on the viewer configuration.

Q: Can users navigate multi-file items seamlessly?
A: Yes, with Universal Viewer, navigation between files in the same work is continuous with next/previous controls, providing a seamless experience for multi-page documents or collections of images.

2.5. Import/Export & Data Management

2.5.1. Bulk Import

Q: How does Bulkrax work?
A: Bulkrax is enabled by default in Hyku. It appears as "Importers" and "Exporters" in the admin dashboard and supports various import formats:

• CSV with metadata and file paths

• XML imports

• OAI-PMH harvesting

Q: How resilient is the importer?
A: Bulkrax is quite resilient:

• Each record import is isolated, so successful records will still import even if others fail

• Failed imports are tracked with error messages

• You can export just the failed records to fix and re-import

• Worker processes handle the background jobs for file processing

Q: Is the "batch upload" feature useful?
A: The batch upload toggle in admin settings has largely been replaced by Bulkrax functionality and may not work reliably.

2.5.2. Research Data Management

Q: What research data management functionality does Hyku have?
A: Out of the box, Hyku offers basic functionality:

• Support for dataset work types

• File versioning

• Access controls and embargoes

• Customizable metadata

• Per-tenant storage configuration

Hyku lacks specialized features like:

• Data visualization tools

• Advanced dataset-specific metadata validation

• Integrated data analysis capabilities

Large file handling (>1GB) may need additional configuration (e.g. globus endpoint configurations), but is relatively straightforward.

2.6. Deployment & Technical Considerations

2.6.1. Storage Configuration

Q: Can Hyku use S3-compatible storage that isn't AWS S3?
A: Yes, any S3-compatible storage (MinIO, Wasabi, etc.) can be used with minimal configuration changes to endpoint URLs and authentication settings.

2.6.2. Performance

Q: What are the performance limitations of Hyku?
A: No specific record count limitations have been observed in production environments. Factors affecting performance include:

• Server resources and bot defense

• Storage configuration

• Index optimization

• Number of concurrent users/bot traffic

• Size and type of files

Solr (which is Java-based) tends to be the most resource-intensive component.

2.6.3. Long-term Preservation

Q: How does Hyku support long-term data preservation?
A: Hyku includes:

• Checksum creation and verification for uploaded files

• File characterization (identifying file types and extracting technical metadata)

• Version control for files

For more robust preservation, integration with specialized tools like Archivematica is possible.

2.7. Customization & Theming

2.7.1. Theming

Q: How easy is it to customize the appearance of Hyku?
A: Basic customizations are straightforward:

• Upload logo in admin panel

• Set banner images

• Apply CSS overrides through the admin interface

• Choose from available themes

More extensive HTML modifications are possible but not recommended without strong Ruby/Rails expertise, as they can complicate upgrades.

2.7.2. Hyku Knapsack

Q: What is Hyku Knapsack and is it still relevant?
A: Hyku Knapsack is still relevant and recommended for new Hyku instances. It adds a layer where Hyku is treated as a submodule, allowing you to:

• Override Hyku features without modifying Hyku's code

• Upgrade Hyku more easily by updating the submodule

• Maintain your customizations separately from the core application

This presentation contains some additional information

2.8. Analytics & Reporting

Q: What analytics are available in Hyku?
A: Hyku includes:

• Basic usage statistics in the admin dashboard

• Google Analytics (GA4) integration

• Optional Hyrax Analytics module for more detailed statistics

Q: How do web statistics work with bot traffic?
A: Bot traffic is a significant concern for academic repositories currently. Analytics tools attempt to filter this traffic, but it remains a challenge.

2.9. Accessibility

Q: What is the state of Hyku web accessibility?
A: Hyku includes:

• Semantic HTML markup

• ARIA attributes

• Keyboard navigation support

• Screen reader compatibility

The last full audit was a couple of years ago, but a new accessibility working group was established in February 2025 to address ongoing requirements. See this page for further details.

2.10. Repository Integrations

Q: How can Hyku integrate with Avalon Media System?
A: Options include:

1. Embedded iframes using Avalon's embed codes

2. API integration with custom UI elements

3. Metadata linking to Avalon resources

The simplest approach is embedding iframes, which requires minimal development.

Q: Can Hyku support OAI-PMH for metadata harvesting?
A: Yes, Hyku provides an OAI-PMH feed by default without requiring configuration. The feed respects authentication settings, so private records remain protected.