%TOC%
%STARTINCLUDE%
---# 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 %TWIKIWEB%.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 [[#ManualUpgradeProcedure][manual upgrade procedure]] 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 <full path to new_twiki>=
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.
#ManualUpgradeProcedure
---++ 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
1. *Update files in TWiki root*:
* Overwrite all =*.html= and =*.txt= files in =$TWIKIROOT= with the new ones
1. *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%
=<input type="submit" class="twikiSubmit" name="action" value="Cancel" id="cancel" />= %BR%
=<input type="submit" class="twikiSubmit" name="action" value="Preview" id="preview" />= %BR%
=<input type="submit" class="twikiSubmit" name="action" value="Checkpoint" id="checkpoint" />= %BR%
=<input type="submit" class="twikiSubmit" name="action" value="QuietSave" id="quietsave" />= %BR%
=<input type="submit" class="twikiSubmit" name="action" value="Save" id="save" />%TMPL:END%=
1. *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%
=<Files "rdiffauth">= %BR%
= require valid-user= %BR%
=</Files>=
* 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#Editing_the_CGI_scripts][WindowsInstallCookbook]]
1. *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)
1. *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
1. *Adapt the other webs (all other than =TWiki= and =_default=)*:
* Add WebLeftBar topic. See WebLeftBarExample for a clean example, and TWiki.WebLeftBarCookbook for more information. (WebLeftBar is used by the TWiki.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
1. *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
1. *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 [[%TWIKIWEB%.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%
%STOPINCLUDE%