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-2000). The file system set-up is almost identical, but much of the underlying data structure and processes is new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly.

Upgrade Requirements

• To upgrade from a 01-Dec-2000 standard installation to the new, next generation 01-Sep-2001 TWiki Production Release, follow the instructions below.

• NOTE: To upgrade from a pre-01-Dec-2000 TWiki, start with TWikiUpgradeTo01Dec2000.

• 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-2000

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

• TWikiPlugins - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the TWiki Plugin API.
  • InterwikiPlugin (preinstalled) - Link to external sites with text aliases, SiteAlias:Page; rules are defined in InterWikis. (Get more Plugins from the TWiki:Plugins web.)
• TWikiTemplates - New, more flexible template system.
• TWikiSkins - Overwrite template headers and footers; page content is unaffected.
• TWikiMetaData - New data format
• TWikiForms - Create multiple input forms per web; data is rendered in HTML tables.
• ManagingTopics Individual topics can be renamed, moved and deleted through the browser. Deleted topics are stored in a common Trash web.
• Change passwords^? Change and reset passwords using forms.
• TOC (Table of Contents) - %TOC% variable generates a hierarchical table of contents from topic headings: <hI>...<h6>. Set depth.
• Arbitrary Text for WikiWord Links - Text formatting rules to generate automatic links from any combination of words and spaces.
• Attachments Under Revision Control Changes made to files attached to topics are now saved under revision control (RCS).
• Convert to XHTML - Templates and HTML page rendering are in XHTML 1.0 as far as possible without breaking HTML 3.2 compliance.
• HierarchicalNavigation uses new Meta Data variables to link hierarchically.
• SuperAdministrator Group allows you to give one user group - by default, TWikiAdminGroup - superpowers: the ability to overwrite locked topics from the browser interface. (This gets around a potential problem where mistyping topic access definition could result in locking everyone out.)

TWiki Directory Structure and File Names

The TWiki directory structure remains the same, with one exception, the TWiki configuration file and Perl modules have been moved from the twiki/bin directory into it's own twiki/lib directory tree. The following files have been renamed and moved:

From TWiki 01-Dec-2000:	To TWiki 01-Sep-2001:
twiki/bin/wikicfg.pm	twiki/lib/TWiki.cfg
twiki/bin/wiki.pm	twiki/lib/TWiki.pm
twiki/bin/wikiaccess.pm	twiki/lib/TWiki/Access.pm
twiki/bin/wikiprefs.pm	twiki/lib/TWiki/Prefs.pm
twiki/bin/wikisearch.pm	twiki/lib/TWiki/Search.pm
twiki/bin/wikistore.pm	twiki/lib/TWiki/Store.pm

A new twiki/lib/TWiki/Plugins directory contains the new Plugin modules.

Standard Upgrade Procedure

The idea is to have the new and old installation work in parallel so that you can test the new installation before switching over. That way you can make the switch on your live TWiki installation within one minute without affecting the users.

Before Switch:		After Switch:
Current 01-Dec-2000:	New 01-Sep-2001:	Obsolete 01-Dec-2000:	New 01-Sep-2001:
twiki/templates/	twiki/templates2/	twiki/templates1/	twiki/templates/
twiki/bin/	twiki/bin/2/	(overwritten)	twiki/bin/
(N/A)	twiki/bin/lib/	(N/A)	twiki/lib/
twiki/data/TWiki	twiki/data/TWiki2	twiki/data/TWiki1	twiki/data/TWiki
(other directories do not change)

Alternatively you could move the existing installation away, install the 01-Sep-2001 release into it's place and move your webs and pub files back.

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 - TWikiTemplates and TWikiForms (input forms associated with a topic)- are entirely different in the new TWiki. If you've customized your templates or use Category Tables, read those sections before starting your upgrade.

The following steps describe the upgrade on Unix. Windows setup is very similar. It's assumed that $TWIKIROOT is the root of your current 01-Dec-2000 release, ex: export TWIKIROOT=/some/dir/

Step 1: Backup & Unpack

1. Back up all existing TWiki directories twiki/bin, twiki/pub, twiki/data, twiki/templates.
2. Create a temporary directory and unpack the ZIP file there:
   mkdir -p ~/tmp/
cp -p ~/downloads/TWiki20010901.zip ~/tmp/
cd ~/tmp/
unzip ~/tmp/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: Install new template files

1. Move & rename the template directory to a temporary twiki/templates2 directory, ex:
   mv ~/tmp/templates $TWIKIROOT/templates2
2. Pay attention to the file and directory permissions (security issue). Set file permissions, ex:
   chmod 644 *.cgi

