Difference: TWikiUpgradeGuide (7 vs. 8)

Revision 810 Jan 2008 - Main.TWikiContributor

Line: 1 to 1
 
Changed:
<
<

TWiki Upgrade Guide

>
>

TWiki Upgrade Guide

 
Changed:
<
<
This guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to TWiki 4.1_
>
>
This guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to TWiki 4.2
 
On this page:

Overview

Changed:
<
<
TWiki-4.0.0 was a major new release. TWiki-4.1.0 is a minor release without dramatic changes since 4.0.0
>
>
TWiki-4.0.0 was a major new release. TWiki-4.1.0 was a minor release without dramatic changes since 4.0.0. TWiki-4.2.0 is also a minor release containing a few new features that can be seen by the end user, a large number of bug fixes, and a face lift for the skin. It also contains some important updates under the hood to the way users are handled which enables new types of authentication and integration with other systems. The most important new feature is the QuerySearch feature.
 

Upgrade Requirements

Changed:
<
<
>
>
 
  • To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
  • To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.X Production Release, follow the instructions below
  • Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write. Make sure you take a backup!
Line: 21 to 21
 

Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0

Changed:
<
<
See TWikiReleaseNotes04x00 and TWikiReleaseNotes04x01
>
>
See TWikiReleaseNotes04x00, TWikiReleaseNotes04x01 and TWikiReleaseNotes04x02
 

Line: 42 to 42
 
  • Follow the installation instructions in INSTALL.html which you find in the root of the new installation. Install the new release in a new directory. Do not install on top of the old release.
  • Use the configure script to configure TWiki.
Changed:
<
<
    • If you are upgrading from a 4.0.x release, carry over the configure settings from the old release.
>
>
    • If you are upgrading from a 4.x.x release, you can carry over the configure settings from the old release.
    • You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.
    • You can also choose to start with a fresh configuration and walk through all the settings using your old LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg.
    • If at any time during the installation you want to start over from fresh all you need to do is delete the lib/LocalSite.cfg file and re-run configure.
 
Changed:
<
<
    • Your lib/TWiki.cfg from the old TWiki installation is a good resource for some of the settings you will need but you cannot reuse the old TWiki.cfg.
>
>
    • If you upgrade from an older TWiki your lib/TWiki.cfg from the old TWiki installation is a good resource for some of the settings you will need but you cannot reuse the old TWiki.cfg.
 
  • Make sure you have a working basic TWiki before you continue

Install Extensions

Line: 64 to 67
 
    • InterwikiPlugin - Set RULESTOPIC
    • InterWikis - If you added your own rules you should save this topic and not overwrite it.
    • SlideShowPlugin - Make sure you did not change the embedded 'Default Slide Template' If you did you should save it. It is a bad idea to do. It is better to define your own slide show templates as separate topics that do not get overwritten when you upgrade.
Changed:
<
<
    • SmiliesPlugin - Did you add your own smileys? No smileys were added 4.0.0 and 4.0.2 so you can just leave this topic as it is.
>
>
    • SmiliesPlugin - Did you add your own smileys? No real changes were made to the smilies topic October 2005 so you can just leave this topic as it is.
 
Added:
>
>
  • To avoid having to re-apply plugin settings each time you upgrade a plugin or TWiki itself, define the altered plugin settings in Main.TWikiPreferences instead
 

Copy your old webs to new TWiki

Line: 74 to 78
 
    • find data -name '*,v' -exec rcs -u -M '{}' \;
    • find pub -name '*,v' -exec rcs -u -M '{}' \;
  • Copy your local webs over to the data and pub directories of the new install. Do not copy the default webs: TWiki, Main, Trash, Sandbox, _default, and _empty.
Added:
>
>
  • Make sure all data and pub files and directories are owned by the webserver user.
  • Note: TWiki's WebChanges topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or to change them in the sequence of old file timestamps.
 

Copy Users And Their Topics From Main Web

  • Copy all the topics from the Main web and corresponding pub/Main directories from the old TWiki to the new TWiki but do not overwrite any of the new topics already inside the new Main directory!
Changed:
<
<
  • Manually merge all the users from the old TWiki.TWikiUsers topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.X simply use the old topic.
>
>
  • Manually merge all the users from the old Main.TWikiUsers topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.X simply use the old topic. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.
 
  • If you use data/.htpasswd for authentication copy this file from the old TWiki to the new.
Changed:
<
<
    • If you upgrade from Cairo and you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password database. There is a script that performs this extra upgrade step for you - see tools/upgrade_emails.pl.
>
>
    • If you upgrade from Cairo and you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password file. There is a script that performs this extra upgrade step for you - see tools/upgrade_emails.pl.
 
  • The old sandbox web may have a lot of useful topic and users may use it actively for drafts. Manually select the topics (remember the corresponding pub directories) from the old Sandbox web and copy them to the new TWiki. Decide if you want to overwrite the sandbox homepage and left menu bar or keep the new.
Added:
>
>
  • If you added or removed fields from the user topic form you may also have tailored TWiki.TWikiRegistration. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new TWiki.TWikiRegistration topic.
  • Starting from 4.2.0 TWiki ships with NewUserTemplate and UserForm in the TWiki web. If you choose to tailor anything you are strongly adviced to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your tailorings next time you upgrade TWiki.
  • Make sure all data and pub files and directories are owned by the webserver user.
 

