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.
- 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:
- 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
--
PeterThoeny - 01 Feb 2002
--
MartinRaabe? - 15 Jan 2003