Skip to content
This repository

Umlaut is a ruby gem (re-useable library) that functions as a Rails engine.

This guide includes as an audience people newish to ruby. Installation and Getting Started.

Umlaut is an engine gem

This means that you will have a local Rails app unique to you, and that app will use the Umlaut gem to provide Umlaut functionality. In basic cases, there won't be much actually in your local app other than some configuration, and perhaps a few over-rides of Umlaut functionality. Umlaut is a pretty heavy weight gem, trying to use it in an existing app that does a whole lot of non-Umlaut related stuff may or may not work and is probably for advanced users. It's distributed as a gem mainly to allow you to keep local overrides and customizations seperate from the shared Umlaut distro, and allow you to easily upgrade to future versions of Umlaut within your local app.

Pre-requisites (for the ruby neophyte)

  • Umlaut is developed for unix/linux, it is unlikely to work on a Windows server.

  • Your system needs ruby installed -- ruby 1.9.3 is recommended, but it works under 1.8.7 too. rvm is one easy way to install ruby. Some people prefer rbenv these days.

  • You will need 'rubygems' installed; 1.9.x should come with rubygems, for 1.8.7 you may need to install it seperate. After installing (or if it came with your installation), you probably want to ensure you have an up-to-date rubygems utility by running sudo gem update --system

  • Umlaut is developed for mysql. It may work with other databases, but Umlaut's use of threaded concurrency causes problems with some ruby database adapter code not written for concurrency. mysql seems to be working. The 'sqlite3' database probably won't work, even under development -- sqlite3 via ruby does not tolerate threaded concurrency well (or it may depend on how sqlite3 or it's ruby adapter were compiled, but I haven't had much luck with it).

Here are some instructions from someone else you may find useful in getting ruby and rails installed on a new machine. However, I disagree with their advise to use rvm 'gemsets' feature, it should not be neccessary.

Install

Install the rails gem (rails 3.1+ required). Create a new empty rails app using mysql database setup template. Name it anything you like, but do not name it umlaut, that name will end up conflicting with the umlaut gem.

    $ gem install rails
        # 'sudo' in front of 'gem install rails' may be needed for a non-rvm install of ruby
    $ rails new my_app_name -d mysql

cd my_app_name into your newly created blank Rails app, all further commands will be from there.

You need to delete the default static front page Rails generates, because it gets in the way:

    $ rm public/index.html

Edit the './Gemfile' in your new app to include Umlaut

# inside ./Gemfile
gem "umlaut"

On Linux, you also need to add a Javascript runtime gem to your Gemfile. (Rails 3.1 asset pipeline feature needs a JS runtime. On Windows or OSX, Rails can usually find an OS-provided one. On Linux, you usually need to add one, therubyracer is a popular way to do it. Oddly, you seem to need the JS runtime even to run generators, as in the Umlaut install generator in the next step).

# inside ./Gemfile
gem 'therubyracer'

Now install your all the dependencies newly listed in your Gemfile (including Umlaut) with bundler:

    $ cd my_app_name
    $ bundle install

Now run the install 'generator' script built into Umlaut. This script will add a couple files to your app, as well as make some modifications to several files that were already there in your empty rails app. If you want to see exactly what it does, consider adding your blank app to a source control repo before running the install generator, then you can diff!

    # still with working directory my_app_name
    $ rails generate umlaut:install

You now have a basic Umlaut installed, but you'll need to at least set up a database, and may want to configure more.

Initial Configuration

database

In your app, there is a ./config/database.yml. This standard file for Rails apps sets your database connection details.

Use of a mysql database with the 'mysql2' adapter is strongly encouraged for Umlaut. The Umlaut install generator gives you a template in config/database.yml. You'll want to create an empty mysql database somewhere, and then set up the connection details in config/database.yml -- to begin with, only connection details for the 'development' environment are needed. (You may be able to create the db simply by running rake db:create after setting host and credentials in database.yml. If your credentials have privileges to create new dbs on your mysql instance)

Then, from the app root directory, run:

    $ rake db:migrate

to create umlaut's schema in your database.

config

