Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
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.
Upgrade Paths For Alfresco Enterprise
Prior to release 1.4, Alfresco recommends that you upgrade through all official intermediate releases. For release 1.4 and later, you should use one of the following supported upgrade paths for Alfresco:
Please note that these are Alfresco Enterprise releases.
Target: Version 4.0
http://docs.alfresco.com/4.0/topic/com.alfresco.enterprise.doc/concepts/upgrade-path.html
Target: Version 3.0
- Version 2.1.5 to Version 3.0
- Version 2.1.5 to Version 2.2.1 to Version 3.0
- Version 2.2.0 to Version 2.2.1 to Version 3.0
- Version 2.2.1 to Version 3.0
- Version 2.1.6 to Version 3.0 (SP1)
- Version 2.1.6 to Version 2.2.2 to Version 3.0 (SP1)
- Version 2.2.0 to Version 2.2.2 to Version 3.0 (SP1)
Target: Version 3.1
- Version 2.1.7 to Version 3.1
- Version 2.2.3 to Version 3.1
- Version 3.0 to Version 3.1
- Version 3.0 SP1 to Version 3.1
Target: Version 3.2
- Version 2.1 SP7 to Version 3.2
- Version 2.2 SP5 to Version 3.2
- Version 3.1 SP1 to Version 3.2
- Version 3.1 SP2 to Version 3.2
- Version 3.2 to Version 3.2r
- Version 3.1 SP2 to Version 3.2r
- Version 3.1 SP1 to Version 3.2r
- Version 2.2 SP5 to Version 3.2r
- Version 2.1 SP7 to Version 3.2r
Target: Version 3.3
- Version 2.1 SP7 to Version 3.3.0 FCS
- Version 2.2 SP7 to Version 3.3.0 FCS
- Version 3.1 SP2 to Version 3.3.0 FCS
- Version 3.2 SP1.2 to Version 3.3.0 FCS
- Version 2.1 SP7 to Version 3.3 SP1
- Version 2.2 SP8 to Version 3.3 SP1
- Version 3.1 SP2 to Version 3.3 SP1
- Version 3.2 SP1 to Version 3.3 SP1
Target: Version 3.4
- Version 2.1 SP7 to Version 3.4 SP5 does not work directly. We used this path : Version 2.1 SP7 --> Version 3.3 SP5 --> Version 3.4 SP5
Note: Always perform a test upgrade using a backup copy of your production repository before doing the upgrade 'for real'. This not only ensures that the correct upgrade procedure is being followed, it also validates that backups are being taken correctly (see Backup and Restore).
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.
Note: If you have any customizations (AMPs, patches, and so on) in your existing Alfresco installation, 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).
The upgrade process involves:
- Shutdown your existing Alfresco instance, including any virtualization servers and file system receivers. Alfresco Runtimes may be left running and upgraded at a later time using this same process.
- Perform a cold backup of your repository, as described at Backup and Restore.
- Back up any configuration overrides from the <extension> directory.
Note: Do not copy the files. Copy only the override settings so that you will not overwrite the new extension files in the upgraded version.
- Install the new version of Alfresco (including any virtualization servers) in a different directory to the existing installation.
- Validate the new installation to check that it is working correctly. For example:
- Configure the new installation with a new repository (not the existing one).
- Start Alfresco and validate that the system works correctly.
- Shutdown Alfresco and (optionally) wipe the new repository.
- Restore the backup taken in step 2 into the new repository (not the existing one), as described at Restore procedure.
- Manually apply your backed up configuration override settings from step 3 into the relevant new override files in the <extension> directory. Ensure that you do not overwrite the new extension files.
- Reinstall all customizations (AMPs, etc.) into the new Alfresco instance.
- Start Alfresco, monitoring the startup log messages for information on the status of the upgrade.
- Update statistics for all tables in the Alfresco schema (note: consult a DBA for specific details on how to do this on your make and model of database). This may need to be done with Alfresco shutdown.
- Validate that the system works correctly.
- If you are satisfied that the upgrade is successful, remove the old Alfresco installation and repository. This may be done at a later time, once the new installation has been thoroughly validated.
WCM-Specific Upgrades
Deployment Across Versions
Alfresco does not guarantee that deployment from one version of Alfresco to another (for example, from a Version 3.2 Alfresco instance to a Version 3.1 runtime environment) will function correctly. You should plan your upgrade such that Alfresco and all of its dependent runtimes, both Alfresco runtimes, Deployment engines, and File System Receivers (FSR), are upgraded at the same time.
Note: If 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.
For the purposes of upgrade, virtualization servers are considered to be an integral part of the Alfresco authoring environment and must be upgraded in lock-step with the Alfresco authoring instance(s).
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).
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).
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 that's restarted (the other nodes will detect that it's been upgraded and skip the database upgrade step).
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.
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.
Upgrading
Administration
