TWiki/TWikiUpgradeGuide.mdwn

   1 <div>
   2   <ul>
   3     <li><a href="#TWiki Upgrade Guide"> TWiki Upgrade Guide</a><ul>
   4         <li><a href="#Overview"> Overview</a></li>
   5         <li><a href="#Upgrade Requirements"> Upgrade Requirements</a></li>
   6         <li><a href="#Major Changes Compared to TWiki"> Major Changes Compared to TWiki 01-Feb-2003</a></li>
   7         <li><a href="#Automated Upgrade Procedure from"> Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release</a></li>
   8         <li><a href="#Manual Upgrade Procedure from 01"> Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release</a></li>
   9         <li><a href="#Known Issues"> Known Issues</a></li>
  10       </ul>
  11     </li>
  12   </ul>
  13 </div>
  14
  15 # <a name="TWiki Upgrade Guide"></a> TWiki Upgrade Guide
  16
  17 _Upgrade from the previous TWiki 01-Feb-2003 production release to TWiki 01-Sep-2004_
  18
  19 ## <a name="Overview"></a> Overview
  20
  21 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.
  22
  23 ## <a name="Upgrade Requirements"></a> Upgrade Requirements
  24
  25 - Please review the [[AdminSkillsAssumptions]] before you upgrade TWiki
  26 - To upgrade from a 01-Feb-2003 standard installation to the latest 01-Sep-2004 TWiki Production Release, follow the instructions below
  27 - **_NOTE:_** To upgrade from a **pre-01-Feb-2003** TWiki, start with [[TWikiUpgradeTo01Feb2003]]
  28 - 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
  29
  30 ## <a name="Major Changes Compared to TWiki"></a><a name="Major Changes Compared to TWiki "></a> Major Changes Compared to TWiki 01-Feb-2003
  31
  32 - Automatic upgrade script, and easier first-time installation
  33 - Attractive new skins, using a standard set of CSS classes, and a [[TWikiSkinBrowser]] to help you choose
  34 - New easier-to-use save options
  35 - Many improvements to SEARCH
  36 - Improved support for internationalisation
  37 - Better topic management screens
  38 - More pre-installed Plugins: [[CommentPlugin]], [[EditTablePlugin]], [[RenderListPlugin]], [[SlideShowPlugin]], [[SmiliesPlugin]], [[SpreadSheetPlugin]], [[TablePlugin]]
  39 - Improved Plugins API and more Plugin callbacks
  40 - Better support for different authentication methods
  41 - Many user interface and usability improvements
  42 - And many more enhancements, see the complete change log at [[TWikiHistory]]
  43
  44 ## <a name="Automated Upgrade Procedure from"></a> Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release
  45
  46 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.
  47
  48 If you would prefer to do things manually than trust a beta script, skip to the [[manual upgrade procedure|Main/WebHome#ManualUpgradeProcedure]] below.
  49
  50 The upgrade script is called `"UpgradeTwiki"`, and is found in the root of the distribution.
  51
  52 It will:
  53
  54 - Create a new TWiki installation, placing the files from the distribution there as appropriate
  55 - Where possible, merge the changes you've made in your existing topics into the new twiki
  56 - Where not possible, it will tell you, and you can inspect those differences manually
  57 - Create new configuration files for the new TWiki based on your existing configuation information
  58 - Set the permissions in the new TWiki so that it should work straight away
  59 - Attempt to setup authentication for your new TWiki, if you are using .htaccess in the old one
  60 - Tell you what else you need to do
  61
  62 To perform the upgrade, you need to:
  63
  64 - Check first if there is a newer `UpgradeTwiki` script available, see TWiki:Codev.UpgradeTwiki
  65 - Create a new directory for your new installation: Let's call this `distro/`
  66 - Put the distribution zip file in `distro/`
  67 - Unzip it
  68 - Choose a directory for the new installation. I will call this `new_twiki`. This directory must not already exist.
  69 - Change directory to `distro/` and run: %BR% `./UpgradeTwiki <full path to new_twiki>`
  70
  71 Assuming all goes well, `UpgradeTwiki` will give you the final instructions.
  72
  73 There are a few points worth noting:
  74
  75 - `UpgradeTwiki` may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with
  76 - `UpgradeTwiki` creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:
  77   - Clearly you need to point it to a location where there is enough space
  78   - If you have symlinks under your `data/` directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed
  79 - `UpgradeTwiki` doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation
  80 - If you have done tricky stuff with $OS in your existing `TWiki.cfg` file, then you will need to manually examine the new `TWiki.cfg` file and possibly put your tricky changes in there manually
  81
  82 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.
  83
  84 <a name="ManualUpgradeProcedure"></a>
  85
  86 ## <a name="Manual Upgrade Procedure from 01"></a> Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release
  87
  88 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.
  89
  90 1. **Back up and prepare**:
  91   - Back up all existing TWiki directories `$TWIKIROOT/bin`, `$TWIKIROOT/pub`, `$TWIKIROOT/data`, `$TWIKIROOT/templates`, `$TWIKIROOT/lib`
  92   - Create a temporary directory and unpack the ZIP file there
  93 2. **Update files in TWiki root**:
  94   - Overwrite all `*.html` and `*.txt` files in `$TWIKIROOT` with the new ones
  95 3. **Update template files**:
  96   - Overwrite all template files in `$TWIKIROOT/templates` with the new ones
  97     - If you have customized your templates, make sure to merge those changes back to the new files
  98   - If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files
  99   - Change to **view** templates and skins:
 100     - Add `%BROADCASTMESSAGE%` somewhere on the top of the rendered HTML page (see the new `view.tmpl` for reference)
 101   - Changes to **edit** templates and skins:
 102     - Change the form action from `preview` to `save`: %BR% <code>&lt;form name="main" action="%SCRIPTURLPATH%/**save**%SCRIPTSUFFIX%/%WEB%/%TOPIC%" method="post"&gt;</code>
 103     - Change the topic action to the following: %BR% `%TMPL:DEF{"topicaction"}%` %BR% `<input type="submit" name="action" value="Cancel" id="cancel" />` %BR% `<input type="submit" name="action" value="Preview" id="preview" />` %BR% `<input type="submit" name="action" value="Checkpoint" id="checkpoint" />` %BR% `<input type="submit" name="action" value="QuietSave" id="quietsave" />` %BR% `<input type="submit" name="action" value="Save" id="save" />%TMPL:END%`
 104 4. **Update script files**:
 105   - Overwrite all script files in `$TWIKIROOT/bin` with the new ones.
 106     - If necessary, rename the scrips to include the required extension, e.g. `.cgi`
 107   - Edit `$TWIKIROOT/bin/setlib.cfg` and point `$twikiLibPath` to the **_absolute_** file path of `$TWIKIROOT/lib`
 108   - Edit your existing `$TWIKIROOT/bin/.htaccess` file to include a directive for the new `rdiffauth` script:%BR% `<Files "rdiffauth">` %BR% `    require valid-user` %BR% `</Files>`
 109   - Pay attention to the file and directory permissions, the scripts need to be executable, e.g. `chmod 775 $TWIKIROOT/bin/*`
 110     - Certain hosted environments require a `755` (do so if you get a "Premature end of script headers" messages in the Apache error log)
 111   - 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|Main/WindowsInstallCookbook#Editing_the_CGI_scripts]]
 112 5. **Update library files**:
 113   - Overwrite the `TWiki.cfg` configuration file in `$TWIKIROOT/lib` with the new one
 114   - 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"
 115   - Overwrite the `TWiki.pm` library in `$TWIKIROOT/lib` with the new one
 116   - 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`
 117   - 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)
 118 6. **Update data files**:
 119   - 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:
 120     - 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`
 121     - Run the `testenv` script from your browser; in the %BROWN% **Fix** %ENDCOLOR% line you can <u>relock</u> all the rcs files **(recommended)**
 122     - Alternatively, execute the shell script commands described in [[TWikiInstallationGuide#StepTwo]]
 123   - In the temporary `twiki/data/TWiki` directory where you unzipped the installation package:
 124     - Remove the files you do **not** want to upgrade: `InterWikis.*`, `TWikiRegistration.*`, `TWikiRegistrationPub.*`, `WebPreferences.*`, `WebStatistics.*` and all `WebTopic*` files
 125   - Rename in the temporary directory the file `$TWIKIROOT/data/TWiki/TWikiPreferences.*` to `TWikiPreferencesSave.*`.
 126   - Move all remaining `*.txt` and `*.txt,v` files from the temporary `data/TWiki` directory to your `$TWIKIROOT/data/TWiki` directory, overwriting the existing ones
 127   - Merge your original `TWikiPreferencesSave.txt` settings into `$TWIKIROOT/data/TWiki/TWikiPreferences.txt`. Notable changes are:
 128     - New WIKIWEBMASTERNAME setting to avoid notifications being trapped by spam filters
 129     - New ATTACHFILESIZELIMIT setting for maximum size of [[FileAttachments]] in KB, 0 for no limit
 130     - New READTOPICPREFS and TOPICOVERRIDESUSER settings to allow override Preference settings in topics
 131     - Changed FINALPREFERENCES:
 132       - Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER
 133   - Move the `data/_default` directory from the temporary location to your `$TWIKIROOT/data` directory
 134   - Make sure that the directories and files below `$TWIKIROOT/data` are writable by your cgi-script user
 135 7. **Adapt the other webs (all other than `TWiki` and `_default`)**:
 136   - Add [[WebLeftBar]] topic. See [[WebLeftBarExample]] for a clean example, and [[WebLeftBarCookbook]] for more information. ([[WebLeftBar]] is used by the [[PatternSkin]] skin)
 137   - Add [[WebSearchAdvanced]] topic, which has this one line: %BR% `%INCLUDE{"%TWIKIWEB%.WebSearchAdvanced"}%`
 138   - Consider changing [[WebPreferences]] settings:
 139     - New NOAUTOLINK setting to prevent automatic linking of [[WikiWords]] and acronyms
 140     - Changed FINALPREFERENCES:
 141       - Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
 142 8. **Update pub files**:
 143   - Move all subdirectories below `pub/TWiki` from your temporary directory into your `$TWIKIROOT/pub/TWiki` directory
 144   - Make sure that the directories and files below `$TWIKIROOT/pub/TWiki` are writable by your cgi-script user
 145   - Move all files in `pub/icn` directory from the temporary location to your `$TWIKIROOT/pub/icn` directory
 146 9. **Verify installation**:
 147   - 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
 148   - Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users
 149   - Test if the installed Plugins work as expected. You should see the list of installed Plugins in [[TWiki.WebHome|TWiki/WebHome]]
 150
 151 **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.
 152
 153 ## <a name="Known Issues"></a> Known Issues
 154
 155 - Check TWiki:Codev/KnownIssuesOfTWiki01Sep2004 for known issues of TWiki 01-Sep-2004 production release
 156
 157 -- TWiki:Main.PeterThoeny - 29 Aug 2004 %BR%