The Caboteria / TWiki Web / TWikiUpgradeGuide (revision 1)
On this page:

TWiki Upgrade Guide

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

Overview

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:
    • 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 back 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
    • Change to view templates and skins:
      • Add %BROADCASTMESSAGE% somewhere on the top of the rendered HTML page (see the new view.tmpl for reference)
    • Changes to edit templates and skins:
      • Change the form action from preview to save:
        <form name="main" action="%SCRIPTURLPATH%/save%SCRIPTSUFFIX%/%WEB%/%TOPIC%" method="post">
      • Change the topic action to the following:
        %TMPL:DEF{"topicaction"}%
        <input type="submit" class="twikiSubmit" name="action" value="Cancel" id="cancel" />
        <input type="submit" class="twikiSubmit" name="action" value="Preview" id="preview" />
        <input type="submit" class="twikiSubmit" name="action" value="Checkpoint" id="checkpoint" />
        <input type="submit" class="twikiSubmit" name="action" value="QuietSave" id="quietsave" />
        <input type="submit" class="twikiSubmit" name="action" value="Save" id="save" />%TMPL:END%
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
      • If necessary, rename the scrips 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 your existing $TWIKIROOT/bin/.htaccess file to include a directive for the new rdiffauth script:
      <Files "rdiffauth">
          require valid-user
      </Files>
    • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
      • Certain hosted environments require a 755 (do so if you get a "Premature end of script headers" messages in the Apache error log)
    • For Windows hosts, 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` (for files) and chmod 775 `find -type d $TWIKIROOT/lib` (for 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, for example www-data
      • Run the testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)
      • Alternatively, execute the shell script commands described in TWikiInstallationGuide#StepTwo
    • 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.*, 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. Notable changes are:
      • New WIKIWEBMASTERNAME setting to avoid notifications being trapped by spam filters
      • New ATTACHFILESIZELIMIT setting for maximum size of FileAttachments in KB, 0 for no limit
      • New READTOPICPREFS and TOPICOVERRIDESUSER settings to allow override Preference settings in topics
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER
    • Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory
    • 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):
    • Add WebLeftBar topic. See WebLeftBarExample for a clean example, and WebLeftBarCookbook for more information. (WebLeftBar is used by the PatternSkin skin)
    • Add WebSearchAdvanced topic, which has this one line:
      %INCLUDE{"%TWIKIWEB%.WebSearchAdvanced"}%
    • Consider changing WebPreferences settings:
      • New NOAUTOLINK setting to prevent automatic linking of WikiWords and acronyms
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
  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. Verify installation:
    • Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; address 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 TWiki.WebHome

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

Edit | Attach | Print version | History: r13 | r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions...
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding The Caboteria? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiUpgradeGuide.