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.
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).
Troubleshooting
If you run into issues running this rake task, try removing your `Gemfile.lock` file and removing the test app with `rm -R .internal_test_app`. Then run `bundle install` before running the above command again.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.
Using an External SOLR Instance
In some cases you may need to install SOLR through a different method than described above, or link your GeoBlacklight installation to an existing SOLR installation. You can learn more about installing SOLR in the Apache documentation.
Configure the SOLR Core
Once you have SOLR installed, you will need to create a new core and configure it for GeoBlacklight. How you create the core may depend on your installation method, but will likely be something like
$ bin/solr -c blacklight-core
Now rename/remove the core's conf
directory and replace it with the solr/conf
directory from GeoBlacklight: [github.com/geoblacklight/geoblacklight/tree/main/solr/conf](https://github.com/geoblacklight/geoblacklight/tree/main/solr/conf.
You can alter the core's configuration here as well, generally in the schema.xml
file.
You can find the installation location of your SOLR instance through the web admin interface: http://yourdomain.com:8983/solr/
Set SOLR_URL
Environment Variable
GeoBlacklight will use the SOLR_URL
environment variable (if present) to look for SOLR. For example, assuming your core is named blacklight-core
:
$ export SOLR_URL=http://yourdomain.com:8983/solr/blacklight-core
Now run the rails server and your external SOLR will be used
$ rake engine_cart: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