Child pages
  • Installing Sufia From Scratch
Skip to end of metadata
Go to start of metadata

On this page, I will document the step-by-step process of getting a default, out-of-the-box installation of Sufia with Fedora 4 up and running with minimal fuss. In the end, we end up with a fully functional, out-of-the-box version of Sufia for testing.

This setup is pretty generic, but is customized in a few ways to match our specific needs here at IU. Other implementations may vary in some details. A few notes about our particular setup:

  • Uses the most recent version of Sufia which will also use Fedora 4 underneath.
  • Changes the default port that hydra-jetty runs on. This is because we have multiple applications running on the same server.
  • Uses a local version of the Sufia gem, so that we can run tests and possibly customize Sufia gem code if needed.
  • Uses RVM for gem management, and creates a separate custom gemset to keep our gems separate from other applications.
  • Uses thin because we need an https URL.

IMPORTANT NOTE! These steps do not create a production installation — we use hydra-jetty, which creates an easy to use version of Fedora 4, that is also completely insecure. This is for testing purposes only.


First off, we need to confirm that we have installed a few prerequisite applications before we even get to Ruby:

  • ImageMagick - we can confirm that it is installed properly by typing

    convert -version
  • Redis - confirm with

    redis-cli ping
  • phantom.js (for running tests) - confirm with

    phantomjs -v
  • FFmpeg - confirm with

    ffmpeg -version

Configure Ruby

To set up Ruby, we first install RVM, then ensure we are at the latest version:

rvm get stable

Then download and install the appropriate ruby:

rvm install 2.1.5

Next create and configure a new gemset:

rvm gemset create sufia6-dev
rvm use ruby-2.1.5@sufia6-dev

Get some basic gems installed:

gem install rails --no-ri -v 4.1.8
gem install thin

Initialize Application Directory

In this step, we create a directory to hold our application, and set it up with a basic rails application. First, create the directory and a generic rails application:

mkdir sufia6dev
cd sufia6dev
rails new .

Next, add some files to tell RVM which gemset to use for this application. This helps prevent problems with using the wrong gemset when working with this application.

touch .ruby-version
vi .ruby-version [... insert "2.1.5" into file ...]
touch .ruby-gemset
vi .ruby-gemset [... insert "sufia6-dev" into file ...] 

Check Out Sufia Gem

Next, we will check out the Sufia gem locally, and place it inside a sub-directory in the application.

mkdir sufia-gem
cd sufia-gem
git clone 
cd ../

Edit Gemfile (not needed for most installations)

For our IU environment, the Gemfile inside the Sufia gem doesn't work because the RAILS_VERSION environment variable isn't set correctly. So I had to manually change the Gemfile as follows. For most other installs this step can probably be skipped.

file = File.expand_path("Gemfile", ENV['ENGINE_CART_DESTINATION'] || ENV['RAILS_ROOT'] || File.expand_path("../spec/internal", __FILE__))
if File.exists?(file)
  puts "Loading #{file} ..." if $DEBUG # `ruby -d` or `bundle -v`
  gem 'rails', "4.1.8"
  gem 'sass-rails', "< 5.0"
  #if ENV['RAILS_VERSION'] and ENV['RAILS_VERSION'] =~ /^4.2/
  #  gem 'responders', "~> 2.0"
  #  gem 'sass-rails', ">= 5.0"
  #  gem 'sass-rails', "< 5.0"

Run Gem Spec Tests

In this step, we initialize the Sufia gem and run the spec tests to ensure everything is working properly before moving on. NOTE: Even though we will specify another port for the application to run on later on, for now these tests will use the default 8983 port, so we need to make sure that port is open before running these tests. Any failures at this point should be fixed before moving on. (There may be minor failures around external services such as FFmpeg that might be ignored depending on your particular setup and needs).

cd sufia-gem/sufia
bundle install
bundle exec rake jetty:clean
bundle exec rake sufia:jetty:config
bundle exec rake engine_cart:clean
bundle exec rake engine_cart:generate
bundle exec rake jetty:start
bundle exec rspec [... wait for tests to finish ...]
bundle exec rake jetty:stop
rm -Rf spec/internal
rm -Rf jetty
cd ../../

Generate Application

In this step, we generate and configure the application. First, we

vi Gemfile

and add the following near the beginning

gem 'sufia', :path => "/path/to/sufia6dev/sufia-gem/sufia"
gem 'kaminari', github: 'harai/kaminari', branch: 'route_prefix_prototype'
gem 'thin'

Then generate everything else:

bundle install
rails generate sufia:install -f 
rake db:migrate

Change default port

For our configuration we wanted a port other than the default 8983 since we are in a shared environment. For other setups this step can probably be skipped. Inside the config folder, I simply edited fedora.yml, jetty.yml, and solr.yml, changing all references to port 8983 to port 8990.

Install Hydra-Jetty

This step downloads and configures hydra-jetty to run inside our application folder.

rake jetty:clean
rake sufia:jetty:config

Due to our port change, I also had to alter a couple of files inside the jetty folder (solr/development-core/conf/scripts.conf and etc/jetty.xml) to change port 8983 to port 8990.

Bring Up Application Services

First, start the resque workers. (This assumes Redis itself is already running.)

resque-pool --daemon --environment development start

Then start jetty.

rake jetty:start

Before moving on, it's helpful at this point to confirm that jetty started up properly. Go to http://{SYSTEMURL}:{PORT}/solr and http://{SYSTEMURL}:{PORT}/fedora and make sure they resolve to something. (For example: http://localhost:8983/solr)

Bring Up Sufia

thin start --ssl -d -p 8515 -e development

This is for our purposes — using Thin so we get SSL. If you don't have these requirements you can probably use the regular rails server command.

At this point, you should be able to navigate to the server and port that you configured, and Sufia is up and running!

Shutting Things Down

thin stop
rake jetty:stop
kill the pid in tmp/pids/

Resetting the Application

If you want to erase all data and start over without altering any code, from the application directory:

rm -Rf jetty
rake db:reset
rake jetty:clean
rake sufia:jetty:config
[change port numbers if needed]
  • No labels