h1. Setting Up the Hydra-Head Plugin as a Project Containing a Rails Application for Testing or Demo

This document describes how to set up a project for the hydra-head plugin code itself - primarily intended for the hydra-head plugin developers.  It will contain a pre-configured rails application for testing the hydra-head plugin.

It does NOT describe how to set up a rails application that uses the hydra-head plugin.  For that, see "CREATE_RAILS_APP":https://github.com/projecthydra/hydra-head/blob/master/CREATE_RAILS_APP.textile.

h2. Install the Hydra-Plugin and its Contained Test Host Application

h4. (0) Install Prerequisites.

See "INSTALL_PREREQ":/projecthydra/hydra-head/blob/master/INSTALL_PREREQ.textile

h4. (1) Get the hydra-head engines plugin from github and include the testing rails application.

<pre>
git clone --recursive git@github.com:projecthydra/hydra-head.git
cd hydra-head
</pre>

This will also initialize and update the jetty and hydra-plugin_test_host git submodules. The former is a copy of Jetty pre-configured for Hydra with Fedora and Solr installed. The latter is a preconfigured Rails application to house and test the hydra-head engines plugin.

This <b>hydra-head directory</b> is the <b><i>root of the plugin</i>.</b>

h4. (2) Use bundler to install the gem dependencies.

<pre>
  bundle install
</pre>

Note that if you have RVM installed, it will create/use a gemset called "hyhead".


h4. (3) Put a copy of the hydra-head plugin into the testing application

The rails application used for testing MUST have a copy of the hydra-head plugin added to its vendor/plugins directory. We provide a "rake task":http://hudson.projecthydra.org/job/hydra-head-rails2-plugin/Documentation/file.README_RAKE_TASKS.html#hyhead_Test_Host_Setup__setup_test_host for this which copies your current hydra-head plugin code into hydra-plugin_test_host/vendor/plugins as well as the fixtures and cucumber features required for testing.

<pre>
rake hyhead:setup_test_host
</pre>

h4. (5) Migrate the test databases

See below to reset the test databases when re-running tests.

You must do this within the <b><i>hydra-plugin_test_host</i> directory</b>, not at the root of the plugin.

<pre>
  cd hydra-plugin_test_host
</pre>  

To ensure that the tests do not rely on non-test data, do this:

<pre>
  rake db:drop:all 
</pre>

Migrate the test databases:

<pre>
  rake db:migrate RAILS_ENV=test  
</pre>

In case you ever run the server in development mode, you will need to migrate the databases without RAILS_ENV set to test:

<pre>
  rake db:migrate
</pre>

Now cd back up to the root of the <b><i>hydra-head plugin</i> directory</b>:

<pre>
  cd ../
</pre>

h3. Now you're ready to run the tests

If you want to run the tests, see "TESTING_PLUGIN":/projecthydra/hydra-head/blob/master/TESTING_PLUGIN.textile

h2. Running the Testing Application

The test host app is a regular Rails app with Blacklight installed.  It's configured with the assumption that the hydra-head plugin is installed into vendor/plugins/hydra-head.

Hydra expects Fedora and Solr instances to be running (for testing, a jetty instance is provided in the hydra-head plugin directory.  See also config/solr.yml and config/fedora.yml).

Change into the root of the test app and start it like you normally start any rails app.

<pre>
cd hydra-plugin_test_host
script/server
</pre>