General Upgrade Process

From AlfrescoWiki

Jump to: navigation, search

Contents

[edit] Background

Upgrades are only safe to do between officially released versions of Alfresco. This does not include preview or beta releases or custom builds out of SVN.

Always perform a test upgrade using a backup copy of your production repository before doing the upgrade "for real".

To upgrade to the latest release, Alfresco recommends that you upgrade through all official intermediate releases. For release 1.4 and later, you can upgrade directly to the latest release.

Note: Before starting any upgrades, ensure your backups are up to date. It is usually a good idea to do a dry run on a copy of the production data before attempting final upgrade.

[edit] The Upgrade Process

The recommended process for upgrading involves a new installation of the Alfresco binaries and configuration and an in-place upgrade of a copy of the repository. In-place upgrade of the Alfresco binaries and configuration is not recommended.

In detail, this involves:

  1. Validate that your platform is still on the supported stack for the new version of Alfresco
  2. Shutdown your existing Alfresco instance, including any virtualisation servers and file system receivers. Alfresco Runtimes may be left running and upgraded at a later time using this same process.
  3. Backup your repository, as described at Backup and Restore#Backup
  4. Install the new version of Alfresco (including any virtualisation servers) in a different directory to the existing installation
  5. Validate the new installation using a blank repository:
    1. Configure the new installation with a new repository (not the existing one)
    2. Start Alfresco and validate that the system works correctly
    3. Shutdown Alfresco and (optionally) wipe the new repository
  6. Restore the backup taken in step 3 into the new repository (not the existing one)
  7. Manually reapply any configuration changes to the new installation (changes in the <shared>/classes/alfresco/extension directory)
  8. If you have any customisations (AMPs, patches etc.) in your existing Alfresco installation:
    1. Recompile all Java code against the new version of Alfresco and regression test against the new version of Alfresco (this is best done prior to the upgrade itself, since it could be a lengthy exercise)
    2. Reinstall all customisations into the new Alfresco instance
  9. Start Alfresco, monitoring the startup log messages for information on the status of the upgrade
  10. Validate that the system works correctly
  11. If all goes well, remove the old Alfresco installation and repository (may be done at a later time, once the new installation has been thoroughly validated)

[edit] WCM-Specific Upgrades

[edit] Deployment Across Versions

Alfresco does not guarantee that deployment from one version of Alfresco to another (eg. from a 2.2.0 authoring environment to a 2.1.2 runtime environment) will function correctly, and so you should plan your upgrade such that an authoring instance and all of its dependent runtimes (both Alfresco Runtimes and FileSystem Receivers) are upgraded at the same time. Note that provided you avoid deployment, these components do not all need to be taken offline, upgraded and brought back online at exactly the same time - you can use a rolling upgrade process thereby avoiding downtime on your site.

Note that for the purposes of upgrade, virtualisation servers are considered to be an integral part of the authoring system and must be upgraded in lock-step with the main authoring Alfresco instance(s).

[edit] Upgrading an Alfresco Runtime

If you have Alfresco Runtimes in your environment, they should be upgraded using the same process described above. Note that this process does require downtime, so to accomplish an interruption-free upgrade, you will need to have configured at least two Alfresco Runtimes, and upgrade each of them separately (so that at least one remains online at all times).

[edit] Upgrading a FileSystem Receiver

If you have FileSystem Receivers in your environment, they should be upgraded using the same general process (new installation of file system receiver in different directory, manually reapply configuration changes, in-place upgrade of a copy of the depmetadata, deplog, depdata and target directories).

[edit] Upgrading a Cluster

If you've configured an Alfresco cluster, you should shut down all nodes in the cluster, then perform the above steps on each node in turn (ensuring that you let each node start fully before restarting the next one). Note that you'll only need to copy the database once - it will be upgraded by the first node to be upgraded (the other nodes will detect that it's been upgraded and skip the database upgrade step).

[edit] In the Event of an Upgrade Failure

The startup log is very important to help Alfresco Support diagnose any issues that might arise as a result of the upgrade. Immediately after startup, make a copy of the alfresco.log file. All SQL statements that are executed by the upgrade are written to temporary files as well - make a copy of these temporary files immediately after startup and submit them along with the log file to Alfresco Support. The locations of the temporary files containing the SQL statements are written to alfresco.log.

[edit] Rolling Back

By in-place upgrading a copy of the repository, the process described above ensures that rolling back to the previous version in the event of an upgrade failure is quick and painless (the original installation, configuration and repository are untouched by this process, so it can simply be restarted). This process also allows for the upgrade to be re-attempted any number of times; simply restart the process at step 6.

Retrieved from "http://wiki.alfresco.com/wiki/General_Upgrade_Process"