Skip to content

Commit

Permalink
Initial Commit
Browse files Browse the repository at this point in the history
  • Loading branch information
@g8tor
g8tor committed Oct 30, 2009
0 parents commit cfc4743
Show file tree
Hide file tree
Showing 494 changed files with 22,088 additions and 0 deletions.
Empty file added CHANGES
Empty file.
14 changes: 14 additions & 0 deletions LICENSE
@@ -0,0 +1,14 @@
##########################################################################
# Copyright 2008 Rector and Visitors of the University of Virginia
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
110 changes: 110 additions & 0 deletions PRE-REQUISITES.rdoc
@@ -0,0 +1,110 @@
== Pre-requisites

===Ruby

Ruby version 1.8.7 (or 1.8.6 enterprise) is required. You can find out which version you are running by executing:
ruby -v
Information on installing Ruby can be found here:
http://www.ruby-lang.org/en/downloads

For installing Ruby and related goodies on Ubuntu, this may be helpful:
http://www.rubyinside.com/how-to-install-a-ruby-18-stack-on-ubuntu-810-from-scratch-1566.html

===Ruby Gems

You'll need Ruby Gems version 1.3.1 or later. You can check which version of “gem” you have by running:
gem -v
Information on installing Ruby Gems can be found here:
http://www.rubygems.org/read/chapter/3

To update your Ruby Gems, run (YMMV for various operating systems):
sudo gem install rubygems-update
sudo update_rubygems

You can also manually install Ruby Gems:
wget http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
tar xzf rubygems-1.3.1.tgz
cd rubygems-1.3.1
sudo ruby setup.rb
gem -v

These commands should work for Linux and OSX, but we haven't yet written any instructions for Windows installation. If anyone is able to volunteer for this task, please let us know!

===Ruby Gems Sources

Make sure you have the standard ruby gem sources available:
gem sources -l
should show
http://gems.rubyforge.org
http://gems.rubyonrails.org
http://gems.github.com
http://gemcutter.org

If you're missing those gem sources, add them like this:
gem sources -a http://gems.rubyforge.org
gem sources -a http://gems.rubyonrails.org
gem sources -a http://gems.github.com
gem sources -a http://gemcutter.org

===Git Client

Some of the rubygems required by blacklight are hosted in git repositories.
Information on getting the git client installed can be found here:

http://git-scm.com/
http://book.git-scm.com/2_installing_git.html

If you are behind a firewall, you may need to open port 9418 for Git.


===Install Blacklight's Ruby Gem dependencies:
You will need Rails gem version 2.3.2. You can check if you have it installed:
gem list

If you need to install rails 2.3.4:
sudo gem install -v=2.3.4 rails

You will need libxml and libxslt installed for the ruby-xslt and nokogiri gems.

On Red Hat Fedora the command is:
sudo yum install libxml2-devel libxslt-devel

Note: the curb gem can be used for Blacklight SOLR requests, instead of net::http,
which can be used by the rsolr gem. If you'd rather use curb than net::http, you need to make sure curl is installed.

On Red Hat Fedora the command is:
sudo yum install curl curl-devel

and then install the curb gem:
sudo gem install curb

===Database dependencies
You can choose to use any database that has ruby on rails bindings, but sqlite and MySQL are used most commonly and are documented here.

* if you are using sqlite3:
sudo gem install sqlite3-ruby

If you want to use sqlite, you will need to install sqlite3 and its ruby bindings

On Red Hat Fedora the command is:
sudo yum install sqlite sqlite-devel ruby-sqlite3

On OSX macports the command is:
sudo port install sqlite3 rb-sqlite3

On FreeBSD the commands are:
cd /usr/ports/databases/rubygem-sqlite3
make install clean


* if you are using MySQL, make sure MySQL is installed, and run:
sudo gem install mysql

===Dependencies included with Blacklight

* ActsAsTaggableOnSteroids plugin docs: http://agilewebdevelopment.com/plugins/acts_as_taggable_on_steroids

