hydra 6.2.0.rc1 → 6.2.0

data/doc/Lesson:-create-a-git-repository.md

@@ -0,0 +1,35 @@
+This lesson is known to work with hydra (gem) version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+Note: This lesson is basically equivalent to the [Create A New Git Repo](http://curriculum.railsbridge.org/curriculum/create_a_new_git_repo) step in the RailsBridge Curriculum.
+
+# Goals
+* Create a local git repository that will track all changes to this application's code
+
+# Explanation
+
+In order to track the changes you make to your code, to share your changes with others, and to pull other people's changes into your code, you need some form of Version Control.  All of the Hydra projects use Git for version control and share their work on Github.
+
+# Steps
+
+Now, let's turn this directory into a git repository.  Type the following:
+
+```bash
+$> git init .
+```
+
+Then you should see something like this:
+
+```
+Initialized empty Git repository in /Users/justin/hydra-demo/.git/
+```
+
+Next, we'll add all the files rails created into the repository.  This way we can jump back to this state later if the need arises.
+
+```bash
+$> git add .
+$> git commit -m "Initial rails application"
+```
+
+# Next Step
+Go on to [[Lesson: Add the Hydra Dependencies]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-generate-a-rails-application.md

@@ -0,0 +1,53 @@
+This lesson is known to work with hydra (gem) version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Create your new Ruby on Rails Application
+
+# Explanation
+
+**Note:** This lesson is basically equivalent to the [Getting Started](http://curriculum.railsbridge.org/curriculum/getting_started) step in the RailsBridge Curriculum.
+
+This lesson assumes you are using a **3.2 or 4.0 version of rails**.  To avoid confusion, it's better to have a clean gemset with only one version of rails installed.  Most people use either [RVM](http://rvm.io) or [rbenv](https://github.com/sstephenson/rbenv) to handle gemsets and ruby versions.
+
+The first step to creating a Hydra Head, or any other type of Rails Application, is to generate the basic skeleton of the application code.
+
+# Steps
+
+### Step 1: Create a new rails application
+
+Once you have installed a suitable rails gem (any 3.2 or 4.0 release), begin by using it to generate a new rails application.  You can choose any name for your application.  In this tutorial we are calling it hydra-demo 
+
+```bash
+$> rails new hydra-demo
+```
+
+This generates the file structure for an empty rails application. And it runs 'bundler' which loads in all of the external dependencies for rails.
+
+Enter the directory for the new rails app: ```cd hydra-demo```, then you should see a file structure like this:
+
+```bash
+$> ls
+Gemfile		Rakefile	config.ru	lib		script		vendor
+Gemfile.lock	app		db		log		test
+README.rdoc	config		doc		public		tmp
+```
+
+### Step 2: Set your Ruby version for this project
+
+Create the file ```.ruby-version``` in your project's directory (hydra-demo). Put your Ruby's version inside that file. For example, if you're using ruby-2.0.0, your file would look like this:
+
+```text
+2.0.0
+```
+
+If you're using a Ruby environment manager such as RVM or rbenv, this will make it so you switch to the correct version of Ruby when you enter this directory.
+
+> ### Linux only step: Enable javascript runtime
+>
+> Find the line in your Gemfile that has ```# gem 'therubyracer', :platforms => :ruby``` and uncomment that line.  This allows your system to identify the appropriate javascript runtime.
+>
+> Now save the Gemfile and run ```bundle install```. This tells bundler to update your dependencies to reflect the change in your Gemfile.
+
+# Next Step
+Go on to [[Lesson: Create a git Repository]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-install-hydra-jetty.md

@@ -0,0 +1,57 @@
+This lesson is known to work with hydra release version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Install a copy of hydra-jetty, which includes pre-configured copies of Fedora and Solr
+
+# Explanation
+In order to use blacklight and hydra-head, you need an installation of Solr.  Additionally, hydra-head requires a copy of the Fedora repository.  We have created a package called hydra-jetty, which provides both of these within a Jetty Java application server.
+
+# Steps
+
+
+### Step 1: Install the hydra-jetty package 
+
+Use the hydra:jetty generator to install the hydra-jetty package by running:
+
+```bash
+$> rails g hydra:jetty
+```
+
+This generator is provided by the jettywrapper gem.
+
+
+This can be very slow (over 100Mb of download).  When it's done you'll see the directory named ```jetty``` has been created. If you run '''git status''' you will see 
+
+```text
+# On branch master
+# Untracked files:
+#   (use "git add <file>..." to include in what will be committed)
+#
+#	jetty/
+```
+
+**Windows Tip**:  Currently this rake task doesn't work on Windows (see [jettywrapper issue #14](https://github.com/projecthydra/jettywrapper/issues/14) for status).  Workaround: Download https://github.com/projecthydra/hydra-jetty/archive/new-solr-schema.zip, unpack it, and move the unpacked 'jetty' directory to the root of your application.
+
+### Step 2: Make git ignore the jetty directory
+
+We want git to ignore the jetty directory for the same reasons that we don't check our development databases into git -- because it's big and bulky and you don't actually need other developers to have exact copies of your jetty as long as they have all the other code. 
+
+We do that by editing ```.gitignore``` and adding the something like this:
+
+```text
+# Ignore jetty directory (from hydra-jetty)
+/jetty
+
+```
+
+Now commit this change
+
+```
+git add .gitignore
+git commit -m "Adds /jetty to .gitignore"
+```
+
+
+# Next Step
+Go on to [[Lesson: Start Jetty]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-make-blacklight-return-search-results.md

@@ -0,0 +1,47 @@
+This lesson is known to work with hydra version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Tell Blacklight which fields to use in searches
+* Run a search in Blacklight and see results rendered
+
+# Explanation
+
+In [[Lesson: Build a Book Model]] you made a Book object, saved it, and saw that the Book's metadata was indexed in Solr.  Now we will make that Book appear in your Blacklight searches.
+
+# Steps
+
+### Step 1: Run a search in the CatalogController
+
+Visit or reload the page at [[http://localhost:3000/]].  You should see the Blacklight search interface with a search box.  If you search for 'Anna' you don't see any results even though we created a Book called "Anna Karenina" and indexed it in Solr in the last lesson.  
+
+### Step 2: Tell Blacklight which fields to use in Queries
+
+The reason why we're not getting any hits is because we haven't told Blacklight which fields to search in.  Let's fix that by setting the default 'qf' solr parameter.  Open `app/controllers/catalog_controller.rb` and set the `default_solr_params` section (around line 18) to this:
+
+```ruby
+    config.default_solr_params = { 
+      :qf => 'title_tesim author_tesim',
+      :qt => 'search',
+      :rows => 10 
+    }
+```
+
+### Step 3: Re-run your search
+
+Save the file, and refresh your web browser. You should now see a result for "Anna Karenina" when you search for "Anna"
+
+**Tip:** When you make changes like this, you *don't* need to restart the Rails server.  This is because in development mode (which is the default environment for the Rails server), the Rails server reloads any files in app/models, app/controllers, app/views, etc. for every request it receives from a browser.  This makes the server slower, but it makes life much smoother when you're actively developing and making changes.
+
+### Step 4: Commit your changes
+
+Now that we've updated our search functionality, it's a great time to commit to git:
+
+```bash
+$> git add .
+$> git commit -m "Disabled access controls and set default search fields"
+```
+
+# Next Step
+Go on to [[Lesson: Define Relationships Between Objects]] or 
+explore other [Dive into Hydra](Dive into Hydra#Bonus) tutorial bonus lessons.

data/doc/Lesson:-run-the-Hydra-generator.md

@@ -0,0 +1,39 @@
+This lesson is known to work with hydra version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Add Hydra (Hydra, Blacklight, and Devise) functionality to your Rails Application
+
+# Explanation
+
+Hydra builds on and extends the features provided by Blacklight, the generator integrates core hydra and blacklight functionality into your application.  To do this, we run the custom [Rails generator](http://guides.rubyonrails.org/generators.html) provided by the hydra gem.  The generator creates a number of files in your application that will allow you to build a Hydra application and use and modify Blacklight's features in your application.  The default generator also installs [devise](https://github.com/plataformatec/devise) to provide simple user authentication and management.
+
+**Tip:** If you want to see clearly what changes that the generator has made, make sure that before you run the generator all of your current changes have been checked into git -- so before running the generator running 'git status' should report that there are no changes ("nothing to commit").  Then when you run the generator you will be able to see all of the changes it's made by runing 'git status'.
+
+# Steps
+
+**Note:** You must have completed the steps in [[Lesson: Add the Hydra Dependencies]] in order for the following steps to work.
+
+
+### Step 1: Run the code generator provided by the Hydra gem.  
+
+We do this by typing 
+
+```bash
+$> rails generate hydra:install
+```
+
+The hydra generator invokes both the blacklight generator and the hydra-head generator.  Additionally, the blacklight generator installed the devise gem and the bootstrap gem.  It's created an important file in our application `app/controllers/catalog_controller.rb`.  This is the primary place where you configure the blacklight search.
+
+When they are done, the generators have created a few database migrations that support saving user data, searches and bookmarks. Normally you would have to run `rake db:migrate` to update your database tables, but the hydra installer does this for you as one of its last steps.
+
+### Step 2: Commit your changes
+At this point it's a good idea to commit the changes:
+
+```bash
+$> git add .
+$> git commit -m "Ran hydra generator"
+```
+
+# Next Step
+Go on to [[Lesson: Install hydra-jetty]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-set-up-your-Rails-Application-to-use-rspec.md

@@ -0,0 +1,41 @@
+This Tutorial is known to work with hydra version 6.1.0.  
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+
+* Set up a Rails application to use RSpec
+
+# Explanation
+We strongly recommend building a habit of using Test Driven Development.  Most people using Hydra use RSpec for Test Driven Development.  Also, RSpec tests are required with any contributions to any of the core Hydra gems.  Here's how to set up your Rails application to use RSpec for testing.
+
+# Steps
+
+### Step 1: Install the rspec and rspec-rails gems
+
+Ensure your Gemfile includes `rspec-rails`, e.g.:
+```ruby
+group :development, :test do
+  gem "rspec-rails"
+end
+```
+If you had to add `rspec-rails`, run bundle install
+```bash
+$ bundle install
+```
+
+### Step 2: Run the rspec rails generator
+
+On the Command line
+```text
+rails generate rspec:install
+```
+
+### Step 3: Commit your changes
+
+```text
+git add .
+git commit -m"added rspec"
+```
+
+# Next Steps
+Return to the [[Dive into Hydra]] page.

data/doc/Lesson:-start-jetty.md

@@ -0,0 +1,85 @@
+This lesson is known to work with hydra release version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Start and Stop Jetty (which contains Fedora and Solr)
+
+# Explanation
+Fedora and Solr are both Java web applications that need to run in a servlet container like Tomcat or Jetty.  We installed hydra-jetty in the [[Lesson: Install hydra-jetty]].  Now whenever you need Fedora and Solr running, just start or stop that copy of hydra-jetty.
+
+**Tip:** Sometimes people are confused about whether they need to restart jetty when they restart their Rails application.  In most cases it is fine to leave jetty running when you start, stop, and restart the Rails application.  The only exception is when you make changes to Solr's configuration or Fedora's configuration -- these would be changes to files inside of your copy of hydra-jetty (ie. jetty/solr/config), not changes to files in your Rails application's Ruby code.  In those cases, where you have made changes to Solr or Fedora's configuration, you need to restart Jetty in order for those changes to take effect.  The most common change that requires restarting jetty is when you modify the solrconfig.xml or schema.xml in your solr config directory.
+
+# Steps
+
+### Step 1: Start Jetty
+At the project root, type 
+
+```bash
+$> rake jetty:start
+```
+
+You should see output like this:
+
+```text
+Starting jetty with these values: 
+jetty_home: /Users/justin/hydra-demo/jetty
+jetty_command: java -Djetty.port=8983 -Dsolr.solr.home=/Users/justin/hydra-demo/jetty/solr -Xmx256m -XX:MaxPermSize=128m -jar start.jar
+Logging jettywrapper stdout to /Users/justin/hydra-demo/jetty/jettywrapper.log
+Wrote pid file to /Users/justin/hydra-demo/tmp/pids/_Users_justin_hydra-demo_jetty.pid with value 8315
+Waited 5 seconds for jetty to start, but it is not yet listening on port 8983. Continuing anyway.
+Started jetty (5575.9ms)
+```
+
+hydra-jetty has a fair amount of stuff in it, so it may take up to a minute to start.  You can check to see if it's started by going to [[http://localhost:8983/solr]]
+
+If Fedora, Solr, or jetty itself are not starting, you'll want to look at the jettywrapper log to diagnose.
+
+**Windows Tip:* This rake task is not currently working on Windows (see [jettywrapper issue #13](https://github.com/projecthydra/jettywrapper/issues/13) for status).  In the meantime, start jetty manually
+```
+cd jetty
+java -Djetty.port=8983 -Dsolr.solr.home=/Users/justin/hydra-demo/jetty/solr -Xmx256m -XX:MaxPermSize=128m -jar start.jar
+```
+
+### Step 2: Look at the jettywrapper log
+
+The jetty:start rake task runs jetty as a background job, so jetty's logs won't appear in your terminal.  Instead they're written to the file ```jetty/jettywrapper.log```.  If you look at the output from running the jetty:start task, you'll see that one line gives you the full path to the file, for example:
+
+```text
+Logging jettywrapper stdout to /Users/justin/hydra-demo/jetty/jettywrapper.log
+```
+
+You can open this log file with any text editor or log reader.
+
+```bash
+$> vi jetty/jettywrapper.log
+```
+
+### Step 3: Monitor the jettywrapper log
+
+
+**Tip:** if jetty is taking a long time to start, you can watch its output using the tail command with the path to your jettywrapper.log.  For example:
+
+```bash
+$> tail -f jetty/jettywrapper.log
+```
+
+As Jetty, Fedora, and Solr start you will see more info being written to the log file. After a few moments you will be able to open jetty at [[http://localhost:8983]] or [[http://0.0.0.0:8983]] (**note:** The root page will give a 404 error, but should have three links to the applications running in Jetty: /solr, /fedora and /fedora-test)
+
+### Step 4: Stop Jetty
+You might have guessed this one.  In order to stop jetty, at the project root, type
+
+```bash
+$> rake jetty:stop
+```
+
+### Step 5: Start Jetty again
+Before proceeding to the next step, make sure jetty is running.  If you're not sure whether it's running, go to http://localhost:8983.  If jetty is running a page will load.  If jetty is not running no page will load.
+
+If it's not running, just use the jetty:start rake task again.
+
+```bash
+$> rake jetty:start
+```
+
+# Next Step
+Go on to [[Lesson: Start the Application & Search for Results]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-start-the-application-&-search-for-results.md

@@ -0,0 +1,43 @@
+This lesson is known to work with hydra release version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Start and Stop a local "development" copy of the application
+* Remove the default Welcome page provided by Rails
+* Run a Search in Blacklight through your browser
+
+# Steps
+
+### Step 1: Start the Rails server
+
+Now, let's see our model on the web.  You can start 'webrick', a development server that comes with rails by typing:
+
+```bash
+$> rails server
+```
+
+Leave that terminal window open.  It will print info whenever the server does anything.  You will return to this window when you want to stop or restart the server.
+
+### Step 2: Look at the application in your Browser
+
+Now you can visit your local copy of the application with a web browser when you point the browser at [[http://localhost:3000/]]
+
+> ####Rails 3-only step: Remove the Rails default "Welcome" page
+>
+> If it worked you should see a page with the text: "Welcome aboard. You’re riding Ruby on Rails!".  This is the default page, but now that we know it works, we can delete it. In Rails 4 you will **NOT** see the default rails welcome page and you can proceed to the 'Run a Search' step.
+>
+> Open a new terminal (so we can keep the server running) and type:
+>
+> ```bash
+> $> rm public/index.html
+> ```
+> Then reload the page at [[http://localhost:3000/]].  
+
+### Step 3: Run a Search
+
+Now that you've removed the default "Welcome" page and reloaded the page in your browser, you should see something that looks like a default Blacklight install.  If you enter a search query you don't see any results because we haven't created any objects yet -- your Solr index is empty.
+
+In the next step we will create a Book object that will then show up in your search results.
+
+# Next Step
+Go on to [[Lesson: Build a Book Model]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-turn-off-access-controls.md

@@ -0,0 +1,37 @@
+This lesson is known to work with hydra version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* *(for now)* Turn off access controls for Blacklight-based searches and "show" views 
+
+# Explanation
+One of the main features that Hydra adds to Blacklight is the ability to control who has access to which information in search results.  That topic gets a little bit complicated.  For the purpose of this Tutorial we want to stay focused on showing you how to set up an app, define models and create objects based on those models, so in order to keep things simple we will make this Hydra Head behave like an open access repository where everyone can see everything.  Once you've completed this tutorial, you can check out [Access Controls with Hydra](https://github.com/projecthydra/hydra-head/wiki/Access-Controls-with-Hydra) to learn how to assert access controls on objects and enforce those access controls in a Hydra Head.
+
+# Steps
+
+### Step 1: Comment out the lines that enforce access controls in Blacklight's CatalogController
+
+If you open ```app/controllers/catalog_controller.rb``` and look at the code near lines 8-12 you should see this:
+```ruby
+  # These before_filters apply the hydra access controls
+  before_filter :enforce_show_permissions, :only=>:show
+  # This applies appropriate access controls to all solr queries
+  CatalogController.solr_search_params_logic += [:add_access_controls_to_solr_params]
+```
+
+This code tells blacklight to enforce access controls on the search and result view pages.  For the time being we will turn this off by commenting out two lines so that it looks like this:
+
+```ruby
+  # These before_filters apply the hydra access controls
+  #before_filter :enforce_show_permissions, :only=>:show
+  # This applies appropriate access controls to all solr queries
+  #CatalogController.solr_search_params_logic += [:add_access_controls_to_solr_params]
+```
+
+### Step 2: Save the file
+
+Then, save the file.
+
+
+# Next Step
+Go on to [[Lesson: Make Blacklight Return Search Results]] or return to the [[Dive into Hydra]] page.