TWiki Upgrade Guide

TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003

Overview

This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version.

Upgrade Requirements

To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below.

NOTE: To upgrade from a pre-01-Dec-2001 TWiki, start with TWikiUpgradeTo01Dec2001.

To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.

Major Changes from TWiki 01-Dec-2001

Form and script to create new webs
Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule: readTopicText, saveTopicText, setTopicEditLock, checkTopicEditLock
New Plugin hooks registrationHandler, beforeEditHandler, afterEditHandler, beforeSaveHandler, writeHeaderHandler, redirectCgiQueryHandler, getSessionValueHandler, setSessionValueHandler
Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
Possible to omit e-mail address in WebNotify, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite)
New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in %SEARCH{}% variable, FormattedSearch and WebSearch
Many more enhancements, see the complete change log at TWikiHistory

Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release

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

Back up and prepare:
- Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates, $TWIKIROOT/lib.
- Create a temporary directory and unpack the ZIP file there.
Update files in TWiki root:
- Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
Update template files:
- Overwrite all template files in $TWIKIROOT/templates with the new ones.
  - If you have customized your templates, make sure to merge those changes to the new files.
- If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files.
- Specific changes to templates and skins:
  - Replace %WIKIHOMEURL% with %WIKILOGOURL%
  - Replace img tag's src=%PUBURLPATH%/wikiHome.gif with src=%WIKILOGOIMG%
  - Replace img tag's alt="TWiki Home" with alt="%WIKILOGOALT%"
  - Replace meta tag's charset=iso-8859-1" with charset=ISO-8859-1"
  - Add %TOPIC% to form action of GoBox
  - For internationalized sites, URL encode webs and topics in all form actions, e.g. replace .../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%" with .../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%
Update script files:
- Overwrite all script files in $TWIKIROOT/bin with the new ones.
  - If necessary, change the script names to include the required extension, e.g. .cgi
- Edit $TWIKIROOT/bin/setlib.cfg and point $twikiLibPath to the absolute file path of $TWIKIROOT/lib
- Edit $TWIKIROOT/bin/.htaccess to include a directive for the new manage script:
  <Files "manage">
  require valid-user
  </Files>
- Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
- If on Non-Unix host, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook.
Update library files:
- Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one.
- Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server".
- Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
- Copy and overwrite all subdirectories below $TWIKIROOT/lib with the new ones. Make sure to preserve any extra Plugins you might have in $TWIKIROOT/lib/TWiki/Plugins
- Pay attention to the file and directory permissions, the library files should not be executable, e.g. chmod -R 664 $TWIKIROOT/lib/*
Update data files:
- Run the bin/testenv script from the browser (e.g. http://localhost/bin/testenv) to verify if the cgi-scripts are running as user nobody.
  - In case not: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g. www-data:
  - Change the lock user in the temporary twiki/data/* directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
    for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
- In the temporary twiki/data/TWiki directory where you unzipped the installation package:
  - Remove the files you do not want to upgrade: InterWikis.*, TWikiRegistration.*, TWikiRegistrationPub.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
- Rename in the temporary directory the file $TWIKIROOT/data/TWiki/TWikiPreferences.* to TWikiPreferencesSave.*.
- Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory, overwriting the existing ones.
- Merge your original TWikiPreferencesSave.txt settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt.
- Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory.
- Move the data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory
  (The Test web has been renamed to Sandbox in this release.)
  - There are now two webs in parallel (Test and Sandbox) for the purpose of testing (experimenting) TWiki.
    Move all relevant topics from Test web to Sandbox web, or motivate the users to do.
- Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user.
Adapt the other webs (all other than TWiki and _default):
- Merge the new files WebHome.txt and WebPreferences.txt of your other webs to make sure, you have the improvements applied also in your other webs.
Update pub files:
- Move all subdirectories below pub/TWiki from your temporary directory into your $TWIKIROOT/pub/TWiki directory.
- Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user.
- Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory.
Update TWikiPreferences to authorize users to create webs:
- Add ALLOWWEBMANAGE to the FINALPREFERENCES list so that nobody can overwrite the setting:
  - Set FINALPREFERENCES = WIKIWEBMASTER, PREVIEWBGIMAGE, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE
- Set users or groups allowed to create new webs:
  - Set ALLOWWEBMANAGE = TWikiAdminGroup
Verify installation:
- Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; fix any potential problems.
- Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users.
- Test if the installed Plugins work as expected. You should see the list of installed Plugins in TextFormattingRules.

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

Check TWiki:Codev/KnownIssuesOfTWiki01Feb2003 for known issues of TWiki 01-Feb-2003 production release