Revision as of 23:25, 17 May 2008

Umlaut First-Time Setup and Configuration

In all these instructions $Umlaut in a path stands for the location you have installed Umlaut.

Note: Having Rails 2 installed may cause the following rake tasks to fail.

1. Create Local Config Directories

To create directories for your local config, cd into your Umlaut directory, and run:

rake umlaut_lcl:generate

This will create several directories including the one we care about now: $Umlaut/config/umlaut_config/

Explanation: In a normal Rails app, your local config goes in places like config/environment.rb and config/database.yml. But Umlaut config/environment.rb has Umlaut application fixed settings in it, mixing in your local settings would be confusing. Plus, that config directory is in the Umlaut overall SVN, you might want to SVN control your local config seperately.

Therefore we have an architecture to put all local config (and other local customization) in seperate local directories. The goal is that you should never have to edit any of the files that came with the Umlaut distribution to make local customizations, you should always be able to do this through local config. To learn more about this architecture, and how to put your local config in your own local svn, see [Main.Local Configuration Architecture].

2. Configure your database connection information

A typical Rails app uses three databases: a production db, a development db, and a test db. At a minimum you need a production db. A development db is probably also neccessary--Umlaut doesn't use tests right now (we are ashamed), so you don't really need a test db.

In Umlaut (a little bit different than standard Rails), your local connection information for your dbs is stored in $Umlaut/config/umlaut_config/database.yml. There should already be an example file there with some hints in it.

We reccommend MySQL for use with Umlaut. ( SQLite3 won't work, unless you figure out a way to compile it with concurrency support). Create your databases in MySQL. We recommend making sure they are set to UTF8 char encoding. (eg, (CREATE DATABASE 'Name' DATABASE DEFAULT CHARACTER SET utf8). Don't create any tables in your databases yet, that will be done automatically. Do fill out your umlaut_config/database.yml file to point at the right place.

For some functions Umlaut can take advantage of a direct db connection to your SFX instance. We reccommend this for maximum functionality, but it's not required. If you have control of your SFX instance and would like to enable this, you should use the MySQL utility to create a new user in the SFX MySQL instance, which is granted only select permissions to the SFX databases. Then, you can fill out your SFX direct to db connection information in config/umlaut_config/database.yml. If you can't do this, or don't want to do this now, Umlaut should still (mostly) work.

3. Create your database tables

Once your dbs are configured in database.yml, you can have Rails create all the neccesary tables for you by running:

rake db:migrate

That will create tables in your development database. To create them in your production database too:

rake db:migrate RAILS_ENV=production

4. Set up initial Umlaut data

Now you've created your databases and tables, but there is some initial fixed data that need to be in those tables for Umlaut to work with. To add this to your database, cd into your $UMLAUT directory, and run:

rake umlaut:load_initial_data

And again for production:

rake umlaut:load_initial_data RAILS_ENV=production

5. Set up your Institutions and Services

What functions your Umlaut installation will have will depend on which services you configure. Services are configured in $Umlaut/config/umlaut_config/services.yml . An individual user connects with given services by association to Institutions. Each Institution has a collection of services, and an individual user is associated with one more institutions.

To begin with, you could define just one default institution (that all users will be associated with) in institutions.yml, and give it a few services. To start out with, just configure an SFX service pointing to your SFX installation. Comment out the others. As you know a service is working, you can add in another.

Note: The A-Z list and journal name lookup will only currently work if using the direct connection to the SFX database.

After editing the institutions.yml file, it needs to be synced with the db, as some institution information is stored in the db. Umlaut should check on startup if timestamp of institutions.yml requires a resync and do it automatially, but if you want to do it manually you can run cd into the $UMLAUT directory and run:

rake umlaut:sync_institutions (RAILS_ENV=production)

This command ensures the db information is synced with the institutions.yml information.

6. Review additional local configuration

If you look in $Umlaut/config/umlaut_config/environment.rb, you will find some comments showing you some more configuration parameters you may want to set. None of them need to be set now, but it would be wise to review them and set obvious ones, like the name you would like to call your service (eg Find It), and the URL to an icon for a button to your service.

7. Nightly maintenance

Some maintenance routines meant to be run nightly can be executed by cd'ing to your $Umlaut directory and running:

rake umlaut:nightly_maintenance (RAILS_ENV=production)

To put that in a cron job, use this (with parens, where $Umlaut represents your umlaut install directory as usual):

( cd $Umlaut && /usr/bin/rake umlaut:nightly_maintenance RAILS_ENV=production )

Or leave the RAILS_ENV=production off to perform maintainance on your dev database.

If you don't put it in a cron job yet, you might want to run this manually from time to time, and probably once now to begin.

Next Steps?

To try out Umlaut, cd into the $Umlaut directory and run "./script/server" to launch the Rails app. (Be sure you've installed mongrel with 'sudo gem install mongrel', in which case Umlaut will be started with the mongrel environment. The default WEBrick environment will not work for Umlaut!). You'll then connect to Umlaut on http://yourservername.tld:3000 . The resolver base URL will be: http://yourservername.tld:3000/resolve?.

The A-Z search interface will be http://yourservername.tld:3000/search

This is a fine way to start it just for testing, but to deploy it for real see Umlaut Deployment.

You may also be interested in providing your own customized header, footer, or stylesheets. For this, and more localization, you'll find it helpful to see Umlaut Local Configuration Architecture.