Collex Getting Started
Contents
System Requirements
Collex requires a fairly modern processor (newer than 2001 recommended), 2 GB of RAM. A dataset comparable to NINES requires 2-3 GB of disk space, but disk usage depends largely on the number of objects indexed into your installation. It has been tested on Mac OS X as well as Solaris, but it should work on any system with the following components:
- Ruby 1.8.4
- Ruby on Rails 1.2.6
- Java 1.5
- Ant 1.6
- JUnit
- MySQL 5.x
- Capistrano 1.4.1 (see Collex Deployment)
Getting the Source Code
The source code is housed in a Subversion repository with the UVa Library. The Collex subdirectory is arranged in the following manner:
- collex + trunk + tags - branches - RB-1.0
The "trunk" directory is for the latest version of the software. It represents the bleeding edge, which is fairly stable and appropriate for development use. The "RB-1.0" directory represents a release branch for the 1.0 release in August 2006. Developers who wish to work on trunk would issue the following command to check out a local copy for running and revision:
svn co https://subversion.lib.virginia.edu/repos/patacriticism/collex/trunk collex
This will create a "collex" directory with all the sources. Additionally you will want to check out some RDF in order to index some data. The following will check out the RDF for the Rossetti Archive:
svn co https://subversion.lib.virginia.edu/repos/patacriticism/rdf/ra rossetti
Setup
Ant
download and install ant from the apache site. You typically set an environment variable of $ANT_HOME for the installation location. In order to compile the sources you will need to also download JUnit and install its Jar file into $ANT_HOME/lib in order for the compilation (ant index automatically compiles) to work.
Ruby
Collex has been tested with Ruby 1.8.4, 1.8.5 and 1.8.6 and can be obtained from ruby-lang.org. If you are installing on Solaris we highly recommend that you use the binary distribution provided by Blast Wave.
Gems
Ruby Gems are library packages to install and use various add-ons for Ruby. Download and install RubyGems from rubygems.org or Blast Wave if you are using Solaris.
Rails
To install rails, type the following:
gem install rails
Make sure that you have Rails 1.2.6 installed
Required Gems
The following gems must be installed for Collex to work:
- mysql
- rake
You would install them by invoking the command "gem install mysql", for example.
Suggested Gems
We recommend adding the mongrel gem, which makes use of a much better http server for rails. After installing it is used automatically by the script/server command noted below. To install, simply run "gem install mongrel".
MySQL
You should create three databases in mysql:
- nines_development
- nines_production
- nines_test
Consult the MySQL Documentation for information on creating a username (with a password) to access the database. After doing this, edit the collex/web/config/database.yml file so that the username and password fields match up with the database. This permits the Rails application to connect to the database.
Finally, you should run the rake migration to set up all the database tables:
cd collex/web RAILS_ENV=development rake db:migrate
Running unit and functional tests
Collex has a number of unit and functional tests. These are run by simplying running Rake (in the web directory):
rake
We strongly encourage all new code come with unit and functional tests, and no code should break existing tests.
Running the server
There are actually two server processes to make Collex work: solr and rails.
Starting Solr
You will first need to run the "ant" command, which compiles all the sources and packages a web application for the embedded Jetty server.
cd collex/solr ant cd dist/solr java -jar start.jar
That will leave that shell running the solr process.
Starting Rails
Now open up another shell and get another process running:
cd collex/web script/server
This, too, will "occupy" the shell process.
Indexing some RDF
Assuming you downloaded the Rossetti Archive RDF as noted earlier, you can run the indexer (from another shell, which you'll probably want to open from another window) as follows:
cd collex/solr ant index -Drdf.dir=/path/to/rossetti -Dsolr.url=http://localhost:8983/solr
It will run for several minutes and should conclude with the phrase "BUILD SUCCESSFUL". To affirm that all went well, pull up the administrative interface (http://localhost:8983/solr/admin/stats.jsp) and you should see 22130 documents loaded.
Using Collex
Now you can pull up your local Collex installation and see the Rossetti Archive content:
Have fun!