HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Tutorial: Performing an upgrade

Written by Chris Graham, ocProducts
This tutorial will give background information for this process of upgrading ocPortal. The ocPortal upgrader does step you through the process, but further information will be given here so that you may gain a further understanding.


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. You can see the fixes included in a release by looking at the bugs database for the release before it.

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.
  • Non-bundled addons may no longer function.
At the same time, bear in mind that fixes to security holes are not always back-ported to older releases, especially if a newer feature/major version has been out for a while. So ideally you should not stick around on old versions too long. If you want to avoid upgrading but also need to keep your site secure, you should strongly consider getting ocProducts support so that you can be kept up-to-date manually.

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 an inconsistent state then you can download the TAR file yourself, extract it manually, and then continue; this is not ideal but the file integrity check should help remove files from uninstalled bundled addons that don't belong
  • 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 from non-bundled addons
    • 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
    • removing any files relating to bundled addons that you have previously uninstalled
  • upgrading your database; this is the most key step, which upgrades all modules and blocks, as well as doing some cross-system updates, and updating OCF – if any errors happen they'll be displayed and you should note them down and report them, but ocPortal will generally try and continue anyway if there are minor errors happening
  • performing an automatic theme upgrade (if available for the version jump you're doing)
  • clearing caches
  • re-opening your website

Browser cache

Often browsers will cache CSS and Javascript files, even when changed on the server. Usually completely restarting the browser will make it recheck cache times. If you get Javascript errors after upgrading, chances are fair that you need to empty your browser cache.

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.

Concepts

upgrader.php
The script that manages the upgrading process

See also