ocPortal Tutorial: Performing an upgrade
Written by Chris Graham, ocProducts
This tutorial will give background information for this process of upgrading ocPortal. ocProducts does release basic details with the news pieces associated with a new release, but further information will be given here so that you may gain a further understanding.Table of contents
Types of upgrade
When the developers make a release they will state whether they recommend users upgrade to it. If they have corrected a security issue, or a major bug (such as one that causes data loss), they are likely to strongly recommend upgrade. We usually list the main changes made in a releases, but do not explicitly detail vulnerabilities as it makes it a bit too easy for casual hackers.Upgrades may be roughly categorised under:
- patch releases – these are likely to involve bug fixes, with very few, if any new features. Any new features would have been implemented solely to provide important functionality that was obviously missing. Patch releases are very easy to upgrade to
- feature releases – these are likely to include many new features; the quantity of new features will depend on the difference in version numbers between releases. Minor releases are usually easy to upgrade to
- or, major releases – these are likely to involve many architectural changes, as well as new features; major releases are less common, as they need to perform additional testing for them which takes a long length of time – they therefore try to avoid architectural changes other than in large batches
It is recommended that you do not 'jump over' major releases (e.g. v2 to v4, jumping over v3) that you do not feel you need (or did not have time to upgrade to), as the chance is higher of an upgrade process bug being present in unusual upgrade jumps. In theory, it should work without issue, as the process has been designed very carefully, but in practice, it is very easy for a very minor glitch to cause major problems that need manual resolution: in such an event, ocProducts would fix the problem, either directly, or by mass provision of a script, but it would be an inconvenience and could take some time.
Some words of caution
ocProducts cannot make any guarantees about the speed of which any new bugs might be patched, for any upgrade. It is your own responsibility to make and test a full website backup (files and database) before you upgrade, for use in the unlikely event of you wanting to revert your upgrade.Some users may wish to test upgrades (and pre-fix any theme compatibility problems that could occur) on a staging site (a private mirror of their live site).
Special note- multi-site-networks
If you are using OCF on a M.S.N. and upgrading to a new major release then you will need to upgrade all the sites together, starting with the one that hosts the forums.Special note- upgrading third-party forums
If you are using a third-party forum and upgrading that software, be sure to check that the ocPortal forum driver you are using is compatible with the new version. This is usually only an issue with major new releases of third-party software. If you need a new/upgraded forum driver, please contact ocProducts.Things to check in feature/major releases
Be aware that a number of things can change significantly across releases. Make sure you have a good understanding of how the following things may affect you, before making 'the jump':- Template and CSS structure could change considerably. Files may be renamed, reorganised internally, or things may just be completely rearchitected.
- Occasionally features may be deprecated.
- New features will be added, and that could possibly interfere with highly tuned layouts or site flows.
- Minimum requirements may have changed, for example a newer version of PHP may be required as a baseline.
- Third-party addons may no longer function.
The upgrade process
The upgrade process involves a number of stages (the upgrader will step you through this):- taking a full backup (just in case a problem occurs) – better safe than sorry. This is also useful in case you overwrite files that you have edited: either due to these files being in locations with no override support, or due to changes being made without using the proper override mechanism
- closing your website
- the upgrader will make it easy for you to close your site using the ocPortal closed-site feature
- however, for non-patch upgrades your website may return errors until the full upgrade process is complete, so you may wish to place your own closed.html file on the server that shows a standalone closed-site screen. ocPortal will redirect to that file for all page requests for as long as it exists on your server (so it does not need to load it's database or templating system)
- transferring new/updated files (this will copy your customised TAR upgrade file between ocportal.com and your server, and then extract it)
- if your server's connection to the ocportal.com server is slow, you could download the TAR file yourself, upload it to your own server, and then use that copy's URL in step 3
- on modern server environments the extraction happens in a separated framed process, so that if timeouts occur it can't leave your website in an inconsistent state
- if in the unlikely event that you do end up with a consistent state then you can download the TAR file yourself, extract it manually, and then continue
- resolve file integrity issues
- if you have made any ocPortal overrides in place you may need to change these overrides to be consistent with ocPortal's latest structure; or if the overrides came from addons, you may need to overwrite the addon(s) with a newer version
- the above guidance applies to totally new code also, such as new modules
- resolving any conflicts with templates, as necessary (for example, if there was a change in the verbatim version of a template, and the upgraded website had also changed that template, then changes might [depending on importance] need to be incorporated manually
- removing any files from previous versions of ocPortal that are no longer required
- upgrading your database
- clearing caches
- re-opening your website
Assistance
Upgrading is inherently complex, as it is close to programming in the sense that low-level changes are being made to the structure of the website. This is unfortunate but inevitable, and due to ocPortal's openly configurable and overridable (at the code level) nature, the developers would have an extremely hard time trying to automate the process beyond what the upgrade system (the stage launched by running upgrader.php) already does.If you require assistance for an upgrade, consider the Experts by the hour service.