Software requirements for current implementation

Executive summary:

Here's what you'll need to run oai4courts:

  • A database package that works with Rails (mySQL, Postgres, and Oracle should all work, but see here), and that you're comfortable pushing data around with it
  • subversion.
  • ruby, of course.
  • rubygems
  • You'll need some additional gems
    • appropriate gems for connecting with your database from the utility scripts you'll use to populate it
    • login_generator for authentication (don't think this packages itself with the app, but it might).
    • possibly additional gems to use with whichever relational database you're running -- see the database-specific information below
  • Ruby on Rails.
  • Capistrano -- a configuration and deployment manager -- is recommended but not required.
  • the oai4courts package itself

The long version:

Ruby and Rails setup

OAI4Courts is a Ruby on Rails application, so you'll need to install both Ruby and Rails. Depending on how you decide to populate your database, you'll probably need some other Ruby packages as well. Instructions for several simple-to-install packages are here; you should probably start with those.

You might also find one of these tutorials helpful:

 gem install rails --include-dependencies
You'll need to think a little bit about how you want to make Rails work with your existing Web server setup. Basically, Rails applications run their own little servlets, typically using Webrick, Mongrel, or FastCGI. How you integrate them with (for instance) an existing Apache setup is up to you. Here's a little guidance:

Database preparation

We assume that you have a relational database system (such as mySQL) installed, and are able to create databases in it. You will need to create one called oai_production, and a user who has rights to it.

Database drivers are a different problem. So far as we know, Rails comes with pretty much everything you need. Different database packages may also require the installation of more Ruby gems; it's possible that you've already done this as part of the Ruby installation process.

mySQL setup

Rails has a built-in library that connects it with mySQL. It's slow, and (according to the Rails developers) unsuited for production use. So you'll probably want to begin by installing the more robust version, which is packaged as a gem:
gem install mysql
If the installer complains that it needs to know more about your mySQL installation, you can give it options like this:
gem install mysql -- --with-mysql-lib=/usr/lib/mysql
Note the presence of the extra dashes.

Next create the database at the command line (we're calling it oai_production)

 mysqladmin -u somebody -p create oai_production
Then you'd make a user (we call her 'oai_user') and grant them rights on the database:
 grant all on oai_production.* to oai_user identified by 'secretpassword'
You can then test access using the mysql command-line client. There is no need to create anything further in the database -- this will be handled as part of the Rails setup.

[ contributions of similar setup information for postgres, Oracle, and SQL Server would be highly appreciated ]

Obtaining and setting up oai4courts itself

Download oai4courts via anonymous subversion

Decide where you'd like to put your code; it doesn't have to be in an existing web tree. This documentation assumes that you're going to end up with all the code in /usr/local/OAI-current. To start with, just cd to the parent directory (subversion will take care of creating the subdirectory structure in a minute):

 cd /usr/local
Now, check out the source code. There are two branches -- you need only run one of the following commands, not both. The first will get you the current stable version; the second has the often-broken development version.
 svn co svn:\/\/chrome.law.cornell.edu/OAI-current    OR (you probably don't want this. Don't say we didn't warn you.)    svn co svn:\/\/chrome.law.cornell.edu/OAI
Connect oai4courts with your database setup

Next, you'll need to tell oai4courts about your database server. Copy the example configuration file to its proper location:

 cd OAI-current/config/initializers  cp database.yml.example ../database.yml
Now, you'll need to edit it. The simplest way is to change the production setup to reflect your database installation:
 production:  adapter: mysql  database: oai_production  timeout: 5000  username: oai_user  password: secretpassword

Initialize the databases
Make sure that you're in the root directory of your oai4courts installation, then run the Rails migration that sets up the database.
cd /usr/local/OAI-current export RAILS_ENV=production rake db:migrate
You should see a stream of messages showing the creation of many tables within the database.

mySQL users: if the script complains that it can't find mysql.sock, you can add a line like this to database.yml:

 socket: /var/lib/mysql/mysql.sock
Run a quick test of the application

Decide how you will run the application for production

Configure your repository

You can get to the main repository configuration screen using your web browser:

This will lead you to a series of more-or-less self-explanatory setup screens.

Populating your oai4courts database
How you do this is completely up to you. You can use whatever set of languages and techniques you're most comfortable with to stuff your existing metadata into the database, to configure sets, and so on. The hard part is knowing what to put where. These documents should help with that, and you should probably read them in order:

Other helpful information

Information on working with other databases:

LexCraft corpusType 

LexCraft tags 

LexCraft section 

LexCraft articleType