This is part of a larger tutorial created and presented as "A hands on introduction to GeoBlacklight".

Note: If you have issues with any of these steps, a prebuilt version of this application is available within the provided virtual machine. The application can be accessed by SSHing into the virtual maching and then changing directory to pregenerated/demo_geoblacklight_app.

Create your application

Prerequisite: Make sure your environment is setup.

  1. Generate your Rails application
  2. Install GeoBlacklight
  3. Install RSpec

Generating your Rails application

For more information about generating a Rails application see the Getting Started with Rails guide.

  1. Create a new Rails application using the GeoBlacklight template

    $ rails new your_app_name
    
  2. Switch to its folder

    $ cd your_app_name
    
  3. Run the rails server.

    $ rails s -b 0.0.0.0
    

    We are running the Rails server with the “-b” option which is binding the server to the 0.0.0.0 IP address. This is only necessary if your are running the application on your Vagrant virtual machine.

    Now you can visit the Rails application at http://127.0.0.1:3000. You should see “Welcome aboard You’re riding Ruby on Rails!” CTRL + c will stop server.

    rails_welcome

  4. Optional Initialize your git repository and commit your changes

    $ git init
    $ git add .
    $ git commit -m 'initial commit of Rails application'
    

Install GeoBlacklight

  1. Add GeoBlacklight to your Gemfile

    # In ./Gemfile
    gem 'blacklight'
    gem 'geoblacklight'
    
  2. Install required gems and their dependencies

    $ bundle install
    
  3. Run Blacklight generator (with devise authentication)

    $ rails g blacklight:install --devise
    
  4. Run GeoBlacklight generator (overrides Blacklight default Solr config)

    $ rails g geoblacklight:install -f
    

    Depending on how your machine is setup you may need to prepend the rails or rake command with bundle exec.

  5. Run database migrations

    $ rake db:migrate
    

    Quick tip: All of these tasks (1 - 5) are included as part of template to generate a new GeoBlacklight application. To run that generator just run:

    $ rails new your_app_name -m https://raw.githubusercontent.com/geoblacklight/geoblacklight/master/template.rb
    
  6. Start the Solr and Rails server.

    $ rake geoblacklight:server
    

    Running this command will download and start the Solr server. Other commands available to control Solr include:

    $ rake solr:clean # Useful when seeing a "core already exists" error.
    $ rake solr:start # Starts Solr independently of the Rails server in the background (without loading core)
    $ rake solr:stop # Stops Solr
    $ rake solr:restart # Stops and restarts an already running background Solr server
    
  7. Navigate to http://127.0.0.1:3000. You should see the GeoBlacklight homepage. CTRL + c will stop both the Solr and Rails server.

  8. Optional Commit your work

    $ git add .
    $ git commit -m 'installed Blacklight and GeoBlacklight'
    

    Great job for making it this far. You now have a working GeoBlacklight application!

Install RSpec

RSpec is a behavior-driven development framework for Ruby. It is the recommended way to test your application and is used by both the Blacklight and GeoBlacklight projects.

  1. Add rspec-rails to both the :development and :test groups in the Gemfile

    # In ./Gemfile
    group :development, :test do
      gem 'rspec-rails', '~> 3.0'
    end 
    
  2. Download and install RSpec

    $ bundle install
    
  3. Initialize the spec/ directory (where specs will reside) with

    $ rails generate rspec:install
    
  4. Run your tests (specs) by running

    $ bundle exec rspec
    

    Writing tests for your application is outside the scope of this guide, but there are plenty of great examples out there. Check out the Thoughtbot blog.

  5. Optional Commit your work

    $ git add .
    $ git commit -m 'Installed RSpec'
    

Next Steps

So far you have a working GeoBlacklight application with a test framework installed. One thing missing is an index to have your application search against. The next section focuses on indexing Solr documents.