Requirements

Ruby 2.7.x is recommended.

Config changes

No changes to settings.yml

Solr 8 config files are now provided at solr/conf for experimentation with upgrading and is the default in the docker-compose development environment.  Upgrade tooling and documentation for production environments will be available in a future avalon release.  Solr 6 config files are still available at solr/config.

The default branch of the avalon github repository has been renamed to main in line with the Samvera contributing guidelines.

Rails/Blacklight/Bootstrap Upgrades and Styling

This release of Avalon includes upgrades of Rails (5.2 → 6.0), Blacklight (6 → 7), and Bootstrap (3 → 4) which require special attention if your avalon has been customized.

Rails

One of the major changes in Rails is the use of zeitwerk as the code loader.  Zeitwerk will warn if any unsafe loading happens in initializers.  The solution to this problem is usually to wrap any code which autoloads classes in a Rails.application.config.to_prepare block.  For examples see https://github.com/avalonmediasystem/avalon/pull/4657.

Another change is a requirement to allow list hosts that the rails server will respond to.  Avalon by default will allow the host set in the `domain.host` setting as well as any set in the RAILS_ADDITIONAL_HOSTS environment variable.  The docker-compose config (both the development environment in avalon and the avalon-docker environment) allows the avalon host which docker creates for its internal network.  If you connect to your avalon instance using a different hostname then these, you will probably need to set RAILS_ADDITIONAL_HOSTS environment variable or make changes to config/initializers/default_host.rb.  See https://blog.saeloun.com/2019/10/31/rails-6-adds-guard-against-dns-rebinding-attacks.html for more details.

Blacklight

Blacklight 7 changes include the upgrade of bootstrap to 4, changes to search builders, and switching the /catalog json endpoints to return standard JSON-API.  If you have customized the CatalogController, any of the search builders, or any of the catalog views, you may need to make changes to ensure compatibility.  See the Blacklight 7 release notes for more details: https://github.com/projectblacklight/blacklight/releases/tag/v7.0.0

Bootstrap

If you have overridden or custom views you will probably need to adjust the CSS styling for bootstrap 4.  Blacklight has a bootstrap upgrade guide available.

Upgrade Steps

For Manual Installations

1. Install ruby 2.7
2. Update gems, and migrate DB

bundle install --with production --without development test
RAILS_ENV=production bundle exec rake db:migrate

3. Update JS dependencies

yarn install # in Avalon root dir

4. Update configuration, see Config changes above

5. Restart passenger (if using)

passenger-config restart-app

For Docker Installations

Update new code from avalon-docker

git checkout main
git pull

Pull new Avalon image. 

docker-compose pull avalon

Check config changes then replace the Avalon containers

docker-compose up avalon worker

You can also build your own image, Docker Buildkit is recommended

docker-compose build avalon