Table of Contents
- What is Sufia?
- Help
- Getting started
- Creating a Sufia-based app
- Managing a Sufia-based app
- License
- Contributing
- Development
- Release process
- Acknowledgments
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
- Schema.org 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.
Help
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:
- 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.x requires the following software to work:
- Solr version >= 5.x (tested up to 6.2.0)
- Fedora Commons digital repository version >= 4.5.1 (tested up to 4.6.0)
- A SQL RDBMS (MySQL, PostgreSQL), though note that SQLite will be used by default if you're looking to get up and running quickly
- Redis, a key-value store
- ImageMagick with JPEG-2000 support
- FITS version 0.8.x (0.8.5 is known to be good)
- LibreOffice
NOTE: If you do not already have Solr and Fedora instances you can use in your development environment, you may use hydra-jetty (instructions are provided below to get you up and running quickly and with minimal hassle).
Characterization
- 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.
- Mark fits.sh as executable:
chmod a+x fits.sh
- Run
fits.sh -h
from the command line and see a help message to ensure FITS is properly installed - Give your Sufia app access to FITS by:
- Adding the full fits.sh path to your PATH (e.g., in your .bash_profile), OR
- 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 "/
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.
Creating a Sufia-based app
Rails
Generate a new Rails application. We recommend the latest Rails 5.0 or 4.2 release.
gem install rails -v 5.0.0.1
rails new my_app
Sufia's Ruby-related dependencies
Add the following lines to your application's Gemfile.
gem 'sufia', '7.2.0'
Then install Sufia as a dependency of your app via bundle install
Install Sufia
Install Sufia into your app using its built-in install generator. This step adds a number of files that Sufia requires within your Rails app, including e.g. a number of database migrations.
rails generate sufia:install -f
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
or
rails generate sufia:work MovingImage
Database tables and indexes
Now that Sufia's required database migrations have been generated into your app, you'll need to load them into your application's database.
rake db:migrate
Start 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.
Start Solr
If you already have an instance of Solr that you would like to use, you may skip this step. Open a new terminal window and type:
solr_wrapper -d solr/config/ --collection_name hydra-development
You can check to see if Solr is started by going to localhost:8983.
Start FCRepo
If you already have an instance of FCRepo that you would like to use, you may skip this step. Open a new terminal window and type:
fcrepo_wrapper -p 8984
You can check to see if FCRepo is started by going to localhost:8984.
Spin up the web server
To test-drive your new Sufia application, spin up the web server that Rails provides:
rails 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
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 Hydra community. Learn more at the Project Hydra website.
The Sufia logo uses the Hong Kong Hustle font, thanks to Iconian's non-commercial use policy.