Step 4: Install new data and pub files

1. Move the TWiki web to a temporary TWiki2 twiki/data/TWiki2 directory. Do the same to files attached to this web, ex:
   mv ~/tmp/data/TWiki $TWIKIROOT/data/TWiki2
mv ~/tmp/pub/TWiki $TWIKIROOT/pub/TWiki2
2. Move & rename the Know web to a temporary twiki/data/Know2 directory, ex:
   mv ~/tmp/data/Know $TWIKIROOT/data/Know2
mv ~/tmp/pub/Know $TWIKIROOT/pub/Know2
3. Move the _default and Trash web, ex:
   mv ~/tmp/data/_default $TWIKIROOT/data
mv ~/tmp/data/Trash $TWIKIROOT/data
4. Move the MIME types file, ex:
   mv ~/tmp/data/mime.types $TWIKIROOT/data
5. Move the TWiki logo files, ex:
   mv ~/tmp/pub/*.gif $TWIKIROOT/pub
6. Pay attention to the file permissions of the TWiki2 and Know2 directories and its files. The files must be writable by the cgi-scripts (usually user nobody).
7. In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
   for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done

Step 5: Install new CGI scripts

1. Move & rename the CGI script directory to a temporary twiki/bin/2 directory, ex:
   mv ~/tmp/bin $TWIKIROOT/bin/2
2. If necessary, change the script names to include the required extension, ex: .cgi
3. Copy any additional scripts you might have from the 01-Dec-2000 release, ex:
   cp -p $TWIKIROOT/bin/somescript $TWIKIROOT/bin/2
4. In case you use basic authentication, rename .htaccess.txt to .htaccess and customize it, ex:
   cd $TWIKIROOT/bin/2
mv .htaccess.txt .htaccess
diff ../.htaccess .
   and merge the content
5. Pay attention to the file and directory permissions (security issue). Set permissions, ex:
   chmod 755 *.cgi

Step 6: Install new Perl library files

1. Move the lib directory to a temporary twiki/bin/lib directory, ex:
   mv ~/tmp/lib $TWIKIROOT/bin
2. Pay attention to the file and directory permissions (security issue). Set permissions, ex:
   chmod 644 *.pm

Step 7: Set configurations and test installation

1. Merge the content of the old twiki/bin/wikicfg.pm into the new twiki/lib/TWiki.cfg configuration file. Use the diff command to find out the differences, ex:
   cd $TWIKIROOT/bin/lib
diff ../wikicfg.pm TWiki.cfg
2. Make sure to set the correct temporary location of templates and scripts, ex:
   $scriptUrlPath    = "/twiki/bin/2";
$templateDir      = "/home/httpd/twiki/templates2";
3. Do not merge the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE, extendGetRenderedVersionInsidePRE from the old twiki/bin/wikicfg.pm. This is now handled by the Default plugin twiki/lib/TWiki/Plugins/Default.pm
4. Test your new TWiki installation to see if you can view topics. Point your browser to the old installation and fix the URL to see the new installation, ex:
   • Old URL: http://localhost/cgi-bin/view
   • New URL: http://localhost/cgi-bin/2/view

Step 8: Update topics

You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Sep-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended, so that users don't get surprised by meta data content showing up in topics.

1. Remember that you now have two TWiki webs:
   • The original TWiki web.
   • The new TWiki2 web, which gets renamed to TWiki when you switch over the installation.
2. In case you customized TWiki.TWikiRegistration, merge your changes back into TWiki2.TWikiRegistration.
3. Copy TWiki.TWikiWebsTable to TWiki2.TWikiWebsTable.
   • Do the same for any other topics you might have created in the TWiki web.
4. In TWiki2.TWikiPreferences, merge the old TWiki.TWikiPreferences settings and customize it.
   • Add your webs to WIKIWEBLIST
   • Set the WIKIWEBMASTER
   • Set the SMTPMAILHOST
5. In WebPreferences of all webs, add or change the following web preferences: (see TWiki.WebPreferences)
   • Add a NOSEARCHALL in case you want to exclude the web from a web="all" search:
     * Set NOSEARCHALL = on
   • Modify WEBTOPICLIST, ex:
     * Set WEBTOPICLIST = [[%HOMETOPIC%][Home]] %SEP% [[WebChanges][Changes]] %SEP% [[WebIndex][Index]] %SEP% [[WebSearch][Search]] %SEP% Go <input type="text" name="topic" size="16" />
   • Add a these new preferences:
     * Set DENYWEBVIEW =
* Set ALLOWWEBVIEW =
* Set DENYWEBRENAME =
* Set ALLOWWEBRENAME =
   • Set FINALPREFERENCES:
     * Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
6. In WebSearch of all webs, replace content with this one line:
   %INCLUDE{"%TWIKIWEB%.WebSearch"}%
7. In WebChanges of all webs, replace content with this one line:
   %INCLUDE{"%TWIKIWEB%.WebChanges"}%

Step 9: Customize template files

NOTE: Skip this step if you did not customize your template files.

1. Remember that you have now two template directories:
   • The original twiki/templates.
   • The new twiki/templates2, which gets renamed to twiki/templates when you switch over the installation.
2. Customized templates and skins need to be upgraded to the new TWikiTemplates. 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:
   • Templates are now rendered by TWiki. You can use all TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a =<p /> tag added.
   • Added TWikiMetaData rendering.
3. Form Templates replace the TWikiCategoryTables:
   • Create a replacement TWikiForms 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.
4. 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.

Step 10: Switch over to new installation

In this step, you move the working 01-Sep-2001 installation to the old 01-Dec-2000 installation, so that you don't have to change the URL.

1. Test your new 01-Sep-2001 installation under twiki/bin/2/view to make sure everything works as expected.
   • NOTE: Don't worry about the Plugins, they'll work after the switch.
2. Edit $TWIKIROOT/bin/2/TWiki.cfg and remove the /2 from $scriptUrlPath and $templateDir, ex:
   $scriptUrlPath    = "/twiki/bin";
$templateDir      = "/home/httpd/twiki/templates";
3. Rename the TWiki2 web to TWiki, including attachments, ex:
   cd $TWIKIROOT/data
mv TWiki TWiki1
mv TWiki2 TWiki
cd $TWIKIROOT/pub
mv TWiki TWiki1
mv TWiki2 TWiki
4. Rename the templates2 directory to templates, ex:
   cd $TWIKIROOT
mv templates templates1
mv templates2 templates
5. Move the lib directory one level up from $TWIKIROOT/bin/lib to $TWIKIROOT/lib, ex:
   cd $TWIKIROOT
mv bin/lib .
6. Copy content of bin/2 to bin, ex:
   cd $TWIKIROOT/bin
cp -p bin/2/* .
cp -p bin/2/.htaccess .
7. Point your browser to the original URL and make sure the relocated 01-Sep-2001 installation works as expected: check browsing, searching and user registration.
8. Clean up and remove obsolete directories:
   • Remove directory $TWIKIROOT/bin/2
   • Remove directory $TWIKIROOT/templates1
   • Remove directory $TWIKIROOT/data/TWiki1
   • Remove directory $TWIKIROOT/pub/TWiki1
   • Remove temporary directory, ex: ~/tmp

Step 11: Test the TWiki Plugins

1. 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.
2. If you have customized the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE and extendGetRenderedVersionInsidePRE in twiki/bin/wikicfg.pm:
   • Merge those changes back into twiki/lib/TWiki/Plugins/Default.pm

General Format Changes

• The format of the %GMTIME{"..."}% and %SERVERTIME{"..."}% variables is now "$hour:$min" instead of "hour:min". More in TWikiVariables.

• ExtendingTableSyntax: Enhanced table syntax might have unwanted side effect: | *bold* | cells, |  center aligned  | and |   right aligned | cells, span multiple columns using | empty cells |||. More in TextFormattingRules.

• Use Net::SMTP module instead of sendmail if installed.

• Use <verbatim> ... </verbatim> tags instead of <pre> ... </pre> tags where appropriate. More in TextFormattingRules.

• New variable %STARTINCLUDE% and %STOPINCLUDE% variables to control what gets included of a topic. More in TWikiVariables.

• FileAttachment info is now stored as TWiki Meta Data.
  • Upgrading of imported pagess is done automatically after first edit, on save. "In memory" upgrade is done on topic view.
  • Attachments are now under revision control: $attachAsciiPath in TWiki.cfg defines which file types are stored in ASCII, otherwise, binary format is used. This means that the RCS version used should support binary files.

• Handling for topic-specific templates like edit.new.tmpl has been removed and replaced by template topics in the new TWikiTemplates.

• A new file warning.txt file can appear in the data directory. It may contain diagnostic info identifying problems that need fixing. This file could get fairly large if you have a lot of problems your site - you can delete it at any time.

Known Issues

• • Check TWiki:Codev/KnownIssuesOfTWiki01Sep2001 for known issues of TWiki 01 Sep 2001 (production release)

-- JohnTalintyre^? - 18 Jul 2001
-- MikeMannix^? - 12 Sep 2001
-- PeterThoeny - 12 Sep 2001