WebGUI - Upgrading WebGUI - Content Management System | CMS | Open Source Content Management | Web Application Framework

Upgrading WebGUI is relatively simple. It is simply a matter of copying some files and running the upgrade scripts for the database.

Upgrade History

If you want to see what patches have been applied to your WebGUI install, the upgrade utility can tell you that. Simply run this command:

cd /data/WebGUI/sbin
perl upgrade.pl --history --doit

How Upgrades Work

Upgrades in WebGUI work by applying incremental patches to your existing WebGUI site. You first start by copying the new WebGUI distribution over the top of your existing one.

NOTE: This will overwrite any files you've customized including preload.perl.

Then you start applying the data patches using the methods described below. This applies each patch to each of your WebGUI site's data since your last upgrade to make your data compliant with the new version of the code. So if you're upgrading from 5.0.2 to 6.0.3 there might be several dozen patches applied to your site's data. It then repeats this process for every site you have configured. If you have a lot of sites, or you don't upgrade very often, the upgrade process can take a long time. So be prepared for down time.

NOTE: If have not upgraded in a while, you may find that you will have to upgrade in more than one step at a time. This is because the upgrade scripts supplied with a particular version of WebGUI do not go back beyond the previous major release. For example, you can NOT upgrade directly from 7.3 to 7.5 because the upgrade scripts that come with 7.5 only cover the 7.4 versions. You will first have to upgrade from 7.3 to 7.4 using the scripts that come with WebGUI 7.4.40 (the last stable 7.4); once that is complete you can upgrade to your chosen version of 7.5 using the upgrade scripts that come with it.

A list of Stop Versions is being compiled, but is not complete yet.

Beta Upgrades and Target Versions

If you are on the beta branch, you should assume that every upgrade needs to run on the upgrade target version. For example, if you are running the upgrade-7.5.5-7.5.6.pl upgrade script, you should make sure your codebase is as version 7.5.6 (and not something higher like 7.5.7) before running the upgrade. If you want to upgrade over several versions you need to repeat this process manually. This is because upgrades make use of the WebGUI API, which is dependent on the current codebase version.

You can assume that the API is stable enough in the Stable branch for the above rule to not apply. If any such cases arise they will be explicitly mentioned in the gotcha.txt file.

Preparing for the Upgrade

The first thing to do is to find out if a new version of WebGUI is available. You can do this quickly and easily three different ways:

From your web site go to Admin Console > Statistics and it will tell you what version you are running, and what the latest version is.
Visit getwebgui.com, which always has the latest version.
Read the gotcha file. If it lists any perl mods that you need, you can run testEnvironment to make sure that you have them already. Or you can upgrade to the latest wre and you can be sure to have them then.

Backups

Before you ever perform an upgrade, always run a complete backup of your environment. Usually upgrades will go smoothly, but if it doesn't, you're going to want a full backup so you can restore anything and everything.

Upgrade Options

After you've found out if there is an upgrade, and have decided to upgrade, there are two ways to do it. First, if you're using the WRE you can use WebGUI Update, which is an automated upgrade system. If you did a source install, you can do a manual upgrade.

WRE WebGUI Update (Automatic)

To use WebGUI Update go to the command line, and then do the following: ( NOTE: if you are running a pre-7.6.35 WG site, then do a manual upgrade to 7.6.35 ~before~ you do an automatic upgrade -- see gotcha.txt for details )

Set your environment

source /data/wre/sbin/setenvironment.sh

Stop Spectre

/data/wre/sbin/wreservice.pl --stop spectre
Run WebGUI Update and follow the onscreen instructions.

/data/wre/sbin/webguiupdate.pl | tee output.txt
Restart Apache

/data/wre/sbin/wreservice.pl --restart web
Start Spectre

/data/wre/sbin/wreservice.pl --start spectre

Manual Upgrade

To perform a manual upgrade, run the following steps:

Download the new version of WebGUI.
Decompress the new version of WebGUI.
Read the WebGUI/docs/gotcha.txt file to see what you should know about before upgrading. Follow any instructions in there.
Read the WebGUI/docs/changelog/7.x.x.txt file to see what has changed since your current version.

Stop Spectre.

cd /data/WebGUI/sbin

perl spectre.pl --shutdown

Decompress the new version of WebGUI over the top of the old version of WebGUI
```
cd /data
```
```
tar xvfz /path/to/webgui-x.x.x-stable.tar.gz
```
From your server command line run the following command to find out your local version and the latest:
```
cd /data/WebGUI/sbin
```
```
perl testEnvironment.pl
```
Restart Apache
```
apachectl restart
```
Run the upgrade
```
cd /data/WebGUI/sbin
```
```
perl upgrade.pl
```
Note that the above command won't work directly. You need to read the output of the upgrade script to find out how to make it work. This is our way of ensuring that you're not blindly following instructions without knowing what you're getting into.
Restart Apache again just for good measure.

Start Spectre

cd /data/WebGUI/sbin

perl spectre.pl --daemon

Run testEnvironment.pl

cd /data/WebGUI/sbin

perl testEnvironment.pl

Test your site(s) to make sure everything is working.