Upgrading to a new version of the distribution

Review a video about this document.

Before upgrading, please review the required version steps for your upgrade path.

Overview

• Prepare a dedicated environment for upgrade testing
• Obtain a local copy of your production site
• Run the composer update command
• Update the database
• Visit the OpenY upgrade tool dashboard
• Check for regressions/Run smoke tests
• Backup the updated site
• Proceed to the next version (repeat from step 1)

Upgrade Steps

Prepare a Dedicated Environment for Upgrade Testing

Ensure you have a working computer or virtual machine with:

• Ubuntu 20.04 (16.04, 18.04, or any decent Ubuntu LTS version) 64 bit
• MySQL 5.7+ (8+ is preferred because of the performance improvements)
• Apache 2.4 (or Nginx + php-fpm, but be aware of potential .htaccess issues)
• PHP 8.1 (older versions might have issues with some contributed modules)
• Drush 12, 11, or 10

The YMCA Website Services team maintains a Vagrant preconfigured Virtualbox based virtual machine with OpenY. Feel free to use it to get a working virtual environment. Follow the Vagrant documentation after locating the Vagrantfile within your YMCA Website Services instance’s codebase. Execute vagrant up to provision the virtual machine.

Obtain a Local Copy of Your Production Site

To proceed with the upgrade, create a local copy of your production site.

1. Database Backup: Make a backup of your production database and copy it to your local machine.
2. Codebase Copy: Make a copy of your production site codebase and copy it to your local machine.
3. Check for Manually Removed Modules: Ensure you have not manually removed Drupal modules in your database without uninstalling them first! If you have, return the module to the codebase and uninstall it via the Drupal Extend UI or Drush before proceeding.
4. Upgrade to the latest Open Y 9.2.x version: Ensure your site is on the latest 9.2.x release before proceeding to newer major versions. See the Open Y documentation for specific instructions on upgrading to the latest 9.2.x release.

Run the Composer Update Command

In the same folder as your docroot, run the following commands:

mv composer.json composer.json.bak || true
wget https://raw.githubusercontent.com/YCloudYUSA/yusaopeny-project/9.2.x/composer.json
composer update -W

This script replaces your composer.json file. Therefore, it is only suitable for websites with an unmodified composer.json.

If your composer.json file has been modified, manually merge the changes. The most important part is usually updating the repositories section.

Update the Database

Navigate to the docroot folder of your codebase and run:

drush updatedb

If updatedb Fails…

You can use Drupal’s hook_update_dependencies API to alter the order of updates. See this example for guidance.

Ensure the commands finish without errors. Run them a second time. If the output is:

$ drush updatedb
No database updates required                                                                                    [success]

This confirms the updates were executed correctly.

If Loading the Site Fails…

You might encounter an error like this:

Error: Class … not found in …

This occurs when Drupal cannot find renamed modules. Manually clear Drupal’s caches:

drush ev "drupal_flush_all_caches();"
drush cr

This should resolve the errors.

Visit the OpenY Upgrade Tool Dashboard

Review and revert or apply updated configuration versions after the upgrade.

Check for Regressions/Run Smoke Tests

Perform smoke tests to identify regressions after the upgrade. The YMCA Website Services team maintains a smoke tests database document to assist with this process.

Backup the Updated Site

Use drush sql-dump or another backup tool to create a backup of the site in its current state.

Proceed to the Next Version (Repeat from Step 1)

Repeat these steps to upgrade to the next desired version.