|
TWiki Upgrade Guide
|
< < |
Upgrade from TWiki 01-Dec-2001 to TWiki 01-Jan-2003 (previous to new full release)
|
> > |
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-Jan-2003. The new version involves several new features and numerous enhancements to the previous version.
|
> > |
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-Jan-2003 TWiki Production Release, follow the instructions below.
|
> > |
- To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below.
|
|
|
|
Major Changes from TWiki 01-Dec-2001
|
< < |
- AND Search - With regular expression enabled, use
";" as the AND operator in FormattedSearch and WebSearch
- (to be completed)
|
> > |
- 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
- 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-Jan-2003 Release
|
> > |
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.
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.
|
> > |
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 .
|
> > |
-
- 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.
|
|
- 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, ex:
.cgi
|
> > |
-
-
- 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
|
< < |
-
- Pay attention to the file and directory permissions, the scripts need to be executable, e.g. 775.
|
> > |
-
- 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:
|
< < |
-
- Make a backup copy of
$TWIKIROOT/lib/TWiki.cfg to TWiki.cfg.save
|
|
-
- 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, but set to e.g. 664.
|
> > |
-
- 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 :
|
> > |
-
-
- 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.* , WebNotify.* , WebPreferences.* , WebStatistics.* and all WebTopic* files.
- Rename
$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.
|
> > |
-
-
- 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 all
*.txt and *.txt,v files from the temporary data/_default directory to your $TWIKIROOT/data/_default directory.
- Move the
data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory.
|
> > |
-
- 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/TWiki 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.
|
> > |
- 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.
|
< < |
General Format Changes
|
> > |
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 - 17 Dec 2002
|
> > |
-- PeterThoeny - 01 Feb 2002
-- MartinRaabe? - 15 Jan 2003
|