create new tag
, view all tags
ALERT! NOTE: This is a HistoricalDocument topic. It used to be distributed in an earlier TWiki release, but is no longer part of the official TWiki distribution. Post questions, error notes, and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

ALERT! NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

TWiki Upgrade Guide

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


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.

  1. 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.
  2. Update files in TWiki root:
    • Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
  3. 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=%CHARSET%"
      • 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%"}%
  4. 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
    • 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.
  5. 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 but the directory files should be, e.g. chmod 664 `find -type f $TWIKIROOT/lib` (files) and chmod 775 `find -type d $TWIKIROOT/lib` (directories)
  6. 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.
  7. 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.
  8. 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.
  9. Update TWikiPreferences to authorize users to create webs:
    • Add ALLOWWEBMANAGE to the FINALPREFERENCES list so that nobody can overwrite the setting:
    • Set users or groups allowed to create new webs:
  10. 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

-- Contributors: PeterThoeny, MartinRaabe

Comments & Questions about this Supplemental Document Topic

Isn't a useful point of having code names so that they can be used in documentation (such as this topic) that links to one place rather than using dates that need to be changed? Am I missing something? I just changed two paragraphs above so far, but using the code names probably makes the most sense in documentation due to the static nature of the links it provides. The same process is used for the Debian release documentation.

