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

Create your application

Before beginning this section, make sure your environment is setup.

In this section of the tutorial, we will cover the following steps:

  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. Before, make sure you have Rails installed by running the following:

$ rails -v

If you get an error run:

$ gem install rails

Now you should have Rails installed on your machine and are ready to proceed.

  1. Create a new Rails application using the GeoBlacklight template, in which “your_app_name” can be anything you want to name your app.

    $ rails new your_app_name
    ## For example, you could also use `rails new mockup_geoblacklight`
  2. Switch to its folder

    $ cd your_app_name
  3. Run the rails server.

    $ rails s -b

    We are running the Rails server with the “-b” option which is binding the server to the 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 You should see “Yay! You’re on Rails” CTRL + c will stop server.


Note You will need to leave the Terminal window open while the Rails server is running.

  1. Optional Initialize your git repository and commit your changes

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

Install GeoBlacklight

Now that we have started our Rails application, we need to install GeoBlacklight.

  1. Add GeoBlacklight to your Gemfile. To do this, navigate to the Gemfile in your application, open it with a text editor, and paste the following in to add it to the list of gems:

    # 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:

    $ DISABLE_SPRING=1 rails new your_app_name -m

    Remember to cd your_app_name into the directory before starting the server if you are using the template generator.

  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 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. Again, open the Gemfile with a text editor and paste the line below into the respective groups.

    # In ./Gemfile
    group :development, :test do
      gem 'rspec-rails', '~> 3.0'
  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.