Requirements

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

Config changes

There are new options for how to handle fedora and solr connection errors that happen when servicing requests (app_controller) and background jobs (app_job). The defaults are to raise errors in background jobs so sidekiq can reenqueue them and only log in controllers allowing the possibility of better error messages for users instead of a generic 500. This is configurable in settings.yml.

app_controller:
  solr_and_fedora:
    raise_on_connection_error: false
app_job:
  solr_and_fedora:
    raise_on_connection_error: true

Derivative download is a new feature in Avalon 7.8 and is enabled by default for admins and collection managers.

derivative:
  # Choose whether collection managers and admins can download high quality derivatives
  allow_download: true

A maximum upload size for web uploaded files has been disabled by default. It can be enabled and set (in bytes) by uncommenting the line in settings.yml.

# Maximum size for uploaded files in bytes (default is disabled)
#max_upload_size: 2147483648 # Use :none or comment out to disable limit

Troubleshooting

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

SupplementalFile Migration

Transcript search, a new feature in Avalon 7.8, is a powered by indexed SupplementalFiles and relating them back to their owning parent objects. This migration populates a new `parent_id` column on the SupplementalFile model.

Some objects may not migrate properly and errors encountered will be written to log/parent_id_backfill_errors.log. Besides checking the logs, you can check the number of indexed SupplementalFiles against the total number of SupplementalFiles in the rails console:

SupplementalFile.count
ActiveFedora::SolrService.instance.conn.get("select", params: { q: "has_model_ssim:SupplementalFile", rows: 0 })["response"]["numFound"]

If the migration reports that the migration was successful but the counts do not match, it could be that parent objects have been deleted orphaning SupplementalFiles, a known problem.

MediaObject Section List Migration (optional)

Avalon 7.8 moves data about section order from a separate fedora object to a property on the MediaObject model to be more performant when objects have many sections. The MediaObject model is already coded to lazily migrate existing objects whenever they are saved and this migration will finish updating objects that haven’t already been migrated.

Before running the migration, you can dump the section lists stored in ordered_master_file_ids by running:

bundle exec rails r "ActiveFedora::SolrService.instance.conn.get('select', params: { rows: 1_000_000, q: 'has_model_ssim:MediaObject', fl: [:id, :section_id_ssim], sort: 'id asc' })['response']['docs'].each {|doc| puts \"#{doc['id']}: section_ids: #{doc['section_id_ssim'] || []}\" }" > section_list_dump.pre_migration.txt

Some objects may not migrate properly and the script will log any errors that happens. This could be due to networking issues or objects in an atypical state. Trying running the migration again and reach out to the Avalon team if you have problems resolving any objects that fail to migrate.

After the migration, run the following line to dump again and validate that the section lists, now stored in section_ids matches the one dumped prior to the migration:

bundle exec rails r "ActiveFedora::SolrService.instance.conn.get('select', params: { rows: 1_000_000, q: 'has_model_ssim:MediaObject', fl: [:id, :section_list_ssim], sort: 'id asc' })['response']['docs'].each {|doc| puts \"#{doc['id']}: section_ids: #{JSON.parse(doc['section_list_ssim'].first || '[]').to_s}\" }" > section_list_dump.post_migration.txt
diff -awu section_list_dump.pre_migration.txt section_list_dump.post_migration.txt

Upgrade Steps

For Manual Installations

1. Install ruby 3.2.x (if needed)

2. Update gems, and migrate DB

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

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

4. Update JS dependencies

   yarn install # in Avalon root dir

5. Update configuration, see Config changes above

6. Restart passenger (if using)

   passenger-config restart-app

7. Run rake migrations

   RAILS_ENV=production bundle exec rake avalon:migrate:backfill_parent_id
   RAILS_ENV=production bundle exec rake avalon:migrate:media_object_section_list

For Docker Installations

1. Stop Avalon

   docker-compose down

2. Update new code from avalon-docker

   git checkout main
   git pull

3. Pull new images

   docker-compose pull avalon solr

4. Check config changes then restart the Avalon containers

   docker-compose up

5. Run rake migrations (inside avalon container)

   RAILS_ENV=production bundle exec rake avalon:migrate:backfill_parent_id
   RAILS_ENV=production bundle exec rake avalon:migrate:media_object_section_list

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

docker-compose build avalon