Sufia: a fully featured, flexible Hydra repository front-end.
Ruby HTML JavaScript CSS XSLT CoffeeScript
Latest commit fe71a58 Dec 2, 2016 @mjgiarlo mjgiarlo committed on GitHub Merge pull request #2955 from projecthydra/speed_up_feature_specs_and…

Speed up feature specs and nuke the travis timeout
Failed to load latest commit information.
.github Create GitHub templates for issues and PRs Feb 18, 2016
app Merge pull request #2944 from projecthydra/single-step-with-depositor… Dec 1, 2016
config Remove enable_mediated_deposit feature flipper. Dec 1, 2016
db/migrate Add Release form to AdminSet editing Nov 23, 2016
lib add notion of 'depositor review' to one step mediated deposit workflow Dec 1, 2016
solr/config Add solrconfig.xml from AF to Sufia Aug 12, 2016
spec Merge pull request #2955 from projecthydra/speed_up_feature_specs_and… Dec 2, 2016
tasks Add a rake task for importing languages Sep 12, 2016
vendor/assets Replace addthis sharing buttons with icons Aug 23, 2016
.codeclimate.yml Search for a user on the AdminSet participants form Nov 10, 2016
.engine_cart.yml Add --skip-listen for Rails 5-based builds to avoid problems with our… Aug 25, 2016
.eslintignore Add config files to have greater control over Code Climate analysis Aug 16, 2016
.eslintrc Add config files to have greater control over Code Climate analysis Aug 16, 2016
.gitignore Remove extraneous `puts` statements from specs. Sep 12, 2016
.hound.yml Add scss-lint config and point Hound at it Sep 7, 2016
.rspec DRY up require 'spec_helper' from tests May 25, 2016
.rubocop.yml Switch to do/end for multiline block Sep 27, 2016
.rubocop_todo.yml Remove dead code (EndnoteFormatter) Nov 28, 2016
.scss-lint.yml Add scss-lint config and point Hound at it Sep 7, 2016
.travis.yml Fix for using sufia with curation_concerns 1.7.0.alpha Nov 2, 2016
Gemfile Add pry and pry-byebug as development dependencies Oct 13, 2016
LICENSE Update and rename to LICENSE per community convention. Jan 6, 2015 Bumping tested versions Dec 2, 2016
Rakefile Import jasmine rake tasks Apr 2, 2016
sufia.gemspec Use a released version of CC to make the build work Nov 16, 2016
template.rb Add an installation template to simplify installation process Oct 12, 2016


Code: Version Build Status Coverage Status Code Climate Dependency Update Status Dependency Maintenance Status

Docs: Documentation Status API Docs Contribution Guidelines Apache 2.0 License

Jump in: Slack Status Ready Tickets

Table of Contents

What is Sufia?

Sufia uses the full power of Hydra and extends it to provide a user interface around common repository features and social features (see below). Sufia offers self-deposit and proxy deposit workflows, and mediated deposit workflows are being developed in a community sprint running from September-December 2016. Sufia delivers its rich and growing set of features via a modern, responsive user interface. It is implemented as a Rails engine, so it is meant to be added to existing Rails apps.

Feature list

Sufia has the following features:

  • Multiple file upload, and folder uploads (for Chrome browser only)
  • Flexible user- and group-based access controls
  • Transcoding of audio and video files
  • Generation and validation of identifiers
  • Generation of derivatives (served from the filesystem, not the repository)
  • Fixity checking
  • Version control
  • Characterization of uploaded files
  • Forms for batch editing metadata
  • Faceted search and browse
  • Social media interaction
  • User profiles
  • User dashboard for file management
  • Highlighted files on profile
  • Sharing w/ groups and users
  • User notifications
  • Activity streams
  • Background jobs
  • Single-use links
  • Google Analytics for usage statistics
  • Integration w/ cloud storage providers
  • Google Scholar-specific metadata embedding
  • microdata, Open Graph meta tags, and Twitter cards for rich snippets
  • User-managed collections for grouping files
  • Full-text indexing & searching
  • Responsive, fluid, Bootstrap 3-based UI
  • Dynamically configurable featured works and researchers on homepage
  • Proxy deposit and transfers of ownership
  • Integration with Zotero for automatic population of user content
  • Suggested values from controlled vocabularies provided by Questioning Authority
  • ResourceSync capability lists and resource lists
  • Administrative sets (curated collections)
  • Administrative dashboard, w/ feature flippers to turn features on and off in the UI
  • Contact form
  • Customizable banner image
  • Flexible object model: upload and manage single-file works, multi-file works, zero-file works, and works-within-works
  • Geonames integration for location-oriented metadata fields
  • Virus detection for uploaded files
  • Citation formatting suggestions

See the Sufia Management Guide to learn which features listed above are turned on by default and which require configuration.

For non-technical documentation about Sufia, see its documentation site.


If you have questions or need help, please email the Hydra community tech list or stop by the #dev channel in the Hydra community Slack team.