* Resource Controller: http://github.com/giraffesoft/resource_controller/tree/master There is a very good
video tutorial on the resource_controller plugin: http://www.vimeo.com/637894

* Additional gems are vendorized with blacklight and will be built locally by the ''rake gems:build'' command. See the README in this same directory for more information (provided in the post installation instructions.
188 changes: 188 additions & 0 deletions README.rdoc
@@ -0,0 +1,188 @@
=Blacklight

Please see {README_PROJECT.rdoc}[link:files/vendor/plugins/blacklight/README_PROJECT_rdoc.html] for main information about this project and plugin.

Please see {PRE-REQUISITES.rdoc}[link:files/vendor/plugins/blacklight/PRE-REQUISITES_rdoc.html] for pre-requisites Blacklight needs.

Please see {README_SOLR.rdoc}[link:files/vendor/plugins/blacklight/README_SOLR_rdoc.html] for information about setting up and configuring SOLR (http://lucene.apache.org/solr).

Note: these instructions apply to releases 2.2.0 and above.

NOTE: issue commands from your Rails application's root directory.

==How to Install the Blacklight Plugin into Your Rails Project

1. Create your rails app: http://guides.rubyonrails.org/getting_started.html#creating-a-new-rails-project
2. Install Blacklight:
From a release: (2.2.0_RC2 in this example)
script/plugin -v install http://blacklight.rubyforge.org/svn/releases/plugins/blacklight-plugin-2.2.0_RC2/
Or from trunk:
script/plugin -v install http://blacklight.rubyforge.org/svn/trunk/rails/vendor/plugins/blacklight/

Using <tt>script/plugin install</tt> calls the plugin's install.rb script, which does the following:

1. Automatically installs the Engines plugin ( http://rails-engines.org )
2. Updates config/environment.rb with the necessary lines for Engines and Blacklight
3. Copies the vendorized Authlogic gem from vendor/plugins/blacklight/vendor/gems to vendor/gems
4. Adds default solr.yml to config dir
5. Copies the migration files from vendor/plugins/blacklight/db/migrate to db/migrate
6. Copies the default blacklight_config.rb file to config/initializers/blacklight_config.rb

If you need to manually install Blacklight, see Installing Blacklight Manually below, then return to Post Installation.

==Post Installation

===Remove Rails Application Files Conflicting with Blacklight Plugin
From the your rails application's root directory:

rm public/index.html
rm app/controllers/application_controller.rb
rm app/helpers/application_helper.rb

===Run the Database Migrations
By default, Rails uses a SQLite3 database. Configure others in config/databases.yml. For more information, see {PRE-REQUISITES.rdoc}[link:files/vendor/plugins/blacklight/PRE-REQUISITES_rdoc.html]

rake db:migrate

===Build Gems
Now you need to build the "vendorized" gems for your local system:
from (rails app)/vendor/plugins/blacklight:

sudo rake gems:build

Note: you can run the above command from your rails app directory, but you may get error messages saying you need to install additional gems, e.g.

sudo gem install mislav-hanna
and/or messages that you need to create a database.yml file (see {DEMO_README}[link:files/DEMO_README] re: database.yml file).

After you successfully run gems:build, see if you have all of the required gems
installed, or whether you're still missing some:

rake gems

The ''rake gems'' command will give you a list of the required gems and their version numbers, and will tell you which ones are installed already.
You can also see vendor/plugins/blacklight/init.rb for the Blacklight plugin dependencies' versions.
An example of a versioned install: sudo gem install rails --version '2.3.2')

The gems vendorized with blacklight are in (rails_app)/vendor/plugins/blacklight/vendor/gems; all of the gems found there should be built locally by the ''rake gems:build'' command.

You can confirm your gem installations and their release numbers with

gem list

If you manually install (or uninstall?) gems, be sure to run ''sudo rake gems:build'' afterwards.

====Possible Issues with Gems

curb gem: since curb is currently not required for the RSolr gem (it will default to net::http, which should already be available via your ruby installation), you can do the following to get rid of the curb dependency:
in bl-demo/vendor/plugins/blacklight/init.rb
comment out the line
config.gem curb
by inserting "#" at the beginning of the line.

ruby-xslt gem: installations on Windows machines may have difficulties with ruby-xslt. This gem is only used for indexing EAD files. To remove this dependency:
in bl-demo/vendor/plugins/blacklight/init.rb
comment out the line
config.gem 'ruby-xslt', :lib=>'xml/xslt' # you may need to install libxml and libxslt
by inserting "#" at the beginning of the line.

Note: as of 2009-08-10, there have been some reports of problems with gems. If you are seeing errors relating to gems, you may need to uninstall other versions of gems if they are already installed, for example:
sudo gem uninstall curb
sudo gem uninstall nokogiri
sudo gem uninstall ruby-xslt

Be aware of gems that may have been inadvertently installed in your (home)/.gems directory, rather than in your system location for ruby gems. At least one site encountered difficulties when gems were installed in the account's directory, rather than in the system location. (This can happen if you don't use "sudo gem install" but instead use "gem install"). In this case, you may need to remove the account's version of the gems.
gem uninstall (gem name) - note absence of ''sudo''
If that doesn't work, you can try the brute force method to remove them:
cd ~/.gem/ruby/1.8/gems
then remove everything in that directory.

You may also see messages to run refresh_spec when you run the ''rake gems'' command; go ahead and follow those instructions. (In at least one case, the refresh_spec command needed to be run many times before the error messages ceased.)


===Start Solr
You need a running instance of Solr. Just to get going you can use the test instance in the Blacklight plugin:

cd vendor/plugins/blacklight/jetty
java -jar start.jar

This starts an instance of jetty with Solr running on port 8983. If you want to start on another port, use Java's -D argument:

java -Djetty.port=8888 -jar start.jar

This Solr instance already has data in the index. Once you start it you can run your Rails app and it will use this SOLR index (expected on port 8983).

./script/server

Now navigate to http://localhost:3000 and you should have a working demo blacklight application with the test data set!


==Installing Blacklight Manually

This assumes that for some reason you can't install the plugin via <tt>script/plugin install</tt> or
there was a problem and you need to finish manually. Otherwise, see the instructions above.

1. Create your Rails app: http://guides.rubyonrails.org/getting_started.html#creating-a-new-rails-project
2. Get the Blacklight plugin and put it in your plugins directory:

Edge: svn export http://blacklight.rubyforge.org/svn/trunk/rails/vendor/plugins/blacklight vendor/plugins/blacklight

Specific Release:

1. Find the release you want here: http://blacklight.rubyforge.org/svn/releases/plugins/
2. Then navigate to the plugin, for example: http://blacklight.rubyforge.org/svn/releases/plugins/blacklight-plugin-2.2.0
3. Use SVN to export it: svn export http://blacklight.rubyforge.org/svn/releases/plugins/blacklight-plugin-2.2.0

Finally, you can also downlowd the archive and unpack it in vendor/plugins/blacklight:

1. Find the release you want here: http://rubyforge.org/frs/?group_id=5235
2. Download it into vendor/plugins
3. Move to the directory: cd vendor/plugins
4. Unarchive: tar xvzf blacklight-plugin-2.2.0
5. Rename the directory: mv blacklight-plugin-2.2.0 blacklight

3. Install the Engines plugin:

script/plugin install git://github.com/lazyatom/engines.git

If you aren't using or can't use script/plugin, then install it manually:

1. git clone git://github.com/lazyatom/engines.git vendor/plugins/engines
2. rm -rf vendor/plugins/engines/.git

4. Update _config/environment.rb_ with necessary lines:

1. Below require File.join(File.dirname(__FILE__), 'boot'):

require File.join(File.dirname(__FILE__), '../vendor/plugins/engines/boot')

2. Inside Rails::Initializer.run do |config| block:

config.gem 'authlogic'
config.plugin_paths += ["#{RAILS_ROOT}/vendor/plugins/blacklight/vendor/plugins"]
config.plugins = %W(engines blacklight acts_as_taggable_on_steroids resource_controller)

5. Install the Authlogic gem. You can install this as a system gem or copy it from the Blacklight plugin:

* As a system gem:

sudo gem install authlogic

* As a vendorized gem (this is what the Blacklight installer does--see above):

mkdir vendor/gems
cp -rp vendor/plugins/blacklight/vendor/gems/authlogic-<version> vendor/gems/authlogic-<version>

6. Copy solr.yml to config dir:

cp vendor/plugins/blacklight/install/solr.yml config/

7. Copy the migration files to your app:

cp -pR vendor/plugins/blacklight/db/migrate db/migrate

8. Copy the default blacklight_config.rb file to config/initializers:

cp vendor/plugins/blacklight/config/initializers/blacklight_config.rb config/initializers/

9. Go to "Post Installation", above.
21 changes: 21 additions & 0 deletions README_PRODUCTION.rdoc
@@ -0,0 +1,21 @@
== Running Blacklight in Production Mode

Rails projects are generally designed so that "development" mode will reload files as you modify them, "test" mode is for testing only, and "production" mode caches files for faster performance.

To run Blacklight in Production Mode:

1. Create the prod database

You will need to ensure that the database for your production instance exists. See
(your app)/config/database.yml

2. Do the database migration for production
rake db:migrate RAILS_ENV=”production”

3. Start up your web server in production mode.

Many sites prefer mod_passenger as their web server, especially for production. See http://www.modrails.com/install.html

For mongrel, the command is

script/server -e production
28 changes: 28 additions & 0 deletions README_PROJECT.rdoc
@@ -0,0 +1,28 @@
Please note: The main Blacklight website is http://projectblacklight.org

=Installing Blacklight

== Some background information

Blacklight is open source discovery software. Libraries (or anyone else) can use Blacklight to enable searching and browsing of their collections online. Blacklight uses the Apache SOLR ( http://lucene.apache.org/solr ) search engine to index and search full text and/or metadata, and Blacklight has a highly configurable Ruby on Rails front-end. Currently, Blacklight can index, search, and provide faceted browsing for MaRC records and EAD XML files, and support is planned for Dublin Core and MODS as well. Blacklight was originally developed at the University of Virginia Library and is made public under an Apache 2.0 license. As of version 2.3.0 (released July 31, 2009), Blacklight is distributed as a rails engines plugin and also as a demo rails application that uses an engines Blacklight plugin.

== Which one should I install?
There are two ways of installing Blacklight. You can either install a pre-configured demo app, which already has the Blacklight plugin installed and integrated, or you can install the plugin into an existing rails application.

If you're just getting started with Blacklight and want to get something up and running
relatively quickly, start by installing the demo app. This will give you a good introduction
to the pieces of the Blacklight system before you start customizing your own installation.

If you want to integrate Blacklight search and discovery into another rails app, or if you already have a customized copy of Blacklight and you only want to upgrade the plugin, you'll want the plugin installation instructions.

==Pre-requisites
Whichever method you choose for installation, be sure you have all the pre-requisites in place. You can find these detailed in {PRE-REQUISITES.rdoc}[link:files/vendor/plugins/blacklight/PRE-REQUISITES_rdoc.html]

==Installing the demo app
Instructions for installing the demo app are contained in the file DEMO_README

==Installing the plugin into an existing rails app
Instructions for installing the demo app are contained in the plugin's {README.rdoc}[link:files/vendor/plugins/blacklight/README_rdoc.html]

==Running solr
You'll also want some information about how Blacklight expects Apache SOLR ( http://lucene.apache.org/solr ) to run, which you can find in {README_SOLR.rdoc}[link:files/vendor/plugins/blacklight/README_SOLR_rdoc.html]

0 comments on commit cfc4743

Please sign in to comment.