Upgrading to Alfresco 5 – Keys to Success

With the recent release of Alfresco 5 Enterprise, many clients are beginning to plan to upgrade to the latest version of Alfresco in the coming months.  On January 8th, TSG participated in an Alfresco Tech Talk Live Session that focused on upgrading to Alfresco 5.  Alfresco Tech Talk Live is a regularly scheduled webcast where a panel of subject matter experts discuss various topics related to Alfresco.  A recording of the Alfresco 5 Upgrade session can be found here.  A complete list of Alfresco Tech Talk Live sessions can be found here.

During the session, some key points were brought up that contribute to the overall success of an Alfresco upgrade.  This post will discuss 5 of those factors in more detail.

Those of us who have performed an Alfresco upgrade know that there’s a lot more involved than just running an executable to install patches.  The upgrade process typically involves performing a clean install of the new version of Alfresco, migrating configurations and customizations to the new version of Alfresco, and finally pointing the new version of Alfresco at the existing database and content store.  For heavily customized systems, upgrading Alfresco can be a lengthy process requiring time for planning and testing.

The tips below come from lessons that we’ve learned over the years when performing Alfresco upgrades.  Admittedly, some of them were learned the hard way…

1.  Take Inventory of Configurations and Customizations

Part of the Alfresco upgrade process is moving configurations and customizations from the old version of Alfresco to the new version.  It’s important to take an inventory of all of the configurations and customizations in your Alfresco installation ahead of time.  Most configurations can be easily ported into the new version of Alfresco, but if they haven’t been identified in advance, it’s just as easy to forget them.  If your system has customizations, it’s important to verify that the customizations are compatible with the new version of Alfresco, and to recompile them against the new version of the Alfresco SDK.

A complete inventory of Alfresco configurations and customizations is also a great guide for helping determine what functionality needs to be tested after the upgrade is completeFrom our experience with upgrades, out-of-the-box Alfresco functionality typically requires very little testing after an upgrade, but customizations should be thoroughly tested to ensure compatibility with the new version of Alfresco.

Don’t forget to hang on to your inventory of configurations and customizations because the list can help you kick start future Alfresco upgrades as well.

2.  Validate Supported Stack

 It’s really tempting to dive head first into an Alfresco upgrade, but it’s critical to first validate that the database, OS, browsers, etc. are supported with the new version of Alfresco before proceeding with the upgrade.  It’s common for Alfresco to drop support for some components and add support for others, especially when major versions are released.  It’s important to stay on a supported stack in order to ensure that Alfresco can provide support for any cases that you log via the support portal.  A complete list of the Alfresco supported stacks can be found here.  Note that significant changes to the supported stacks have come with the release of Alfresco 5.

3.  Document the Process

Upgrading Alfresco can be a lengthy process.  Alfresco provides good documentation for performing upgrades, found here, but every upgrade is different.  Some of the steps may be relevant for your environment, and others may not.  Documenting the upgrade process as you perform it will not only help ensure that that all of the appropriate steps are taken in all environments (development, test, production, etc.), but it will also help future upgrades go more quickly.  Since the process does not change much between versions, your documentation can likely be reused.

4.    Test on a Clone of Production Data

Even if you have non-production Alfresco environments (development, test, etc.), we recommend performing an Alfresco upgrade on a clone of the production data prior to performing the actual production upgrade.  From experience, we’ve seen successful upgrades in non-production environments still lead to issues when upgrading production.  Because of differences in the type and amount of data in production, sometimes unforeseen errors can occur.  For example for one client, upgrading Alfresco required a full re-index in Solr, and during the upgrade the system ran out of memory due to the amount of data in the production repository.  The out of memory error was not encountered during the upgrade in the test environment because the amount of data in the test environment was only 5% of what was in production.

Testing on a clone of production data also has the benefit of giving you an idea of how long the production upgrade will take.  If the upgrade runs more slowly than is acceptable for production, steps can be taken in advance to optimize the process (database tuning, more CPU/RAM, etc.).

5.  Have a Backout Plan

No matter how much planning you do for an Alfresco upgrade, there’s always a possibility that things will not go as expected when upgrading a production environment.  It’s important to have a plan in place for backing out the upgrade if things do not go well.  If you’re working in a virtual environment, the quickest way to back out an upgrade is to create a snapshot of the VM, database, and content store before starting the upgrade, and reverting back to the snapshots if necessary.

Hopefully this list of tips is helpful in planning your upgrade to Alfresco 5.  Please feel free to add comments below.