diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 976f5238..f3ea075c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,6 +1,8 @@ # ✨ Contributing ✨ + NYU's Spatial Data Repository (SDR) is a collaborative open source project where contributions are welcome. + This contributing guide is borrowed in part from [Geoblacklight](https://github.com/geoblacklight/geoblacklight/blob/master/CONTRIBUTING.md). Contents: @@ -9,14 +11,14 @@ Contents: - [How to add a GitHub issue](#how-to-add-a-github-issue) - [How to submit a pull request](#how-to-submit-a-pull-request) - [Software Versioning](#software-versioning) -- [Development Guide](#development-guide) - ### Who can contribute? + Anyone is welcome to contribute to the SDR, though the core group at NYU will need to discuss and vet pull requests. We follow a set of contribution practices to maintain a socially inclusive and technically sustainable software project. For more information, please visit our [Code of Conduct](CODE_OF_CONDUCT.md). ### What kinds of contributions are wanted? + - Requesting bug fixes ⁉️🐛 (submitted as [GitHub issues](#adding-github-issues)) - Requesting features ⁉️🎉 (submitted as [GitHub issues](#adding-github-issues)) - Requesting documentation ⁉️📄 (submitted as [GitHub issues](#adding-github-issues)) @@ -25,6 +27,7 @@ We follow a set of contribution practices to maintain a socially inclusive and t - Committing documentation ➕📄 (submitted as [pull requests](#submitting-pull-requests)) ### How to add a GitHub issue + Did you find a bug in the SDR or interested in a new feature? Make sure to add an issue for it in the [issue tracker](https://github.com/NYULibraries/spatial_data_repository/issues). - Make sure you have a [GitHub account](https://github.com/signup/free) @@ -52,33 +55,8 @@ Do you have software fixes or documentation changes to contribute to the codebas For more robust information about the above steps, see the [Development Guide](#development-guide) below. - ### Software Versioning -The SDR follows the practice of [Semantic Versioning](https://semver.org/) for software releases, tracking the versioning for Geoblacklight where possible. -The version for a given release is recorded in the `VERSION` file in the project root. - -### Development Guide -- Install [Vagrant](https://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/) on your local machine. If you are on Mac and have [Homebrew](https://brew.sh/) installed, `brew cask install virtualbox && brew cask install vagrant` should be sufficent. If not, submit an [issue](https://github.com/NYULibraries/spatial_data_repository/issues)! - -- Clone the master branch of the SDR to your desktop with `cd ~/Desktop && git clone https://github.com/NYULibraries/spatial_data_repository.git` - -- Change directory into the local SDR `cd ~/Desktop/spatial_data_repository` - -- Start the virtual machine with `vagrant up`, then enter it with `vagrant ssh` - -- Within the VM, change directory with `cd /vagrant/sdr` - -- Load the database schema with `bundle exec rake db:schema:load` - -- Start the Solr + SDR servers with `bundle exec rake sdr:server` -- Open the development SDR running locally in your browser at http://localhost:3000 - -- Test your changes by editing the project files using your favorite text editor, e.g., [Atom](https://atom.io/) - -- When you are done: - + quit the webserver with `Ctl-C` - + exit the virtual machine by typing the command `exit` - + stop the virtual machine with the command `vagrant halt` +The SDR follows the practice of [Semantic Versioning](https://semver.org/) for software releases, tracking the versioning for Geoblacklight where possible. -- If you have changes to contribute, submit a pull request (see [above](#how-to-submit-a-pull-request)) +The version for a given release is recorded in the `VERSION` file in the project root. diff --git a/.gitignore b/.gitignore index ce52aea5..49115b20 100644 --- a/.gitignore +++ b/.gitignore @@ -25,9 +25,6 @@ # Ignore assets /public/assets/* -# Ignore Vagrant -/.vagrant -/sdr.box .byebug_history *cloudimg-console.log diff --git a/.rubocop.yml b/.rubocop.yml index 1fd39522..561c3a18 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -10,7 +10,6 @@ AllCops: - 'bin/*' - 'config/**/*' - 'vendor/**/*' - - 'Vagrantfile' - 'app/helpers/geoblacklight_helper.rb' - 'coverage/**/*' - 'log/**/*' diff --git a/.tool-versions b/.tool-versions new file mode 100644 index 00000000..2857c926 --- /dev/null +++ b/.tool-versions @@ -0,0 +1,3 @@ +ruby 3.2.2 +java openjdk-17 +nodejs 22.6.0 diff --git a/README.md b/README.md index ddd5ba9e..faa02807 100644 --- a/README.md +++ b/README.md @@ -2,65 +2,87 @@ [![CI](https://github.com/NYULibraries/spatial_data_repository/actions/workflows/ci.yml/badge.svg)](https://github.com/NYULibraries/spatial_data_repository/actions/workflows/ci.yml) -This repository tracks the implementation of GeoBlacklight used to power the front-end of NYU Libraries [Spatial Data Repository](https://geo.nyu.edu) +This repository tracks the implementation of GeoBlacklight used to power the front-end of NYU Libraries' [Spatial Data Repository](https://geo.nyu.edu) -## Links +## Local Development Quickstart -- [Documentation Repo](https://github.com/NYULibraries/sdr-documentation) +### Prerequisites -## Archive +You will need the following installed: -- [Wiki for GBL 0.12.1](https://github.com/NYULibraries/spatial_data_repository/wiki); some info obsolete but contains some supporting doc and application change tracking +- Git +- MySQL +- Ruby 3.2.2 +- NodeJS 20+ +- Java 11+ -## Local Development Quickstart +(Check specific versions in [.tool-versions](./.tool-versions)) +#### Installing Prerequisites with Homebrew & asdf -Below are barebones steps for getting started in development for the SDR. +If you don't already have the prerequisites installed on your Mac laptop you can use [Homebrew](https://brew.sh) and [asdf](https://asdf-vm.com) to install everything you need: -### Using Vagrant +```bash +$ brew install git mysql asdf +``` +You'll need to [set up asdf for your chosen shell](https://asdf-vm.com/guide/getting-started.html#_3-install-asdf) and then you'll be able to install the required language plugins: -#### Prerequisites -- Git -- Vagrant -- VirtualBox +```bash +$ asdf plugin add ruby +$ asdf plugin add java +$ asdf plugin add nodejs +``` -#### Steps +### Running a Development Server -1. Run the commands below in order specified: - - `git clone https://github.com/NYULibraries/spatial_data_repository.git && cd spatial_data_repository` - - `vagrant up` - - `vagrant ssh` - - `cd /vagrant/sdr` - - `bundle exec rake db:schema:load` - - `bundle exec rake sdr:server` -2. View to test environment Solr admin panel: http://localhost:8983/ -3. View the operating GeoBlacklight Rails app: http://localhost:3000 +Checkout the project repo: -### On Mac, including M1-3 (no virtualization) +```bash +$ git clone https://github.com/NYULibraries/spatial_data_repository.git +$ cd spatial_data_repository +``` +Next, load the correct Ruby, Node, and Java versions using your version managers. If you're using `asdf`, you can do this with: -#### Prerequisites -- Git (`brew install git`) -- Ruby 3.2.2 (not 3.3.1) + Rails (many options; GBL recommends this [Go Rails install list](https://gorails.com/setup/macos/14-sonoma#ruby), especially for Apple M1, M2; use `asdf` install manager and install Ruby + Nodejs + Rails) -- Mysql (`brew install mysql`) -- Java (`brew install openjdk@11`); if needing help to add Java to PATH, see [this help](https://stackoverflow.com/questions/71059252/mac-the-operation-couldn-t-be-completed-unable-to-locate-a-java-runtime-that-su)) +``` sh +$ asdf install +``` +Finally, install the ruby gems and node modules, load the data, and start the server: +``` +$ bundle install +$ npm install +$ bundle exec rake db:schema:load +$ bundle exec rake sdr:server +``` -#### Steps +The development SDR web application will be available at -1. Run the commands below in order specified: - - `git clone https://github.com/NYULibraries/spatial_data_repository.git && cd- spatial_data_repository` - - `bundle install` - - `bundle exec rake db:schema:load` - - `bundle exec rake sdr:server` -2. View to test environment Solr admin panel: http://localhost:8989/solr -3. View the operating GeoBlacklight Rails app: http://localhost:3000 +The development Solr instance will be available at -### Setup Gotchas +#### Setup Gotchas If the `mysql2` gem fails to install and complains about not finding `zstd` you may need to do the following: ```bash -gem install mysql2 -v '0.5.6' -- --with-opt-dir=$(brew --prefix openssl) --with-ldflags=-L/opt/homebrew/opt/zstd/lib +$ gem install mysql2 -v '0.5.6' -- --with-opt-dir=$(brew --prefix openssl) --with-ldflags=-L/opt/homebrew/opt/zstd/lib +``` + +### Loading NYU Data in Development + +First, start up the Rails app if it's not already running: + +```bash +$ bundle exec rake sdr:server +``` + +Then in another terminal run the following Rake task: + +```bash +$ bundle exec rake sdr:load_nyu_data ``` +Once completed, head to and you should have a lot more data to work with. + +The Solr instance does not persist its data between runs so you will need to reload the data if you ever restart the web application. + ### Running the Test Suite To run the full test suite use the following command: @@ -87,20 +109,8 @@ Note: You'll know this step is necessary if an individual spec fails with an err Blacklight::Exceptions::ECONNREFUSED: Connection refused - Unable to connect to Solr instance using # ``` -### Loading NYU Data Locally - -First, start up the Rails app if it's not already running: +## Resources -```bash -$ bundle exec rake sdr:server -``` - -This will ensure Solr is up and running. - -Then in another terminal run the following Rake task: - -```bash -$ bundle exec rake sdr:load_nyu_data -``` - -Once completed, head to and you should have a lot more data to work with. +- [Documentation Repo](https://github.com/NYULibraries/sdr-documentation) +- [Wiki for GBL 0.12.1](https://github.com/NYULibraries/spatial_data_repository/wiki) + - some info obsolete but contains some supporting doc and application change tracking diff --git a/Vagrantfile b/Vagrantfile deleted file mode 100644 index d745fdb7..00000000 --- a/Vagrantfile +++ /dev/null @@ -1,63 +0,0 @@ -# frozen_string_literal: true - -# -*- mode: ruby -*- -# vi: set ft=ruby : -RUBY_V = File.open('./.ruby-version', &:read).chomp - -Vagrant.configure(2) do |config| - config.vm.box = 'bento/ubuntu-16.04' - config.vm.hostname = 'sdr-geoblacklight' - config.vm.synced_folder '.', '/vagrant/sdr' - - config.vm.network 'forwarded_port', guest: 8983, host: 8983, auto_correct: true - config.vm.network 'forwarded_port', guest: 3000, host: 3000, auto_correct: true - - config.vm.provider 'virtualbox' do |vb| - vb.memory = '1024' - end - - $apt_script = <<-SCRIPT - sudo apt-get update - sudo apt-get install -y apache2 curl git nodejs gcc bzip2 dkms software-properties-common libreadline-dev libmysqlclient-dev g++ firefox libsqlite3-dev - - sudo add-apt-repository -y ppa:openjdk-r/ppa - sudo apt-get update - sudo apt-get install -y openjdk-8-jdk - - sudo debconf-set-selections <<< 'mysql-server-5.5 mysql-server/root_password password rootpass' - sudo debconf-set-selections <<< 'mysql-server-5.5 mysql-server/root_password_again password rootpass' - sudo apt-get -y install mysql-server - sudo apt-get -y autoremove - SCRIPT - - $rbenv_script = <<-SCRIPT - if [ ! -d ~/.rbenv ]; then - git clone https://github.com/rbenv/rbenv.git ~/.rbenv - echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc - echo 'eval "$(rbenv init -)"' >> ~/.bashrc - fi - if [ ! -d ~/.rbenv/plugins/ruby-build ]; then - git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build - echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc - fi - export PATH="$HOME/.rbenv/bin:$PATH" - export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH" - eval "$(rbenv init -)" - if [ ! -e .rbenv/versions/#{RUBY_V} ]; then - RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install #{RUBY_V} - rbenv global #{RUBY_V} - fi - cd /vagrant - if [ ! -e /home/vagrant/.rbenv/shims/bundle ]; then - echo 'gem: --no-document' >> ~/.gemrc - gem install bundler - rbenv rehash - fi - cd /vagrant/sdr - gem update bundler - bundle install - SCRIPT - - config.vm.provision :shell, inline: $apt_script - config.vm.provision :shell, privileged: false, inline: $rbenv_script -end