# TWiki Upgrade Guide
_Upgrade from the previous TWiki 01-Feb-2003 production release to TWiki 01-Sep-2004_
## Overview
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.
## Upgrade Requirements
- Please review the [[AdminSkillsAssumptions]] before you upgrade TWiki
- To upgrade from a 01-Feb-2003 standard installation to the latest 01-Sep-2004 TWiki Production Release, follow the instructions below
- **_NOTE:_** To upgrade from a **pre-01-Feb-2003** TWiki, start with [[TWikiUpgradeTo01Feb2003]]
- 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 Compared to TWiki 01-Feb-2003
- Automatic upgrade script, and easier first-time installation
- Attractive new skins, using a standard set of CSS classes, and a [[TWikiSkinBrowser]] to help you choose
- New easier-to-use save options
- Many improvements to SEARCH
- Improved support for internationalisation
- Better topic management screens
- More pre-installed Plugins: [[CommentPlugin]], [[EditTablePlugin]], [[RenderListPlugin]], [[SlideShowPlugin]], [[SmiliesPlugin]], [[SpreadSheetPlugin]], [[TablePlugin]]
- Improved Plugins API and more Plugin callbacks
- Better support for different authentication methods
- Many user interface and usability improvements
- And many more enhancements, see the complete change log at [[TWikiHistory]]
## Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release
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.
If you would prefer to do things manually than trust a beta script, skip to the [[manual upgrade procedure|Main/WebHome#ManualUpgradeProcedure]] below.
The upgrade script is called `"UpgradeTwiki"`, and is found in the root of the distribution.
It will:
- Create a new TWiki installation, placing the files from the distribution there as appropriate
- Where possible, merge the changes you've made in your existing topics into the new twiki
- Where not possible, it will tell you, and you can inspect those differences manually
- Create new configuration files for the new TWiki based on your existing configuation information
- Set the permissions in the new TWiki so that it should work straight away
- Attempt to setup authentication for your new TWiki, if you are using .htaccess in the old one
- Tell you what else you need to do
To perform the upgrade, you need to:
- Check first if there is a newer `UpgradeTwiki` script available, see TWiki:Codev.UpgradeTwiki
- Create a new directory for your new installation: Let's call this `distro/`
- Put the distribution zip file in `distro/`
- Unzip it
- Choose a directory for the new installation. I will call this `new_twiki`. This directory must not already exist.
- Change directory to `distro/` and run: %BR% `./UpgradeTwiki `
Assuming all goes well, `UpgradeTwiki` will give you the final instructions.
There are a few points worth noting:
- `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
- `UpgradeTwiki` creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:
- Clearly you need to point it to a location where there is enough space
- 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
- `UpgradeTwiki` doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation
- 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
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.
## Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release
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.
1. **Back up and prepare**:
- Back up all existing TWiki directories `$TWIKIROOT/bin`, `$TWIKIROOT/pub`, `$TWIKIROOT/data`, `$TWIKIROOT/templates`, `$TWIKIROOT/lib`
- Create a temporary directory and unpack the ZIP file there
2. **Update files in TWiki root**:
- Overwrite all `*.html` and `*.txt` files in `$TWIKIROOT` with the new ones
3. **Update template files**:
- Overwrite all template files in `$TWIKIROOT/templates` with the new ones
- If you have customized your templates, make sure to merge those changes back to the new files
- If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files
- Change to **view** templates and skins:
- Add `%BROADCASTMESSAGE%` somewhere on the top of the rendered HTML page (see the new `view.tmpl` for reference)
- Changes to **edit** templates and skins:
- Change the form action from `preview` to `save`: %BR% <form name="main" action="%SCRIPTURLPATH%/**save**%SCRIPTSUFFIX%/%WEB%/%TOPIC%" method="post">
- Change the topic action to the following: %BR% `%TMPL:DEF{"topicaction"}%` %BR% `` %BR% `` %BR% `` %BR% `` %BR% `%TMPL:END%`
4. **Update script files**:
- Overwrite all script files in `$TWIKIROOT/bin` with the new ones.
- If necessary, rename the scrips to include the required extension, e.g. `.cgi`
- Edit `$TWIKIROOT/bin/setlib.cfg` and point `$twikiLibPath` to the **_absolute_** file path of `$TWIKIROOT/lib`
- Edit your existing `$TWIKIROOT/bin/.htaccess` file to include a directive for the new `rdiffauth` script:%BR% `` %BR% ` require valid-user` %BR% ``
- Pay attention to the file and directory permissions, the scripts need to be executable, e.g. `chmod 775 $TWIKIROOT/bin/*`
- Certain hosted environments require a `755` (do so if you get a "Premature end of script headers" messages in the Apache error log)
- 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]]
5. **Update library files**:
- Overwrite the `TWiki.cfg` configuration file in `$TWIKIROOT/lib` with the new one
- 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"
- Overwrite the `TWiki.pm` library in `$TWIKIROOT/lib` with the new one
- 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`
- 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)
6. **Update data files**:
- 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:
- 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`
- Run the `testenv` script from your browser; in the %BROWN% **Fix** %ENDCOLOR% line you can relock all the rcs files **(recommended)**
- Alternatively, execute the shell script commands described in [[TWikiInstallationGuide#StepTwo]]
- In the temporary `twiki/data/TWiki` directory where you unzipped the installation package:
- Remove the files you do **not** want to upgrade: `InterWikis.*`, `TWikiRegistration.*`, `TWikiRegistrationPub.*`, `WebPreferences.*`, `WebStatistics.*` and all `WebTopic*` files
- Rename in the temporary directory the file `$TWIKIROOT/data/TWiki/TWikiPreferences.*` to `TWikiPreferencesSave.*`.
- Move all remaining `*.txt` and `*.txt,v` files from the temporary `data/TWiki` directory to your `$TWIKIROOT/data/TWiki` directory, overwriting the existing ones
- Merge your original `TWikiPreferencesSave.txt` settings into `$TWIKIROOT/data/TWiki/TWikiPreferences.txt`. Notable changes are:
- New WIKIWEBMASTERNAME setting to avoid notifications being trapped by spam filters
- New ATTACHFILESIZELIMIT setting for maximum size of [[FileAttachments]] in KB, 0 for no limit
- New READTOPICPREFS and TOPICOVERRIDESUSER settings to allow override Preference settings in topics
- Changed FINALPREFERENCES:
- Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER
- Move the `data/_default` directory from the temporary location to your `$TWIKIROOT/data` directory
- Make sure that the directories and files below `$TWIKIROOT/data` are writable by your cgi-script user
7. **Adapt the other webs (all other than `TWiki` and `_default`)**:
- Add [[WebLeftBar]] topic. See [[WebLeftBarExample]] for a clean example, and [[WebLeftBarCookbook]] for more information. ([[WebLeftBar]] is used by the [[PatternSkin]] skin)
- Add [[WebSearchAdvanced]] topic, which has this one line: %BR% `%INCLUDE{"%TWIKIWEB%.WebSearchAdvanced"}%`
- Consider changing [[WebPreferences]] settings:
- New NOAUTOLINK setting to prevent automatic linking of [[WikiWords]] and acronyms
- Changed FINALPREFERENCES:
- Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
8. **Update pub files**:
- Move all subdirectories below `pub/TWiki` from your temporary directory into your `$TWIKIROOT/pub/TWiki` directory
- Make sure that the directories and files below `$TWIKIROOT/pub/TWiki` are writable by your cgi-script user
- Move all files in `pub/icn` directory from the temporary location to your `$TWIKIROOT/pub/icn` directory
9. **Verify installation**:
- 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
- Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users
- Test if the installed Plugins work as expected. You should see the list of installed Plugins in [[TWiki.WebHome|TWiki/WebHome]]
**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.
## Known Issues
- Check TWiki:Codev/KnownIssuesOfTWiki01Sep2004 for known issues of TWiki 01-Sep-2004 production release
-- TWiki:Main.PeterThoeny - 29 Aug 2004 %BR%