Getting Started for Developers

After reading this guide, you will know:

• How to install a local instance of GeoBlacklight for Development purposes.
• How to make small changes to the application.
• How to see how those changes look in a browser.

For a more in-depth guide to development, see the tutorials.

Dependencies

Software you should have installed on your development computer

• Ruby > 3.0.0
• Git > 2
• Java > JRE version 11 or higher

Installation for Development

To set up a working space, navigate to where you'd like to put your test GeoBlacklight app and then clone the repository:

$ git clone git@github.com:geoblacklight/geoblacklight.git

Once the files are downloaded, run

$ cd geoblacklight
$ bundle exec rake geoblacklight:server

This command executes everything needed to run a local version of GeoBlacklight. In order to see the version you have running, open a web browser and go to http://localhost:3000/. You should be able to navigate around the site. Remember that your Rails server is running locally, so to stop it, run ^C (ctrl + c).

Refer to the Customization pages of this website for instructions on making look and feel changes. Refer to the Metadata section for instructions on testing new records.

Running Solr and Rails server separately

You may decide to run either the Solr server or Rails server separately. With Solr, for instance, run

$ rake geoblacklight:solr

Then, open another Terminal window, navigate to the place where your app is located, and run:

$ rake engine_cart:server

Once the server is running, you can open a web browser and visit the URL it prompts, usually http://localhost:8983/solr/#/blacklight-core to see the admin interface of your test instance of Solr. As before, remember that ^C (ctrl + c) stops the server.

Unit Testing

Running all the tests

As you develop and make changes, you may want to run tests on parts of the app to see if any warning occur. You can run the following to test the app

$ rake ci

Note that a test like this could take up to 5-6 minutes to complete, or longer. Warnings, deprecations, and other messages will be printed on your Terminal screen.

Running the tests separately

$ rake geoblacklight:solr

Then, in another terminal window:

$ rspec spec/

Note: It is not necessary to run tests after every change you make. You can, for instance, change the name of a facet field, save your file, and then refresh your browser to see the change. However, if you add a new fixture metadata record, you will have to stop the servers and then restart them so the new file will be indexed.

Browser Testing

Cross-browser testing provided by:

Helpful Development Tools

Version Managers

Using version management tools for compatible versions of Ruby (rvm, rbenv, asdf) and Node (nvm, asdf) can make development easier.

asdf

Many developers like asdf because you can manage versions for Ruby and Node in a single utility. For developers who use asdf, it is helpful to add a .tool-versions file for each app.

Example:

ruby 2.7.5
nodejs 17.4.0
java openjdk-11.0.2