Code4Lib - User contributions [en]

Umlaut Setup

2010-02-09T11:36:10Z

Navtis: /* 7. Nightly maintenance */

[[Category:Umlaut]]

= Umlaut First-Time Setup and Configuration =

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

== 1. Create Local Config Directories ==

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

./script/generate umlaut_local

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

Mysql by default has no password for the root user. If you have set a root password, you will need to add this to $Umlaut/config/database.yml

:'''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 [[Umlaut 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 5.x 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 my_db_name 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 search functions (manually entered journal name or citation), Umlaut uses a direct db connection to your SFX instance. 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, talk to Jonathan, it may be possible to set up other functionality. Umlaut used to support a bulk export from SFX instead of a live db connection, but that functionality has atrophied. It can in theory be brought back if needed.

== 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 (from the Umlaut directory):

:rake db:schema:load

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

:rake db:schema:load 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.

== 6. Review additional local configuration ==

There are several files in $Umlaut/config/umlaut_config/initializers/umlaut that contain additional local configuration parameters. A bunch of examples are provided for you, you'll have to un-comment the line and set a value if you want to locally configure a particular property.

There are only a few that are really best set right away, all in umlaut_config/initializers/umlaut/umlaut_properties.rb
* You may want to set your local application name and a URL to an image for a 'link resolver button'. The button is mainly only used in Umlaut 'search' functionality (look up a manually typed in citation or journal name).
* You will definitely need to point AppConfig::Base.main_sfx_base_url to your SFX base URL. This is not used in general link resolver menu functions, but may be used in 'search' function to look up a manually typed in journal name or citation. It is also used on Umlaut's error page, to give the user an option of going to the native original SFX in an error condition.
* You may want to set AppConfig::Base.help_url , which is also used on error pages.

There's really nothing else here you need to change to get Umlaut to work properly for you, but feel free to look around in the other files in initializers to see what sorts of things you can customize (an awful lot, sometimes by writing custom logic in ruby code to determine a particular Umlaut decision.)

== 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

(should also work on straight http://yourservername.tld:3000/)

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]].

Umlaut Setup

2010-02-08T16:45:52Z

Navtis: /* 1. Create Local Config Directories */

[[Category:Umlaut]]

= Umlaut First-Time Setup and Configuration =

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

== 1. Create Local Config Directories ==

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

./script/generate umlaut_local

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

Mysql by default has no password for the root user. If you have set a root password, you will need to add this to $Umlaut/config/database.yml

:'''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 [[Umlaut 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 5.x 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 my_db_name 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 search functions (manually entered journal name or citation), Umlaut uses a direct db connection to your SFX instance. 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, talk to Jonathan, it may be possible to set up other functionality. Umlaut used to support a bulk export from SFX instead of a live db connection, but that functionality has atrophied. It can in theory be brought back if needed.

== 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 (from the Umlaut directory):

:rake db:schema:load

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

:rake db:schema:load 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.

== 6. Review additional local configuration ==

There are several files in $Umlaut/config/umlaut_config/initializers/umlaut that contain additional local configuration parameters. A bunch of examples are provided for you, you'll have to un-comment the line and set a value if you want to locally configure a particular property.

There are only a few that are really best set right away, all in umlaut_config/initializers/umlaut/umlaut_properties.rb
* You may want to set your local application name and a URL to an image for a 'link resolver button'. The button is mainly only used in Umlaut 'search' functionality (look up a manually typed in citation or journal name).
* You will definitely need to point AppConfig::Base.main_sfx_base_url to your SFX base URL. This is not used in general link resolver menu functions, but may be used in 'search' function to look up a manually typed in journal name or citation. It is also used on Umlaut's error page, to give the user an option of going to the native original SFX in an error condition.
* You may want to set AppConfig::Base.help_url , which is also used on error pages.

There's really nothing else here you need to change to get Umlaut to work properly for you, but feel free to look around in the other files in initializers to see what sorts of things you can customize (an awful lot, sometimes by writing custom logic in ruby code to determine a particular Umlaut decision.)

== 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

(should also work on straight http://yourservername.tld:3000/)

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]].

Umlaut Installation

2010-02-08T15:55:37Z

Navtis: marc requirement

[[Category:Umlaut]]

To install Umlaut

== 1. Make sure you have a modern Ruby ==

Install a 1.8.x version of ruby, ruby 1.9 is still considered experimental. The Rails web page says "We recommend Ruby 1.8.7 for use with Rails. Ruby 1.8.6, 1.8.5, 1.8.4 and 1.8.2 are still usable too, but version 1.8.3 is not."
The ''marc'' gem (referred to below) needs Ruby 1.8.6 or greater to install. (http://rubyonrails.org/download) Try installing Ruby with your package manager of choice. If not, try installing from source, eg

# [Download 1.8.4>http://rubyforge.org/frs/download.php/7858/ruby-1.8.7.tar.gz]
# tar -zxvf ruby-1.8.7.tar.gz
# cd ruby-1.8.7
# sudo ./configure
# sudo make
# sudo make install

( jrochkind is currently running ruby 1.8.6 as of Dec 08 )

== 2. Install RubyGems ==

Again, your package manager may be able to supply this (for example "yum install rubygems), but if not, you could again install from source:

# [Download here>http://rubyforge.org/frs/?group_id=126]
# tar -zxvf rubygems-x.x.x.tar.gz
# cd rubygems-x.x.x
# sudo ruby setup.rb
( actually don't do this, to be safe # sudo gem update) (I don't know what this means, jrochkind 14 May 09!)

== 3. Install Rails ==

Umlaut requires Rails 2.1.2, and is bound to it in the default environment.rb. It has not been verified for Rails 2.2.x yet. So install the 2.1.2 version of Rails (you can have multiple versions of Rails installed simulataneously, don't worry about this overwriting a more recent version of Rails you may want--it won't.)

"sudo gem install rails -v 2.1.2" (say yes to any dependencies)

'''Note''': There are various guides available on the net to getting Ruby/Rubygems/Rails installed on various OSs. Consult if you have trouble.

== 4. Install Umlaut ==

Right now, the best (only) way to install Umlaut is from it's SVN store.

For a read-only checkout of Umlaut 2.10.0 (If there is a more recent version, hopefully I'll remember to update it here, or ask me, or look around in the svn repo. 1 July 09):

<pre>
svn checkout http://umlaut.rubyforge.org/svn/tags/2.10.0 ./Umlaut
</pre>

Or instead of "./Umlaut", whatever local path you want to put the thing in.

For a checkout with commit privs, you need a rubyforge account and to be added to the umlaut project, then:

<pre>
svn checkout svn+ssh://(developername)@rubyforge.org/var/svn/umlaut/tags/2.10.0 ./Umlaut
</pre>

If you are a developer who wants the latest in-progress version of umlaut, check out /trunk instead of /tags/2.10.0.

Umlaut comes with a number of Ruby gems and Rails plugins "frozen" into it's distribution, in vendor/plugins. You do not need to install these, they come with Umlaut. These include: json_pure ; sru; xisbn; enumerations_mixin (plugin) ; app_config (plugin); isbn-tools (plugin) ; openurl ( svn external link in plugin; needs to be fixed to link to a specific tag ); htmlentities (http://htmlentities.rubyforge.org/)

However, there are a few plugins that can not be conveniently packaged with Umlaut, you need to install them yourself...

== 5. Install Umlaut's gem dependencies ==

=== mongrel ===

(Umlaut will not run with WEBrick due to threading issues. Recommend installing mongrel for testing and deployment. mongrel 1.1.4 or later is highly reccommended. )

sudo gem install mongrel

=== hpricot ===

(hpricot is compiled C code, so you are best off installing it yourself. Right now hpricot 0.6 is tested and confirmed. )

sudo gem install hpricot -v 0.6

=== json ===

A pure-ruby json library is bundled with Umlaut automatically, but you really ought to install the compiled C one on your server instead, for much better performance. Umlaut will automatically use it if present. Currently verified with version 1.1.3

sudo gem install json -v 1.1.3

=== marc ===

A rubygem necessary for the generate script. Provides a ruby library for processing Machine Readable Cataloging (MARC) bibliographic data.

sudo gem install marc

=== mysql ===

MySQL is the reccomended db, and the only db currently verified to work. Umlaut won't usually run with SQLite3 due to threading issues.

Rails is supposed to be able to talk to mysql without the mysql gem installed (just less efficiently), but for some reason Umlaut seems to have trouble with this. Not sure, you can try it.

sudo gem install msyql

Except some additional configuration arguments may be neccesary to compile on your machine.

===== redhat =====

On RedHat and CentOS machines, you will need to have the mysql-devel packages installed.

On a RedHat machine, this works:

sudo gem install mysql -- --with-mysql-config=/usr/lib/mysql/mysql_config

===== ubuntu =====

On Ubuntu you will also need to:

sudo apt-get install libmysqlclient15-dev

Then you can:

sudo gem install mysql

Ubuntu also packages the mysql library, if you'd rather use that version you can try:

sudo apt-get install libmysql-ruby

===== Solaris 10 (sparc) =====

This has been reported to work on Solaris 10 (sparc)

gem install mysql -- --with-mysql-include=/opt/pkgs/mysql/include/
\ --with-mysql-lib=/opt/pkgs/mysql/lib

=== More optional gems ===

* Voyager sites that want to bypass z39.50 and access Oracle directly will need Oracle Instant Client or Full Client installed on the same machine as the Umlaut. (This native Voyager code is not currently verified as working.) [http://www.jiubao.org/ruby-oci8 Oracle OCI8] [http://www.oracle.com/technology/tech/oci/instantclient/index.html Oracle Instant Client]

== 5. Configure SFX API to be used ==

On the SFX server that umlaut will be using as a datasource, make sure that the sfx api is turned on in the web-based admin tool (http://sfx.xxx.xxx.edu/sfxadmin/instance-name). This option can be found under the '''SFX API''' in the Menu Configuration Tool. Make sure that the '''Include availability info in text format''' and '''Include availability info in structured XML format''' options are checked. Once these options have been checked, the sfx web server instance needs to be restarted.

== Now You Need to Setup Umlaut ==

Good job, you've got all software installed, now you need to do some setup. See [[Umlaut Setup]].