Introduction to Bloomreach Content Upgrades

Upgrade your Bloomreach Content project regularly to access new features and improvements.

Major Upgrade vs. Minor Upgrade

Bloomreach Content upgrades are categorized as major or minor.

A major upgrade updates your project to a new Bloomreach Content release with a higher major version number (for example, from 13.4 to 14.0).

A minor upgrade updates your project to a release with a higher minor (for example, from 13.3 to 13.4) or patch version number (for example, from 13.4.3 to 13.4.4).

Minor upgrades are designed to be backwards compatible and include bug fixes and minor improvements. Major upgrades may require changes to your environment, project code, and configuration.

Info: Starting with v16.6.0, Bloomreach applies a new Incubating Features and Extension Points Policy. This policy may introduce backward incompatibility in minor versions. For details, see the Incubating Features Policy.

For minor upgrades, follow the generic instructions for minor upgrades.

For major upgrades, only a stop/start deployment model is supported. Stop all cluster nodes before starting any nodes running the new major version.

System Requirements

System requirements may change with major releases. Review and verify that your system and infrastructure meet the requirements before upgrading.

Configuration Verifier

Bloomreach provides the Configuration Verifier tool with every release. Use the Configuration Verifier both before and during the upgrade process to validate and compare your project's bootstrap configuration against the current repository (database). The tool reports differences without applying changes, allowing you to identify and address unintended changes before deployment.

Fitness for Upgrade

Maintaining your project’s upgrade readiness reduces the cost and risk of upgrades. Regular upgrades also help your team retain the knowledge needed for efficient upgrade processes.

Upgrade readiness includes:

Project sources
Project configuration

Do not combine new feature development and deployment with an upgrade. Prepare for upgrades by ensuring your project is in a state that supports a smooth upgrade process.

Project Sources

To keep your project sources upgrade-ready:

Minimize project size. Less code means less to upgrade. Remove unused code and resources; your version control system retains history.
Avoid deprecated classes.
Avoid code forks. If a feature requires forking Bloomreach Content code, contact Bloomreach to discuss alternatives. Bloomreach may extend the CMS to support your requirements without forking.
If forking is unavoidable, document the version, origin, and reason for the fork. Note if the fork is temporary and under what conditions it can be removed. Reference JIRA issues if relevant.
Keep repository data organized. Avoid including data that could disrupt production content or configuration.
Use Maven dependency version overrides sparingly. Regularly review and remove unnecessary overrides. Document the reason for any overrides to simplify future maintenance.

Project Configuration

Project configuration is stored in the JCR repository. Unlike source code, configuration can change at runtime. Upgrades may overwrite or delete runtime configuration. Ensure all project-specific configuration changes are included in your repository data to prevent data loss during upgrades.

For example, if you adjust a configuration property in the JCR repository after deployment, also update your configuration sources. Otherwise, a future upgrade may overwrite your change. Use the Configuration Verifier to identify such runtime changes and incorporate them into your configuration sources.

The Configuration Verifier helps you detect runtime configuration changes at any time, not just during major upgrades.

Testing the Upgrade

After upgrading, verify that all project features work as expected. Automated end-to-end tests are valuable for documenting and validating feature correctness. If you rely on manual testing, prepare a dedicated set of content and configuration for testing in a development environment. Keep this test set small for faster bootstrapping but comprehensive enough to cover all features. Store test resources in a separate Maven module to exclude them from production deployments.

General Upgrade Steps

Step 1: Reconcile Current Runtime Configuration Changes

Before starting the upgrade, merge any current runtime configuration changes into your project configuration sources.

Use the Configuration Verifier as described in the Using a production repository database section. Run the tool against your current project source tree and a recent backup of the production repository database. Reconcile and merge relevant runtime changes into your project source tree (such as the 'master' branch) to establish a new baseline before making upgrade changes.

Step 1.a: Update to the Latest Minor and Patch Release of the Current Major Version

Before upgrading to a new major version, update your project to the latest available minor and patch release of your current major version. For example, if you are on v13.3.0, update to v13.4.1 first.

Review the release notes for important update information, even though minor and patch releases are intended to be backwards compatible.

Step 2: Create and Back Up a Local Upgrade Baseline Repository Database

After completing step 1, build and start your updated project baseline to create a new local (development) repository database. This database serves as your baseline for comparison after the upgrade (see Step 5).

Use a local H2 database for convenience, as it is easy to copy and back up at the filesystem level. Label and store the backup appropriately. This is your baseline repository.

Step 3: Review Target Version Documentation and Upgrade Instructions

Read the overview of Significant Changes, version-specific documentation, and Upgrade Steps for the target Bloomreach Content version.

Step 4: Upgrade Project Sources (Code and Configuration)

Follow the target version’s Upgrade Steps to update your code and configuration.

Remove or replace any classes deprecated in the target version.

After making the required changes, verify that the project starts locally without bootstrap errors using a new (empty) repository database. Some warnings may be acceptable at this stage.

Hint: If you encounter issues aligning your project-specific changes with the standard product configuration:

Create a separate 'vanilla' project using the target version archetype.

Use Essentials to update the project to Bloomreach Content.

Add only the additional product modules and dependencies used by your real project.

Do not add your own custom dependencies or changes.

Run and review this 'vanilla' project and its configuration (use the Console if needed) to identify differences with your real project.

Compare the sources of the 'vanilla' project and your real project using a tool like Meld, focusing on Maven (pom.xml) and bootstrap configuration (yaml) files. Resolve conflicts as needed.

Step 5: Verify Upgraded Project Configuration Against the Local Baseline Repository

Assuming you have a local baseline repository from Step 2 and your updated project starts without bootstrap errors, use the Configuration Verifier to compare the upgraded configuration against the baseline.

Refer to the Using a development repository database section for details.

Review all reported configuration changes. Validate, accept, or explicitly ignore each change to prevent functional errors or configuration data loss in production.

Step 6: Test the Upgraded Project Locally

Test the upgraded project both technically and functionally in your local or development environment. Automate tests where possible. Proceed to the next step only after all tests pass.

Step 7: Verify the Upgraded Project Configuration Against the Production Repository

As a final step, run the Configuration Verifier against the most recent production repository database. This ensures that no unexpected configuration changes will occur when deploying the upgraded project.

This step is similar to Step 1 but focuses on verifying changes resulting from the upgrade. See the 2nd scenario in the Using a production repository database section for instructions.

Completing the Upgrade

After completing the steps above, release (tag) your project sources and deploy to an acceptance environment for final verification. Once validated, deploy the project to production.

Hint: For major upgrades, only a stop/start deployment model is supported. Stop all cluster nodes before starting any nodes running the new major version.