TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Feb-2003 production release to TWiki 01-Sep-2004


This guide describes how to upgrade from TWiki 01-Feb-2003 to TWiki 01-Sep-2004. This is a major new release. You can chose between an automated upgrade using a script or a manual update.

Upgrade Requirements

Major Changes Compared to TWiki 01-Feb-2003

Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

With the 01-Sep-2004 Release, for the first time, comes a helper script for upgrading from a previous version. This feature is currently at beta stage, it has only been sanity tested under Unix. It should be worth giving it a try, it won't mess up your existing TWiki installation because it leaves that untouched.

If you would prefer to do things manually than trust a beta script, skip to the manual upgrade procedure below.

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution.

It will:

To perform the upgrade, you need to:

Assuming all goes well, UpgradeTwiki will give you the final instructions.

There are a few points worth noting:

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTwiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Feb-2003 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.

  1. Back up and prepare:
  2. Update files in TWiki root:
  3. Update template files:
  4. Update script files:
  5. Update library files:
  6. Update data files:
  7. Adapt the other webs (all other than TWiki and _default):
  8. Update pub files:
  9. Verify installation:

Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure TWiki.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/TWiki.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.

Known Issues

-- TWiki:Main.PeterThoeny - 29 Aug 2004