Upgrading WebGUI

A History

• First release: WebGUI 0.9.0, August 16 2001

• 7 major versions and countless bugfixes and improvements

• Continues pushing forward in the CMS world

• Innovation sometimes requires change

upgrade.pl

• WebGUI/sbin/upgrade.pl

• Changes to the database schema or other changes requiring logic / executable code

• Linear upgrade path since 0.1.0

• Plainblack.com has been going since then

The Easy Way

The Easy Way

• webguiupdate.pl

• Included with the WRE

• Will download and install the WebGUI you specify, then run the upgrade script

• Automatically backup your old WebGUI source

The Easy Way# . /data/wre/sbin/setenvironment.sh# webguiupdate.plChecking for existing install: Upgrading

There is already an installation at /data/WebGUI. Are you sure you wish to perform the update? {y|n} [y]

Would you like to back up your existing files before we do the update? {y|n} [y]

Where would you like to store your backups? [/home/doug]Backing up files: OK

The Easy WayHave you already downloaded WebGUI or should I get it from the Internet? {local|mirror} [local] mirrorGetting current WebGUI version: OK

Which version do you want to install? [7.4.8-stable]Getting mirrors list: OK

plainblack = Houston, TX

Which server would you like to download from? [plainblack]Downloading from mirror: OKDecompressing WebGUI archive: OK

The Easy WayOften an upgrade will come with gotchas to let you know about things you should deal with before and after the upgrade. Would you like to read the gotchas now? {y|n} [y]

Press ENTER to page down. Type 'quit' when you're done reading.<< READ THE GOTCHAS >>quit

Do you want me to start the upgrade script? {y|n} [n]<< UPGRADE SCRIPT OUTPUT>>Finished!

# wreservice.pl --restart modperl spectre

The Traditional Way

The Traditional Way• For those who don't use

the WRE

• Get the new release

• update.webgui.org

• Grab the latest -stable or -beta

• While it's downloading....

http://update.webgui.org

Make a Backup!!

• mkdir /data/backup

• The old codebase

• The sites' files

• The sites' databases

tar czf /data/backup/WebGUI.tar.gz /data/WebGUI

tar czf /data/backup/domains.tar.gz /data/domains

mysqldump -u'' -p'' --all-databases > /data/backup/database.sql

The Traditional Way

• Once our new WebGUI is downloaded...

• Extract archive to /data/WebGUI

• Overwrites the current WebGUI

• Server is still running with the old code

• Running the new WebGUI before we perform the upgrade can cause problems

Prepare to Upgrade

• Read the gotchas!

• WebGUI/docs/gotcha.txt

• Notes on issues that may occur with the upgrade

• Notes on new Perl modules that may be required

Prepare to Upgrade

• Run testEnvironment.pl

• cd /data/WebGUI/sbin

• sudo perl testEnvironment.pl

• Checks to make sure we have all the modules needed

• Will ask if you want to install missing modules automatically

Prepare to Upgrade

• Sometimes installing modules can fail

• "make test failed -- Won't install without force"

• Force install modules using CPAN

• cpan -- The CPAN shell

• force install <module name>

• Will run the tests again, but still installs after they fail

Upgrade!

• We've backed up and verified our environment

cd /data/WebGUI/sbinperl upgrade.pl

• A warning message you should heedOr else you'll be messed up indeed

Upgrade!

• Upgrades each site individually

• Puts up the Maintenance Mode screen while the upgrade is being performed

• Lots of text scrolling by rapidly

• If you see an error, stop the upgrade and restore

perl upgrade.pl --doit

What, Me Error?

What, Me Error?

• Could not execute prepared statement ...

• Could be a problem with the MySQL server permissions

• Could be we didn't stop at one of the required upgrade steps

• 6.2.11, 6.8.9, 7.3.22

What, Me Error?

• Permission Denies

• A problem with the user permissions on the server.

• Make sure the files are owned by the right user ("webgui") and can be read, written, and executed by that user.