Getting started

This document contains instructions specific to setting up an app with Sufia v7.2.0. If you are looking for instructions on installing a different version, be sure to select the appropriate branch or tag from the drop-down menu above.

Prerequisites are required for both Creating a Sufia-based app and Contributing new features to Sufia. After installing the Prerequisites:


Sufia 7.x requires the following software to work:

  1. Solr version >= 5.x (tested up to 6.3.0)
  2. Fedora Commons digital repository version >= 4.5.1 (tested up to 4.7.0)
  3. A SQL RDBMS (MySQL, PostgreSQL), though note that SQLite will be used by default if you're looking to get up and running quickly
  4. Redis, a key-value store
  5. ImageMagick with JPEG-2000 support
  6. FITS version 0.8.x (0.8.5 is known to be good)
  7. LibreOffice

NOTE: The Sufia Development Guide has instructions for installing Solr and Fedora in a development environment.


  1. Go to and download a copy of FITS (see above to pick a known working version) & unpack it somewhere on your machine.
  2. Mark as executable: chmod a+x
  3. Run -h from the command line and see a help message to ensure FITS is properly installed
  4. Give your Sufia app access to FITS by:
    1. Adding the full path to your PATH (e.g., in your .bash_profile), OR
    2. Changing config/initializers/sufia.rb to point to your FITS location: config.fits_path = "/<your full path>/"


Install LibreOffice. If which soffice returns a path, you're done. Otherwise, add the full path to soffice to your PATH (in your .bash_profile, for instance). On OSX, soffice is inside Your path may look like "//"

You may also require ghostscript if it does not come with your compiled version LibreOffice. brew install ghostscript should resolve the dependency on a mac.

NOTE: derivatives are served from the filesystem in Sufia 7, which is a difference from earlier versions of Sufia.


Note here that the following commands assume you're setting up Sufia in a development environment (using the Rails built-in development environment). If you're setting up a production or production-like environment, you may wish to tell Rails that by prepending RAILS_ENV=production to the commands that follow, e.g., rails, rake, bundle, and so on.


First, you'll need a working Ruby installation. You can install this via your operating system's package manager -- you are likely to get farther with OSX, Linux, or UNIX than Windows but your mileage may vary -- but we recommend using a Ruby version manager such as RVM or rbenv.

We recommend either Ruby 2.3 or the latest 2.2 version.

Creating a Sufia-based app


Redis is a key-value store that Sufia uses to provide activity streams on repository objects and users, and to prevent race conditions as a global mutex when modifying order-persisting objects.

Starting up Redis will depend on your operating system, and may in fact already be started on your system. You may want to consult the Redis documentation for help doing this.


Generate a new Rails application. We recommend the latest Rails 5.0 or 4.2 release.

# If you don't already have Rails at your disposal...
gem install rails -v
rails new my_app -m

Generating a new Rails application using Sufia's template above takes cares of a number of steps for you, including:

  • Adding Sufia (and any of its dependencies) to your application Gemfile, to declare that Sufia is a dependency of your application
  • Running bundle install, to install Sufia and its dependencies
  • Running Sufia's install generator, to add a number of files that Sufia requires within your Rails app, including e.g. database migrations
  • Loading all of Sufia's database migrations into your application's database

Generate a primary work type

While earlier versions of Sufia came with a pre-defined object model, Sufia 7.x and greater allow you to specify your primary work type by using tooling provided by the CurationConcerns gem. Work on the 7.x series will include adding support for users to generate an arbitrary number of work types, not just a primary work type. At this time we do not recommend generating multiple work types.

Pass a (CamelCased) model name to Sufia's work generator to get started, e.g.:

rails generate sufia:work Work


rails generate sufia:work MovingImage

Start servers

To test-drive your new Sufia application in development mode, spin up the servers that Sufia needs (Solr, Fedora, and Rails):

rake hydra:server

And now you should be able to browse to localhost:3000 and see the application. Note that this web server is purely for development purposes; you will want to use a more fully featured web server for production-like environments.

Managing a Sufia-based app

The Sufia Management Guide provides tips for how to manage, customize, and enhance your Sufia application, including guidance specific to:

  • Production implementations
  • Configuration of background workers
  • Integration with e.g., Dropbox, Google Analytics, and Zotero
  • Audiovisual transcoding with ffmpeg
  • Setting up administrative users
  • Metadata customization


Sufia is available under the Apache 2.0 license.


We'd love to accept your contributions. Please see our guide to contributing to Sufia.

If you'd like to help the development effort and you're not sure where to get started, you can always grab a ticket in the "Ready" column from our Waffle board. There are other ways to help, too.


The Sufia Development Guide is for people who want to modify Sufia itself, not an application that uses Sufia.

Release process

See the release management process.


This software has been developed by and is brought to you by the Hydra community. Learn more at the Project Hydra website.

Project Hydra Logo

The Sufia logo uses the Hong Kong Hustle font, thanks to Iconian's non-commercial use policy.