I think all the references to a date for Beijing need to be replaced by Beijing so that documentation will not have to be updated after the release. I made one exception in the overview so that will need to be changed for the release. The topic headers need to remove the dates too. For consistency sake, keeping the date associated with Athens makes sense (since it's static), but getting folks onto a new scheme of using code names is useful.

-- GrantBow - 07 Jan 2003

Code names are used purely during development, the offical releases are named by date. Once a release is out, it gets two new topics in the Codev web, one for release info (e.g. TWikiRelease01Dec2001), the other for known issues (e.g. KnownIssuesOfTWiki01Dec2001). All releases are listed in Codev.TWikiReleases. Production releases have a date rounded to the first of the month, BeijingRelease will be 01 Jan 2003 (or 01 Feb 2003 if we have more delays in the docs).

-- PeterThoeny - 08 Jan 2003

So you want to have code names but not use them publically. OK. Perhaps I'm just wishing that a better versioning scheme was being used instead of dates. More and more references are made to different releases both before and during development. I fail to understand the logic of not using them for official release names as well. But It's not my call I guess.

I know for myself I will probably use the release names rather than dates. I can't remember dates very well.

There are also the moving monikers of Beta, Alpha and Release that are ultimately another seperate naming scheme for the same set of underlying releases. As a release moves from one temporary moniker to the other the Athens, Beijing, Cairo... names become more useful when you know what specifically what code base you are talking about. Each naming scheme has value and conveys meaning.

Regular versioning schemes such as major.minor.revision convey stability and as the numbers increase so does the awareness to all users instantly a rough guide of evolution of the code. Dates lack this useful connotation. TWiki has been stable for a very very long time. I don't know what other users think about the versioning system currently used. In my own personal experience with software the dated versioning schemes are generally used for versions that evolve very very quickly and/or are not very stable yet. I don't find either one applies to TWiki anymore though these might have applied early on.

I'm also more familiar with a choice of actually using code names publically from my Debian experiences and how useful I find it in that situation. Since the code name is the ONLY naming scheme that's constant during all time frames it has a usefullness that I have come to appreciate very much.

Oh well...

-- GrantBow - 09 Jan 2003

I think writing the corresponding KnownIssues topic only after release is a recipe for problems. Perhaps a document named Codev.BeijingKnownIssues could serve to capture the notations as development progresses. The contents can be copied to a new topic when the name of the release (and the topic) have been finalized.

-- GrantBow - 12 Jan 2003

I'd like to weigh in on the side of using the code names (Athens, Beijing, etc.) after the release as well.

Although I am not a TWiki core developer, or even a TWiki developer, I would like to push this issue a little if I can.

GrantBow has expressed some good reasons for using the code names on a continuing basis. (I think somewhere else I listed similar reasons some time ago.)

So far I have not heard reasons for the preference to use dates -- perhaps someone could express some of those?

-- RandyKramer - 12 Jan 2003

I'm also a Debian user/fan, and really like the way releases are tagged. They have Woody right now, which maps to Debian v 3.01a, Potato, which maps to Debian v 2.2, etc. At first people might be a little confused by the naming, but the nice thing about using codenames is thay also make easy to remember WikiNames. At the very top of BeijingRelease (or at the bottom, to follow the plugin versioning schema), you could have a summary box, with version, date of release, short list of new features, etc.

Also, it's much easier for me to remember a name than a specific date. wink

-- MikeMaurer - 13 Jan '03

Peter, the more I look at the amount of research required to update this document as you did for the previous release the more daunting this task seems to me. This is also a "release notes" collection. Since the last release was over a year ago and there are so many features I'll have to go through each topic on BeijingRelease one by one and pick out the details that apply to each section of this document. Is this what you had in mind when you asked me to do this? This really should have been written piece by piece as each feature was completed.

-- GrantBow - 14 Jan 2003

There should not be too many features that impact the upgrade. The TWikiHistory is not updated yet, once done (based on the Codev.Beijing list) it will give a good indication of changes.

Other points to investigate and possibly to add to the upgrade guide:

  • Change in format of WebIndex, WebPreferences, WebNotify, Web* in any web needed?
  • Test web is now Sandbox web. With the current upgrade guide steps you end up with both webs. Should be documented.

-- PeterThoeny - 15 Jan 2003

I have tested the Upgrade Guide on basis of the Athens release on a WinXP Apache host. It works fine. I made some additions to the text, but did not rearrange too much.

-- MartinRaabe - 15 Jan 2003

Thanks Martin,

Peter, my point was that in looking at past Upgrade Guides I see that this topic was also used as a ReleaseNotes page, listing detailed changes and feature descriptions. That means going through all the BeijingRelease stuff in some detail. So I'll surrender and ask: help!

-- GrantBow - 18 Jan 2003


-- GrantBow - 28 Jan 2003

Some minor changes made:

  • added $TWIKIROOT/lib to the first backup step; deleted later bullet in step 5 which said to back up lib/TWiki.cfg
  • edited to use consistant "for example" spelling throught out ("e.g.")
  • expanded the examples for changing file ownership, executableness (if that is a word), etc. Please verify I have typed the syntax correctly.

-- MattWilkie - 28 Jan 2003

Copying some comments to TWikiVersionNumberingScheme, and even if I'm not sure it's within scope for that other topic, I'm still copying yours as well, Peter! smile

  • I moved the discussion on a different naming/numbering scheme. Having duplicate entries just encourages multi-branched duplicate threads. -- MattWilkie - 29 Jan 2003

-- GrantBow - 28 Jan 2003

I restored the level 1 heading to be shown in the TOC, is needed for the TWikiDocumentation topic where this topic gets incuded.

-- PeterThoeny - 30 Jan 2003

Minor change: I inserted a missing <nop> in %CHARSET% in the list of "Specific changes to templates and skins"

-- DiegoZamboni - 03 Feb 2003

Thanks Diego!

-- GrantBow - 03 Feb 2003

Question: I have installed the KoalaSkin on my Dec2001 release, will the above instructions still work without having to remove the skin and start again?

-- MartinRoberts - 04 Feb 2003

Answer: I just upgraded to the latest while using KoalaSkin with no issues. Of course KoalaSkin doesn't (yet) know about some of the new features.

-- JimMoore - 24 Feb 2003

Fixed the 'pay attention to permissions' line for $TWIKIROOT/lib, as per ChristianFroehler's comment on FeedbackOnKnownIssuesOfTWiki01Feb2003 - the previous command actually broke TWiki installations by setting the wrong lib directory permissions.

-- RichardDonkin - 02 May 2003

I started SeparateCustomPreferences page to figure out how to make upgrade procerss simpler and still more flexible.

-- PeterMasiar - 15 May 2003

Note: as you will see when you start reading, this upgrade guide is rather out-of-date: it refers to how to get to the 1 Feb 03 release from an even older one!

If you are trying to upgrade from 1 Feb 03 to something later your best bet is to read this document and do something like what it says, using your common sense to deduce where you might need to adjust.

The discussion at the bottom of this guide might help you further, as might discussion at TWikiBetaReleaseDiscussions (since you must be trying to upgrade to a beta, because that's all there is after 1 Feb 03). I can reassure you that the process is not too bad, even if it looks scary at first.

And, if you think this situation needs to be fixed, rest assured that you are not alone... and hopefully it will be fixed. If you are interested in what's going on, the place to start is TWikiUpgradeStrategy.

UPDATED: There is now an upgrade tool for people starting with 01-Feb-2003 installations - see UpgradeTwiki and TWikiUpgradeGuide.

-- MartinGregory - 11 Apr 2004

I just did an upgrade of a March 2001 beta to 01 Feb 2003 production and these upgrade notes were very helpful - thanks Peter!

The guide should clarify that, if you installed the InterwikiPlugin as an add-on, it is now built into the 01 Feb 2003 release, and that the format of the TWiki.InterWikis page has changed. To convert from the old to the new format (01 Feb 2003 and higher), you might want to run the following Perl script on the InterWikis.txt file - please take a backup first and check the output file before replacing the original file (e.g. perl migrate.pl InterWikis.txt >out.txt).

#!/usr/bin/perl -p
s/^\t\* ([a-z][a-z0-9]*) (h[^\s]*)/\| $1 \| $2 \| $1 site \|/i;

You will need to hand-edit the file afterwards to get nicer entries in the third column, but at least all your InterWiki links will work.

Note that on TWiki.org, InterWikis is replaced by InterSiteLinkRules, but on a default installation the InterWikis topic name is used.

-- RichardDonkin - 14 Apr 2005

Edit | Attach | Watch | Print version | History: r41 < r40 < r39 < r38 < r37 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r41 - 2006-01-30 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.