Upgrading Avalon 7.6 to Avalon 7.7

Owned by Jon Cameron
Last updated: Apr 10, 2024 by Chris Colvard
3 min read

Avalon 7.7 requires a full reindex due to performance improvements introduced in this release. You may also want to upgrade your version of Solr to 9.x at this time.

Requirements

Ruby 3.2.x and Node.js 20.x are recommended.

Config changes

Recaptcha v2 checkbox (default) or v3 can be enabled and configured in settings.yml

recaptcha: site_key: # Setting a site_key will enable recaptcha on the comments form secret_key: # Required along with site_key type: "v2_checkbox" # or "v3" v3: action: "comment" minimum_score: 0.5

The language code for default captions language now requires a 3 letter ISO 639-2 code.

caption_default: # Language should be 3 letter ISO 639-2 code language: 'eng' name: 'English'

Troubleshooting

Before starting the upgrade there are some steps to keep a close eye on when running.

Reindex

When running the reindex watch for any errors in the log output. If errors occur the reindex can be rerun by either clearing out the reindexing DB table or resetting the specific failed items and trying them again.

# Clearing out the reindexing DB table RAILS_ENV=production bundle exec rails r script/reindex.rb -v --drop-table # Resetting failed items (in rails console) DB = Sequel.connect(ENV["DATABASE_URL"]) DB[:reindexing_nodes].where(state: "errored").update(state: "waiting reindex")

The order of indexing is important so watch to see if any Hydra::AccessControl or Hydra::AccessControls::Permission objects failed to index. If any did this might impact the access control of items indexed later. If you’re continuing to run into problems the reindex script can be rerun on specific models and without parallelization. This should be the safest way to run the reindex.

When reindexing is done be sure to check that the Manage Content page loads for an admin. If it returns a 500 error then rerun the indexing of Admin::Collection objects:

Caption Migration

Sometimes the caption migration fails to migrate all captions. Before running the migration first take a count of captions:

Compare this number to the output of the caption migration rake task. If they do not match, try running the migration again until the total “successfully migrated” between all of the runs matches the count from the output before running the migration.

Upgrade Steps

For Manual Installations

  1. Install Ruby 3.2.x 

  2. Update gems, and migrate DB

  3. Install node.js 20.x (if needed)

  4. Update JS dependencies

  5. Update configuration, see Config changes above

  6. Restart passenger (if using)

  7. Install Solr 9 (optional)

    1. Make backup of existing Solr using instructions on Backing up and restoring supporting services | Solr

    2. Setup Solr 9 in a new location and update config files (solr.yml and blacklight.yml) (safest approach)
      Or the same location as previous Solr and clear it out

  8. Run reindex
    First download the latest version of the reindex script to script/reindex.rb then run:

  9. Run rake migrations

For Docker Installations

Note: avalon-docker 7.7.0 switches to a bind mount volume for storing Solr data for safer persistence across upgrades.

  1. Stop Avalon

  2. Backup solr data using instructions on Backing up and restoring supporting services | Solr

  3. Update new code from avalon-docker

  4. Pull new images

  5. Check config changes then restart the Avalon containers

  6. Run reindex (inside avalon container)
    First download the latest version of the reindex script to script/reindex.rb then run:

  7. Run rake migrations (inside avalon container)

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