• /data/domains/*/public

• /data/wre/var

What, Me Error?

• Can't locate <...>.pm in @INC

• We aren't running upgrade.pl from WebGUI/sbin

• We forgot to run testEnvironment.pl

• We aren't running with the correct environment

• . /data/wre/sbin/setenvironment.sh

What, Me Error?

• Couldn't locate object method ...

• Wrong version of collateral modules

• Run testEnvironment.pl

• Missed an upgrade step

• 6.2.11, 6.8.9, 7.3.22

Most Likely Scenario

• Everything's A-OK

• Each site is upgraded in turn, with a friendly blue "Down for Maintenance" screen during the time it's upgrading

• In the unlikely event of a fire...

Restore From Backup

Restore From Backup

• Immediately shut down the web server

• But not the MySQL server

• Shut off any monitoring

• Edit root's crontab and comment-out the wremonitor.pl

Restore From Backup

• Restore the WebGUI sourcerm -rf /data/WebGUItar xzf /data/backup/WebGUI.tar.gz

• No need to specify a destination, since we made the archive using absolute paths

• Restore the domains directory

rm -rf /data/domainstar xzf /data/backup/domains.tar.gz

Restore From Backup

• Restore the databasesmysql -u'' -p'' < /data/backup/database.sql

• Delete the cacherm -rf /tmp/WebGUICache

• Restart and test

Pre-release Patches

Pre-release Patches

• Software has bugs

• Bugfixes are added to the next release

• Could be days, weeks, months away

• Get a bugfix before the release

• "diff" or "patch" file

• Posted to the bugfix thread

• http://webgui.org/bugs -- If not, ask

A Sample Patch File--- lib/WebGUI/Operation/Profile.pm+++ lib/WebGUI/Operation/Profile.pm@@ -304,6 +304,9 @@ if ($session->user->userId eq $session->form->process("uid")) { $vars->{'profile.accountOptions'} = WebGUI::Operation::Shared::accountOptions($session); }+ else {+ push(@{$vars->{'profile.accountOptions'}}, {'options.display' => '<a href="'.$session->url->page('op=sendPrivateMessage;uid='.$session->form->process("uid")).'">'.$i18n->get('send private message').'</a>'});+ } return $session->style->userStyle(WebGUI::Asset::Template->new($session,"PBtmpl0000000000000052")->process($vars)); }

How to Use Patches

• Make a directory to hold the patches

mkdir /data/WebGUI/patches

• Name the patch with the WebGUI version it will be included in and a short description

• Since this patch is in 7.4.6, we'll name it 7.4.6-operation-profile.patch

• When we upgrade to 7.4.6, we can delete this patch

How to Use Patches

• Apply the patch

cd /data/WebGUIpatch -p0 < patches/7.4.6-operation-profile.patch

• If there were no ---/+++ lines, you must specify the file to patch

cd /data/WebGUIpatch lib/WebGUI/Operation/User.pm < patches/7.4.6-operation-profile.patch

How to Use Patches

• Results of the patch program

• No results is a Good Thing

• Hunk ## SUCCEEDED at ...

• Also a good thing

• Means the code wasn't found at the exact place, but it WAS found

How to Use Patches• Hunk ## FAILED

• A Bad thing

• The patch failed

• Backup with a .orig extention

• Try to resolve the patch manually using the .rej file

• Patch was corrupt or made for a different version of WebGUI

• Restart and test

Future Considerations

Future Considerations

• Separate -stable and -beta branches

• -stable will always remain stable

• -stable will always get new bugfixes

• Only -beta will get new features

• No more waiting for bugfixes!

Future Considerations

• Patch-based upgrades

• No more “upgrade steps” (6.2.8, 6.8.9, 7.3.22)

• Immediate bug-fixes (no waiting for release to fix a bug)

• Pick and choose new features from -beta

• Currently under development

Conclusion

• Relatively simple and painless

• Main focal point of the 7.x series

• STABILITY

• Ensure WebGUI remains the best F/OSS enterprise CMS available

Questions?