netfrag.org . TWiki . TWikiUpgradeGuide

TWiki Upgrade Guide

Upgrade from TWiki 01-Dec-2000 to TWiki 01-Sep-2001 (previous to new full release)

Overview

The latest version of TWiki (01-Sep-2001) involves several major new features and numerous enhancements to the last full version (01-Dec-2001). The file system set-up is almost identical, but much of the underlying data structure and processes are new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly.

Upgrade Requirements

Major Changes from TWiki 01-Dec-2000

The 01 Sep 2001 release includes the following new features and enhancements:

The TWiki directory structure remains the same, with one exception, the new lib/TWiki/Plugins directory tree to for the main configuration file, library, internal modules and the new Plugin modules. Pre-existing files were formerly in bin.

Standard Upgrade Procedure

Follow this step-by-step guide to upgrade from the 01-Dec-2000 TWiki to the 01-Sep-2001 release, importing your original page data and related files:

Pre-Upgrade Preparation

Two major areas of TWiki functionality - templates and Category Tables (input forms associated with a topic)- are entirely different in the new TWiki. Therefore, if you've customized your templates or use Category Tables, you should read those sections before starting your upgrade. That way, converting old templates and pages to new will be flow along smoothly!

Step 1: Backup & Unpack

    1. Move all existing TWiki directories ( bin, pub, data, templates ) to a temporary directory (it's a good idea to do a full back-up first):
      mkdir -p ~/tmp/
      mv $TWIKIROOT/* ~/tmp/
    2. Unpack the zip file into your newly empty working directory:
      cd $TWIKIROOT
      unzip ~/TWiki20010901.zip

Step 2: Upgrade TWiki document files

    1. Move the document files to your TWiki root ( twiki ):
      mv ~/tmp/TWiki*.html $TWIKIROOT
      mv ~/tmp/index.html $TWIKIROOT
      mv ~/tmp/readme.txt $TWIKIROOT
      mv ~/tmp/license.txt $TWIKIROOT

Step 3: Upgrade CGI scripts

    1. If necessary, change the script names to include the required extension, ex: .cgi
    2. Restore any additional scripts you might have from the tmp directory, ex:
      mv ~/tmp/bin/somescript $TWIKIROOT/bin/
    3. Set permissions, ex:
      chmod 755 *.cgi
    4. Restore any additional scripts you might have from the tmp directory, ex:
      mv ~/tmp/bin/somescript $TWIKIROOT/bin/
    5. Test your TWiki installation to see if you can view topics.

Step 4: Set configurations in TWiki.cfg

    1. Customize the new lib/TWiki.cfg configuration file, which replaces the wikicfg.pm file. New settings to watch for:
      • SuperAdminCanConfig
    2. Test your TWiki installation to see if you can view topics.
    3. Test the new TWikiPlugins by checking the Plugins settings in TWikiPreferences.
      • The EmptyPlugin, DefaultPlugin, and InterwikiPlugin should be preinstalled. To check the InterwikiPlugin, go to its page.

Step 5: Upgrade template files

    1. Customized templates and skins need to be upgraded to the new TWiki Template System. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
    2. Form Templates replace the TWikiCategoryTables:
      • Create a replacement Form Template based on twikicatitems.tmpl in each web that used a Category Table.
      • Searches need to be adjusted to deal with format change - if all topics are upgrades, a more specific search can be done.
    3. For each web that has a custom notedited.tmpl template, create a WebTopicEditTemplate to conform with the new SelectableNewTopicTemplates feature. Retired notedited.tmpl, notext.tmpl and notwiki.tmpl templates.
    4. Test your TWiki installation to see if you can view topics.

Step 6: Upgrade public files

    1. Move your own public data files and sub-directories from the original pub directory to the new installation: ( $TWIKIROOT/pub )
      mv ~/tmp/pub/TWiki/somefiles.ext $TWIKIROOT/pub/
      mv ~/tmp/pub/TWiki/somedirectory $TWIKIROOT/pub/

Step 7: Upgrade data files

    1. Move the tmp/data/TWiki directory to your installation: ( twiki/data )
      mv ~/tmp/data/TWiki $TWIKIROOT/data/
      Pay attention to the file permissions of the TWiki directory and its files. The files must be writable by the cgi-scripts (usually user "nobody")
    2. TWikiRegistration moved from TWiki.Main to TWiki.TWiki. In case you customized TWikiRegistration , merge your changes back into TWiki.TWikiRegistration , then delete $TWIKIROOT/data/Main/TWikiRegistration*.
    3. TWikiPreferences into TWiki.TWikiPreferences.
    4. Merge your changes to the WebPreferences topics in all your webs into WebPreferences
    5. Modify the WebPreferences topics in all your webs to reflect the following:
      • In case you want to exclude a web from a web="all" search: Set this new preference
        Set NOSEARCHALL = on
    6. The WebSearch topic has considerable changes. Copy the one from TWiki.TWiki into all webs, or merge them if you made changes. To copy, do an edit-copy-edit-paste operation.
    7. Change the WebHome topics in all your webs to reflect these changes:
    8. If you are using .htaccess, add the rename script * You may want to add [ALLOW|DENY][WEB|TOPIC]RENAME in some places, like TWikiPreferences, WebPreferences and TWikiUsers

General Format Changes

Known Upgrade Issues

-- JohnTalintyre? - 18 Jul 2001

----- Revision r1.15 - 09 Sep 2001 - 00:08 - MikeMannix?