%META:TOPICINFO{author="PeterThoeny" date="1093847381" format="1.0" version="1.1"}%
%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 &lt;full path to new_twiki&gt;=

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 =%<nop>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%
			  =&lt;form name="main" action="%<nop>SCRIPTURLPATH%/<b>save</b>%<nop>SCRIPTSUFFIX%/%<nop>WEB%/%<nop>TOPIC%" method="post"&gt;=
			* Change the topic action to the following: %BR%
			  =%<nop>TMPL:DEF{"topicaction"}%= %BR%
		=&lt;input type="submit" class="twikiSubmit" name="action" value="Cancel" id="cancel" /&gt;= %BR%
		=&lt;input type="submit" class="twikiSubmit" name="action" value="Preview" id="preview" /&gt;= %BR%
		=&lt;input type="submit" class="twikiSubmit" name="action" value="Checkpoint" id="checkpoint" /&gt;= %BR%
		=&lt;input type="submit" class="twikiSubmit" name="action" value="QuietSave" id="quietsave" /&gt;= %BR%
			  =&lt;input type="submit" class="twikiSubmit" name="action" value="Save" id="save" /&gt;%<nop>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%
		  =&lt;Files "rdiffauth"&gt;= %BR%
		  =&nbsp; &nbsp; require valid-user= %BR%
		  =&lt;/Files&gt;=
		* 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 <u>relock</u> 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:
				* <nop>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%
		  =%<nop>INCLUDE{"%<nop>TWIKIWEB%.WebSearchAdvanced"}%=
		* Consider changing WebPreferences settings:
			* New NOAUTOLINK setting to prevent automatic linking of WikiWords and acronyms
			* Changed FINALPREFERENCES:
				* <nop>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%

