Code:

Docs:

Jump in:

Table of Contents

• What is Sufia?
  • Feature list
• Help
• Getting started
  • Prerequisites
    • Characterization
    • Derivatives
  • Environments
  • Ruby
  • Redis
  • Rails
• Creating a Sufia-based app
  • Generate a primary work type
  • Start servers
  • Add Default Admin Set
• Managing a Sufia-based app
• License
• Contributing
• Development
• Release process
• Acknowledgments

What is Sufia?

Sufia uses the full power of Samvera 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 many features. Read more about what they are and how to turn them on. See the Sufia Management Guide to learn more.

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

Help

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

Getting started

This document contains instructions specific to setting up an app with Sufia v7.4.1. 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:

• If you would like to create a new application using Sufia follow the instructions for Creating a Sufia-based app.
• If you would like to create new features for Sufia follow the instructions for Contributing and Development.

Prerequisites

Sufia 7 requires the following software to work:

1. Solr version >= 5.x (tested up to 6.4.1)
2. Fedora Commons digital repository version >= 4.5.1 (tested up to 4.7.1)
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.

Characterization

1. Go to http://projects.iq.harvard.edu/fits/downloads and download a copy of FITS (see above to pick a known working version) & unpack it somewhere on your machine.
2. Mark fits.sh as executable: chmod a+x fits.sh
3. Run fits.sh -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 fits.sh 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>/fits.sh"

Derivatives

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 LibreOffice.app. Your path may look like "//LibreOffice.app/Contents/MacOS/"

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.

Environments

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.

Ruby

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.

Redis

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.

Rails

We recommend the latest Rails 5.0 release.

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

Creating a Sufia-based app

Generate a new Rails application using the template.

rails new my_app -m https://raw.githubusercontent.com/samvera/sufia/master/template.rb

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
• Loading Sufia's default workflows into your application's database

Generate a work type

While earlier versions of Sufia came with a pre-defined object model, Sufia 7 allows you to generate an arbitrary number of work types. Let's start by generating one.

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

rails generate sufia:work Work

or

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.

Add Default Admin Set

After Fedora and Solr are running, create the default administrative set by running the following rake task:

rake sufia:default_admin_set:create

You will want to run this command the first time this code is deployed to a new environment as well. Note it depends on loading workflows, which is run by the install template but also needs to be run in a new environment:

rake curation_concerns:workflow:load

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

License

Sufia is available under the Apache 2.0 license.

Contributing

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.

• Contribute a user story.
• Help us improve Sufia's test coverage or documentation coverage.
• Refactor away code smells.

Development

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.

Acknowledgments

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

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