-
Notifications
You must be signed in to change notification settings - Fork 24
Installation
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.
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.
-
Umlaut is developed for unix/linux, it is unlikely to work on a Windows server.
-
Your system needs ruby installed -- while Umlaut will work with ruby 1.9.3+, ruby 1.9 is approaching end of life and we recommend starting with ruby 2.0 or 2.1. We have had good experiences with chruby for managing ruby installs different from that that comes with your system, and ruby-build for compiling them (instructions on chruby page).
-
After installing a new ruby, it's a good idea 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).
Install the umlaut gem:
$ gem install umlaut
Umlaut comes with an application generator which will install a Rails app with Umlaut installed into it. Just run:
$ umlaut name_of_my_app
cd name_of_my_app into your newly created blank Rails app, for further configuration.
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:migrateto create umlaut's schema in your database.
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.rbhowever. - 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
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?sid=FirstSearch%3AWorldCat&genre=book&title=Fairy+tales&date=1898&aulast=Andersen&aufirst=H&auinitm=C&rfr_id=info%3Asid%2Ffirstsearch.oclc.org%3AWorldCat&rft.genre=book&rft_id=info%3Aoclcnum%2F7675437&rft.aulast=Andersen&rft.aufirst=H&rft.auinitm=C&rft.btitle=Fairy+tales&rft.date=1898&rft.place=Philadelphia&rft.pub=H.+Altemus+Co.&rft.genre=book
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.
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_maintenanceFuture 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.
To upgrade your local app to use the latest patch version of Umlaut, simply run:
$ bundle update umlautIf a new major version of Umlaut is out, you may need to adjust your version specification in your Gemfile.
We recommend locking umlaut dependency to version constraints in your Gemfile locked to major version, eg "~> 4.0" allowing any 4.x but not 5.0.
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:migrateOr 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.