TWiki/TWikiUpgradeGuide.mdwn

   1 # <a name="TWiki Upgrade Guide"></a> TWiki Upgrade Guide
   2
   3 _This guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to TWiki 4.2_
   4
   5 <div>
   6   <ul>
   7     <li><a href="#TWiki Upgrade Guide"> TWiki Upgrade Guide</a><ul>
   8         <li><a href="#Overview"> Overview</a></li>
   9         <li><a href="#Upgrade Requirements"> Upgrade Requirements</a></li>
  10         <li><a href="#Major Changes Compared to TWiki"> Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0</a></li>
  11         <li><a href="#Upgrade Procedure"> Upgrade Procedure</a><ul>
  12             <li><a href="#Installation"> Installation</a></li>
  13             <li><a href="#Install Extensions"> Install Extensions</a></li>
  14             <li><a href="#Copy your old webs to new TWiki"> Copy your old webs to new TWiki</a></li>
  15             <li><a href="#Copy Users And Their Topics From"> Copy Users And Their Topics From Main Web</a></li>
  16             <li><a href="#Apply Customizations To The Skin"> Apply Customizations To The Skin</a></li>
  17             <li><a href="#Apply Preferences From Old Insta"> Apply Preferences From Old Installation</a></li>
  18           </ul>
  19         </li>
  20         <li><a href="#Customization of Special Pages"> Customization of Special Pages</a></li>
  21         <li><a href="#Upgrading from Cairo to TWiki4 ("> Upgrading from Cairo to TWiki4 (additional advice)</a><ul>
  22             <li><a href="#Favicon"> Favicon</a></li>
  23             <li><a href="#!_TWikiUsers topic in Main web"> TWikiUsers topic in Main web</a></li>
  24           </ul>
  25         </li>
  26         <li><a href="#Important Changes since 4.0.5"> Important Changes since 4.0.5</a><ul>
  27             <li><a href="#Supported Perl version"> Supported Perl version</a></li>
  28             <li><a href="#Template spec changed"> Template spec changed</a></li>
  29           </ul>
  30         </li>
  31         <li><a href="#Important Changes since 4.1.0"> Important Changes since 4.1.0</a><ul>
  32             <li><a href="#New location for session and oth"> New location for session and other temporary files</a></li>
  33           </ul>
  34         </li>
  35         <li><a href="#Important Changes since 4.1.2"> Important Changes since 4.1.2</a><ul>
  36             <li><a href="#New WYSIWYG Editor"> New WYSIWYG Editor</a></li>
  37             <li><a href="#NEWTOPICLINKSYMBOL removed"> NEWTOPICLINKSYMBOL removed</a></li>
  38             <li><a href="#!_UserForm and _NewUserTemplate"> UserForm and NewUserTemplate Customization</a></li>
  39             <li><a href="#!_TWikiUsers no longer distribut"> TWikiUsers no longer distributed</a></li>
  40             <li><a href="#New <code>working</code> directory"> New working directory</a></li>
  41             <li><a href="#New Internal Admin Login"> New Internal Admin Login</a></li>
  42           </ul>
  43         </li>
  44       </ul>
  45     </li>
  46   </ul>
  47 </div>
  48
  49 ## <a name="Overview"></a> Overview
  50
  51 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.
  52
  53 ## <a name="Upgrade Requirements"></a> Upgrade Requirements
  54
  55 - Please review the [[AdminSkillsAssumptions]] before you upgrade TWiki
  56 - Review TWiki:TWiki.TWikiUpgradeTo04x02 for latest information and experience notes.
  57 - To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
  58 - To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.X Production Release, follow the instructions below
  59 - 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!
  60 - Not all Plugins written for TWiki Release 01-Sep-2004 are fully supported with 4.X. Make sure the Plugins you use can be upgraded as well!
  61
  62 ## <a name="Major Changes Compared to TWiki"></a><a name="Major Changes Compared to TWiki "></a> Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0
  63
  64 See [[TWikiReleaseNotes04x00]], [[TWikiReleaseNotes04x01]] and [[TWikiReleaseNotes04x02]]
  65
  66 <a name="ManualUpgradeProcedure"></a>
  67
  68 ## <a name="Upgrade Procedure"></a> Upgrade Procedure
  69
  70 The following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki release.
  71
  72 The main steps are:
  73
  74 1. Install the new TWiki version, configure it, and get it to work similar to the old version
  75 2. Install additional extensions (Plugins). Make sure to use the latest versions
  76 3. Copy all the non-default webs from the old installation to the new
  77 4. Copy the users from old installation to the new incl all their topics from Main
  78 5. Apply tailorings to your Skin (logos, menu bars etc)
  79 6. Apply preferences from old installation
  80
  81 ### <a name="Installation"></a> Installation
  82
  83 - 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.
  84 - Use the [configure](http://www.dementia.org/twiki/configure) script to configure TWiki.
  85   - If you are upgrading from a 4.x.x release, you can carry over the configure settings from the old release.
  86   - You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.
  87   - 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.
  88   - 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.
  89 - Additional resources
  90   - TWiki:TWiki.UpgradingTWiki04x00PatchReleases
  91   - TWiki:TWiki.InstallingTWiki#OtherPlatforms
  92   - TWiki:TWiki.ApacheConfigGenerator
  93   - TWiki:TWiki.SettingFileAccessRightsLinuxUnix
  94   - 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.
  95 - Make sure you have a working basic TWiki before you continue
  96
  97 ### <a name="Install Extensions"></a> Install Extensions
  98
  99 - Note that not all extensions that worked in Cairo have been updated to work with TWiki4.X. Many Cairo plugins work fine. Some do not. Many plugins have been upgraded to work with TWiki4.0 and later.
 100 - From TWiki-4.1.0 the [configure](http://www.dementia.org/twiki/configure) script which you ran during installation supports installation of additional plugins.
 101 - Manual installation is possible. Follow the instruction on the Plugin page at twiki.org.
 102 - Check the plugin topics from your old TWiki installation. There may be plugin settings that you want to transfer to the new TWiki installation. %BR% **_%H% Hint:_** For an easier upgrade later on, set the plugin preferences settings in the [[Main.TWikiPreferences|Main/TWikiPreferences]] topic, not in the plugin topic. To identify the plugin, prefix the name of the setting with the capitalized name of the plugin. For example, to change the `DEFAULT_TYPE` setting of the [[CommentPlugin]], create a `COMMENTPLUGIN_DEFAULT_TYPE` setting in Main.TWikiPreferences.
 103 - Typical plugin settings you may have altered.
 104   - [[CommentPlugin]] - Set DEFAULT\_TYPE
 105   - [[EditTablePlugin]] - Set CHANGEROWS, Set QUIETSAVE, and Set EDITBUTTON
 106   - [[InterwikiPlugin]] - Set RULESTOPIC
 107   - [[InterWikis]] - If you added your own rules you should save this topic and not overwrite it.
 108   - [[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.
 109   - [[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.
 110   - [[TablePlugin]] - Set TABLEATTRIBUTES
 111 - Remember that a plugin must be activated in [configure](http://www.dementia.org/twiki/configure).
 112 - 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
 113
 114 ### <a name="Copy your old webs to new TWiki"></a> Copy your old webs to new TWiki
 115
 116 - When upgrading from Cairo or earlier it may be necessary to unlock the rcs files in data and pub directories from the old installation using the following shell commands:
 117   - `find data -name '*,v' -exec rcs -u -M '{}' \;`
 118   - `find pub -name '*,v' -exec rcs -u -M '{}' \;`
 119 - 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.
 120 - Make sure all data and pub files and directories are owned by the webserver user.
 121 - **_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.
 122
 123 ### <a name="Copy Users And Their Topics From"></a> Copy Users And Their Topics From Main Web
 124
 125 - 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!
 126 - 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.
 127 - If you use `data/.htpasswd` for authentication copy this file from the old TWiki to the new.
 128   - 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`.
 129 - 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.
 130 - 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.
 131 - 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.
 132 - Make sure all data and pub files and directories are owned by the webserver user.
 133
 134 ### <a name="Apply Customizations To The Skin"></a> Apply Customizations To The Skin
 135
 136 - Not many of the old Cairo skins work well with TWiki4.X.
 137 - Add Logos, update top bar and left bar as required.
 138 - Apply any desired changes to style sheets and templates. The default [[PatternSkin]] has been totally rewritten since Cairo and once more in 4.0.2. Since then changes to [[PatternSkin]] have been minor and you may be able to carry over most simpler tailorings directly from 4.0.2-4.0.5.
 139 - Additional resources:
 140   - TWiki:TWiki.UpgradingTWiki04x00PatchReleases
 141   - [[PatternSkinCustomization]]
 142   - [[PatternSkinCssCookbook]]
 143
 144 ### <a name="Apply Preferences From Old Insta"></a> Apply Preferences From Old Installation
 145
 146 - Transfer any customized and local settings from [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] to the topic pointed at by \{LocalSitePreferences\} ([[Main.TWikiPreferences|Main/TWikiPreferences]]). Per default this is `Main.TWikiPreferences`. This avoids having to write over files in the distribution on a later upgrade.
 147 - 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.
 148 - 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.
 149 - 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.
 150
 151 ## <a name="Customization of Special Pages"></a> Customization of Special Pages
 152
 153 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:
 154
 155 - `TWiki.ChangePassword`
 156 - `TWiki.ResetPassword`
 157 - `TWiki.ChangeEmailAddress`
 158
 159 ## <a name="Upgrading from Cairo to TWiki4 ("></a> Upgrading from Cairo to TWiki4 (additional advice)
 160
 161 ### <a name="Favicon"></a> Favicon
 162
 163 TWiki4's [[PatternSkin]] introduces the use of the favicon feature which most browsers use to show a small icon in front of the URL and for bookmarks.
 164
 165 In TWiki4 it is assumed that each web has a favicon.ico file attached to the WebPreferences topic. When you upgrade from Cairo to TWiki4 you do not have this file and you will get flooded with errors the error log of your web server. There are two solutions to this.
 166
 167 - Attach a favicon.ico file to WebPreferences in each web.
 168 - Preferred: Change the setting of the location of favicon.ico in TWikiPreferences so all webs use the favicon.ico from the TWiki web. This is the fastest and easiest solution.
 169
 170 To change the location of favicon.ico in TWikiPreferences to the TWiki web add this line to [[TWikiPreferences]]
 171
 172        * Set FAVICON = %PUBURLPATH%/%SYSTEMWEB%/%WEBPREFSTOPIC%/favicon.ico
 173
 174 ### <a name="TWikiUsers topic in Main web"></a><a name="_TWikiUsers topic in Main web"></a> TWikiUsers topic in Main web
 175
 176 Your Cairo [[Main.TWikiUsers|Main/TWikiUsers]] topic will work in TWiki4 but you will need to ensure that these 4 users from the default TWiki4 version of TWikiUsers are copied to the existing TWikiUsers topic. TWikiGuest is probably already there but the others are new
 177
 178 - **TWikiContributor** - placeholder for a TWiki developer, and is used in TWiki documentation
 179 - **TWikiGuest** - guest user, used as a fallback if the user can't be identified
 180 - **TWikiRegistrationAgent** - special user used during the new user registration process
 181 - **UnknownUser** - used where the author of a previously stored piece of data can't be determined
 182
 183 You additionally need to ensure that TWikiUsers has the `Set ALLOWTOPICCHANGE = TWikiAdminGroup, TWikiRegistrationAgent`. Otherwise people will not be able to register.
 184
 185 ## <a name="Important Changes since 4.0.5"></a> Important Changes since 4.0.5
 186
 187 ### <a name="Supported Perl version"></a> Supported Perl version
 188
 189 TWiki 4.0.5 worked on Perl version 5.6.X. Reports from users has shown that unfortunately TWiki 4.1.0 does not support Perl versions older then 5.8.0. It is the goal that TWiki should work on at least Perl version 5.6.X but none of the developers have had access to Perl installations older than 5.8.0.
 190
 191 Since TWiki 4.1.0 has some urgent bugs the development team decided to release TWiki 4.1.1 without resolving the issue with Perl 5.6.X. We will however address this and try and resolve it for a planned 4.1.2 release. The TWiki community is very interested in contributions from users that have fixes for the code which will enable TWiki to run on older versions of Perl.
 192
 193 See the [WhatVersionsOfPerlAreSupported](http://twiki.org/cgi-bin/view/Codev/WhatVersionsOfPerlAreSupported) topic to keep up to date with the discussion how to get back support for earlier Perl versions.
 194
 195 ### <a name="Template spec changed"></a> Template spec changed
 196
 197 Until TWiki 4.0.5 [[TWikiTemplates]] the text inside template definition blocks (anything between %TMPL:DEF\{"block"\}% and %TMPL:END% was stripped of leading and trailing white space incl new lines.
 198
 199 This caused a lot of problems for skin developers when you wanted a newline before or after the block text.
 200
 201 From TWiki 4.1.0 this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. But if you use an older skin or have written your own you will most likely need to make some adjustments.
 202
 203 It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF\{"block"\}% needs to be removed. Ie. the content of the block must follow on the same line as the TMPL:DEF.
 204
 205 The spec change have the same impact on [[CommentPlugin]] templates where you may have to remove the first line break after the TMPL:DEF. See the [[CommentPluginTemplate]] for examples of how comment template definitions should look like in TWiki-4.1.X
 206
 207 An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.
 208
 209     <verbatim>
 210     %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%
 211     |%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
 212     %TMPL:END%
 213     </verbatim>
 214
 215 From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.
 216
 217     <verbatim>
 218     %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
 219     %TMPL:END%
 220     </verbatim>
 221
 222 The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.
 223
 224 ## <a name="Important Changes since 4.1.0"></a> Important Changes since 4.1.0
 225
 226 ### <a name="New location for session and oth"></a> New location for session and other temporary files
 227
 228 **An upgrader upgrading to 4.1.1 should note the following important change**
 229
 230 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.
 231
 232 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.
 233
 234 ## <a name="Important Changes since 4.1.2"></a> Important Changes since 4.1.2
 235
 236 ### <a name="New WYSIWYG Editor"></a> New WYSIWYG Editor
 237
 238 TWiki now ships with a new WYSIWYG editor based on TinyMCE replaces the Kupu based editor.%BR% TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the Kupu editor
 239
 240 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
 241
 242 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
 243
 244 The WYSIWYG button has been removed.
 245
 246 ### <a name="NEWTOPICLINKSYMBOL removed"></a> NEWTOPICLINKSYMBOL removed
 247
 248 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.
 249
 250 ### <a name="UserForm and _NewUserTemplate Cu"></a><a name="_UserForm and _NewUserTemplate C"></a> UserForm and NewUserTemplate Customization
 251
 252 When a new user registers on TWiki his user topic is created based on the `NewUserTemplate` and `UserForm`.
 253
 254 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.
 255
 256 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.
 257
 258 ### <a name="TWikiUsers no longer distributed"></a><a name="_TWikiUsers no longer distribute"></a> TWikiUsers no longer distributed
 259
 260 The `Main.TWikiUsers` topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.
 261
 262 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.
 263
 264 - For new installers this makes no difference at all
 265 - For upgraders this is one less problem to worry about as your important Main.TWikiUsers topic now no longer gets overwritten when upgrading.
 266
 267 ### <a name="New &lt;code&gt;working&lt;/code&gt; directory"></a> New `working` directory
 268
 269 A new directory `working` which per default is located in the twiki root, has been introduced which contains:
 270
 271 - registration\_approvals - with 4.2.0 it is moved to here from the data directory)
 272 - tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.
 273 - work\_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.
 274
 275 Note: Remember to restrict access to this new directory when you upgrade.
 276
 277 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.
 278
 279 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*`.
 280
 281 ### <a name="New Internal Admin Login"></a> New Internal Admin Login
 282
 283 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.
 284
 285 **_Related Topics:_** [[AdminDocumentationCategory]], TWiki:TWiki.UpgradingTWiki, TWiki:TWiki.UpgradingTWiki04x00PatchReleases, TWiki:TWiki.InstallingTWiki#OtherPlatforms, TWiki:TWiki.ApacheConfigGenerator, TWiki:TWiki.SettingFileAccessRightsLinuxUnix