Apply Customizations To The Skin

Line: 95 to 104
 

Apply Preferences From Old Installation

Changed:
<
<
  • Transfer any customized and local settings from TWiki.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (Main.TWikiPreferences). Per default this is Main.TWikiPreferences. This avoids having to write over files in the distribution on a later upgrade.
  • If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though a suggestion is to use 'diff' to find changed files in the data/TWiki of the old and new TWiki installation, and transfer the changes into the new TWiki install.
>
>
  • Transfer any customized and local settings from TWiki.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (Main.TWikiPreferences). Per default this is Main.TWikiPreferences. This avoids having to write over files in the distribution on a later upgrade.
  • If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though a suggestion is to use 'diff' to find changed files in the data/TWiki of the old and new TWiki installation, and transfer the changes into the new TWiki install. If you can run a GUI on your server, you may find that using a visual diff tool like WinMerge, meld, kdiff3, xxdiff, etc. is helpful.
 
  • Compare the WebPreferences topics in the old TWiki Installation with the default from the new TWiki installation and add any new Preferences that may be relevant.
  • Compare the WebLeftBar topics in the old TWiki Installation with the default from the new TWiki installation and add any new feature that you desire.
Added:
>
>

Customization of Special Pages

Some pages in the TWiki web are meant to be customized after choice of authentication. If you do not use the internal TWiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. If you have made such customizations remember to replace these topics in the TWiki web with the tailored versions from your old installation. The topics are:

  • TWiki.ChangePassword
  • TWiki.ResetPassword
  • TWiki.ChangeEmailAddress
 

Upgrading from Cairo to TWiki4 (additional advice)

Favicon

Line: 114 to 131
 To change the location of favicon.ico in TWikiPreferences to the TWiki web add this line to TWikiPreferences
Changed:
<
<
  • Set FAVICON = /twiki/pub/TWiki/WebPreferences/favicon.ico
>
>
  • Set FAVICON = /twiki/pub/TWiki/WebPreferences/favicon.ico
 

TWikiUsers topic in Main web

Line: 173 to 190
 

Important Changes since 4.1.0

Changed:
<
<

New location for session files

>
>

New location for session and other temporary files

 
Changed:
<
<
An upgrader upgrading to 4.1.1 should note the following important change
>
>
An upgrader upgrading to 4.1.1 should note the following important change
  The directory for passthrough files and session files have been replaced by a common directory for temporary files used by TWiki. Previously the two configure settings {PassthroughDir} and {Sessions}{Dir} were by default set to /tmp. These config settings have been replaced by {TempfileDir} with the default setting value /tmp/twiki. If the twiki directory does not exist twiki will create it first time it needs it.

It is highly recommended no longer to use the tmp directory common to other web applications and the new default will work fine for most. You may want to delete all the old session files in /tmp after the upgrade to 4.1.1. They all start with cgisess_. It is additionally highly recommended to limit write access to the {TempfileDir} for security reasons if you have non-admin users with login access to the webserver just like you would do with the other webserver directories.

Added:
>
>

Important Changes since 4.1.2

New WYSIWYG Editor

TWiki now ships with a new WYSIWYG editor based on TinyMCE replaces the Kupu based editor.
TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the Kupu editor

The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that less TWiki Applications are negatively affected by editing WYSIWYG

When TinyMCEPlugin is enabled the Edit button per default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way

The WYSIWYG button has been removed.

NEWTOPICLINKSYMBOL removed

The NEWTOPICLINKSYMBOL preference which was deprecated in 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use NEWLINKFORMAT.

UserForm and NewUserTemplate Customization

When a new user registers on TWiki his user topic is created based on the NewUserTemplate and UserForm.

The NewUserTemplate was located in the TWiki web and the UserForm in the Main web. When upgrading TWiki these were some of the topics you had to take care not to overwrite.

From 4.2.0 the UserForm and NewUserTemplate are distributed in the TWiki web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade TWiki your tailored template and form will not be overwritten.

TWikiUsers no longer distributed

The Main.TWikiUsers topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.

From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the Main.TWikiUsers topic in the Main web if it does not exist already. This means that you can now upgrade TWiki without risk of overwriting the important TWikiUsers topic.

  • For new installers this makes no difference at all
  • For upgraders this is one less problem to worry about as your important Main.TWikiUsers topic now no longer gets overwritten when upgrading.

New working directory

A new directory working which per default is located in the twiki root, has been introduced which contains:

  • registration_approvals - with 4.2.0 it is moved to here from the data directory)
  • tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.
  • work_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.

Note: Remember to restrict access to this new directory when you upgrade.

The configuration setting {WorkingDir} defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is working under your installation root.

Take care for that change if you run your own routine to delete obsolete session files, which will now be found under working/tmp/cgisess*.

New Internal Admin Login

TWiki 4.2 introduces a new Internal Admin Login feature which uses "admin" (configurable) as username and the password used for configure to become temporary administrator. When you do a new installation you need to use this feature as Main.TWikiAdminGroup is now access restricted by default to avoid security attacks during the hours an installation may take. From configure there is a link to the TWikiAdminGroup topic and on TWikiAdminGroup the step by step instructions are written in a yellow box. Our advice is not to remove this help text in case you need it later.

 
 
This site is powered by the TWiki collaboration platformCopyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiUpgradeGuide