Requirements

Ruby 4.x and Node.js 24.x are recommended.

Config changes

New defaults

• Derivative download will attempt to use presigned urls for S3 urls (derivative.use_presigned_url)

Changed defaults

• manager and group_manager have been removed from system_groups in the default settings.yml as they are no longer used with the new inherited permissions. If you have customized this setting you can safely remove these two groups.

• The blacklight pagination window (search_pagination) has been configured to display 2 pages on either side of the current page and the first two pages. The final two pages are no longer displayed to dissuade users and bots from doing deep pagination which is a more expensive operation.

Optional

• Avalon 8.2 has a feature to require accessibility compliance (transcript or captions present) for items created after a certain date (accessibility_compliance.compliance_date). This feature is disabled by default (accessibility_compliance.enforce).

• The HLS streaming nginx container image now has the ability to connect to an authenticated S3 bucket. See https://github.com/avalonmediasystem/avalon-docker#authenticating-and-streaming-from-s3s3-like-storage for more details about configuring this feature.

Unit Migration

With Avalon 8.2 units are now first-class objects instead of just a controlled vocabulary. Permissions and roles are now inherited from units to collections to items. Avalon 8.2 comes with an upgrade migration to create unit objects and set a default unit admin. After the migration completes you can assign a unit admin manually to each individual unit.

Saved Searches in Blacklight Disabled

By default Blacklight has been saving all searches in the database and not automatically cleaning them. Avalon does not make use of these and does not show Blacklight’s interface for saved searches so Avalon 8.2 disables saving these in the database. If you want to clear out the existing saved searches to save on DB space run the following:

Upgrade Steps

For Manual Installations

1. Install ruby 4.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 24.x (if needed)

4. Set NODE_ENV environment variable to production

5. Update JS dependencies

   yarn install # in Avalon root dir

6. Rebuild assets

   RAILS_ENV=production bundle exec rake assets:clobber assets:precompile

7. Update configuration, see Config changes above

8. Setup DB encryption environment variables
   Run the following:

   RAILS_ENV=production bundle exec rails db:encryption:init

   Then copy the output to create the ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY, and ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT environment variables or edit config/application.rb and insert them there. These are secrets so do not commit them to version control.

9. Restart passenger (if using)

   passenger-config restart-app

10. Run unit migration

    RAILS_ENV=production bundle exec rake avalon:migrate:admin_units

11. Migrate existing API tokens

    RAILS_ENV=production ACTIVE_RECORD_ENCRYPTION_MIGRATION=true bundle exec rails r 'ApiToken.all.each(&:encrypt)'

For Docker Installations

1. Stop Avalon

   docker compose down

2. Update new code from avalon-docker

   git fetch git checkout v8.2.0.1 git pull

3. Pull new images

   docker-compose pull avalon

4. Check config changes then restart the Avalon containers

   docker compose up

5. Run unit migration

   docker-compose exec avalon /bin/bash -c "RAILS_ENV=production bundle exec rake avalon:migrate:admin_units"

6. Setup DB encryption environment variables
   Run the following and copy the output into ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY, and ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT in .env or edit docker-compose.yml and insert them there in the avalon service. These are secrets so do not commit them to version control.

   RAILS_ENV=production bundle exec rails db:encryption:init

7. Restart the application

   docker compose down docker compose up

8. Migrate existing API tokens

   docker-compose exec avalon /bin/bash -c "RAILS_ENV=production ACTIVE_RECORD_ENCRYPTION_MIGRATION=true bundle exec rails r 'ApiToken.all.each(&:encrypt)'"

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

For Terraform installations

1. Set avalon_docker_code_branch and avalon_branch in terraform.tfvars if necessary. (Latest tags are v8.2.0.1 for Avalon and avalon-8.2.0.1-aws_min for avalon-docker.)

2. Perform the upgrade:

   terraform apply

3. Enter the EC2 box and run the unit migration and migrate the existing API tokens

   sudo su - ec2-user cd avalon-docker docker-compose exec avalon /bin/bash -c "RAILS_ENV=production bundle exec rake avalon:migrate:admin_units" docker-compose exec avalon /bin/bash -c "RAILS_ENV=production ACTIVE_RECORD_ENCRYPTION_MIGRATION=true bundle exec rails r 'ApiToken.all.each(&:encrypt)'"

You may also see an error when attempting to create an iam user which already exists. If this happens rerunning the terraform apply should resolve the issue and successfully run to completion