The out of the box Umlaut should now start up (although it won't do too much), but here are where you'd start with configuration for your local app:

  • The main meat of Umlaut configuration is which service plugins are enabled for your Umlaut installation. This is configured in the file ./config/umlaut_services.yml; the install generator gave you a sample. Many of the plugins require either local connection details (eg, base url for your SFX), or private api keys (eg for Amazon and Google). Templates for configuring such service plugins are there for you, but they are initially disabled. There are only a few services that actually can work out of the box without any local configuration, but a few of these are initially turned on for you.

  • There is a bit more configuration you can do of local application name and some other values. In your local app, the Umlaut install generator added a ./app/controllers/umlaut_controller.rb. Some configuration can be done here, there are commented-out samples waiting for you.

  • For 'search' (A-Z list) behavior, you need a direct MySQL connection to the SFX database.

    • This is set up in config/database.yml, the generator left hints for you.
    • At present, 'search' functions are only supported by direct connection to SFX db. Other methods may be provided later.
    • SFX4 is default, if you have SFX3 you can tell Umlaut that in ./app/controllers/umlaut_controller.rb however.
    • It is strongly recommended you manually create a new MySQL account in the SFX MySQL db, one with read-only permissions. It's not a good idea to use one of the existing standard SFX instance MySQL accounts, as they have write-permissions too.
    • You can still use the main part of Umlaut without an SFX database connection, just not 'search'/A-Z functionality.

See also Customizing

Starting the app

You can now start your local Umlaut app in the standard Rails way by executing, from the app's directory:

    $ rails server [-p port]

This is not the way you'd deploy an Umlaut app in production, but serves to test things out and ensure the app is working. See Production Deployment.

Here's an openurl which will (at the time of this writing) give you some results (from Internet Archive, and WorldCat Identities) even with out of the box Umlaut install without edits to default umlaut_services.yml.

http://yourserver:3000/resolve?genre=book&title=Fairy%20Tales&au=Andersen

Note that Umlaut's link resolver action is mounted at /resolve. By default the '/' path on Umlaut is the 'search' function, if you are not using the search function you could change this to redirect somewhere else or something perhaps.

Nightly maintenance

Umlaut provides a rake task to perform some regular maintenance, mainly cleaning old data out of the database. Recommended you run this nightly, you can put it into a cronjob like this (yes, it requires the 'cd' I'm afraid):

    cd /path/to/your/umlaut_app && rake umlaut:nightly_maintenance

Future versions of Umlaut may change what happens in nightly maintenance, but this will still be the right command, you won't have to touch it. (source code)

No downtime or interruption to users are intended to occur during nightly_maintenance task, should be safe to run any time. Try running it yourself manually to see what it does, it outputs info about what it's doing as it goes.

Upgrading/Updating Umlaut

(For upgrading from Umlaut 2.x to 3.0, see Upgrading From Umlaut 2.x)

To upgrade your local app to use the latest version of Umlaut, simply run:

    $ bundle update umlaut

Assuming your Gemfile listed umlaut as a dependency with no version constraints, your local Gemfile.lock will be updated to the latest umlaut release, and your app will use that. (You may also want to lock umlaut dependency to version constraints in your Gemfile instead, to require explicit changes to Gemfile before bundle update will install an arbitrary latest release)

Okay, now your app is using the latest version of Umlaut, but what if the new version of Umlaut needs changes to your database, or other changes in your local file?

To install any new Umlaut database migrations in your local app and then run them, after updating to a new version of Umlaut, run:

    $ rails generate umlaut:install --only migrations
    $ rake db:migrate

Or you can re-run the entire umlaut:install generator for the new version, to see if there's anything else the new version of Umlaut suggests for your local app. The umlaut:install generator is intended to be re-runnable multiple times, but may have some bugs there; to be safe, best if you have your local app in source control of some kind, run the generator then look at the diff to see what it changed, keeping or discarding changes as seem appropriate.

    $ rails generate umlaut:install

(This may install new migrations too, so rake db:migrate after the full umlaut:install may be called for).

In general, aside from migrations, Umlaut will try not to require changes in your local app for new versions. Of course, if you've written extensive local modifications or local code that integrates with Umlaut, it's possible a new version will break it, and the umlaut:install generator won't neccesarily alert you to that, you'll just have to test.

Something went wrong with that request. Please try again.