wiki-archive/twiki/data/TWiki/TWikiUpgradeGuide.txt,v

head	1.5;
access;
symbols;
locks; strict;
comment	@# @;


1.5
date	2007.01.16.04.12.02;	author TWikiContributor;	state Exp;
branches;
next	1.4;

1.4
date	2006.06.25.16.26.27;	author TWikiContributor;	state Exp;
branches;
next	1.3;

1.3
date	2006.04.01.05.55.16;	author TWikiContributor;	state Exp;
branches;
next	1.2;

1.2
date	2006.02.01.12.01.20;	author TWikiContributor;	state Exp;
branches;
next	1.1;

1.1
date	2004.08.30.06.29.41;	author PeterThoeny;	state Exp;
branches;
next	;


desc
@none
@


1.5
log
@buildrelease
@
text
@%META:TOPICINFO{author="TWikiContributor" date="1168726854" format="1.1" version="5"}%
%TOC%
%STARTINCLUDE%
---# TWiki Upgrade Guide

_Upgrade from the previous TWiki 01-Sep-2004 Production Release to TWiki-4.X_

---++ Overview

TWiki-4.0.0 was a major new release. TWiki-4.1.0 is a minor release without dramatic changes since 4.0.0

---++ Upgrade Requirements

   * Please review the AdminSkillsAssumptions before you upgrade TWiki
   * Review TWiki:TWiki.TWikiUpgradeTo04x00x00 for latest information and experience notes.
   * To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
   * To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.X Production Release, follow the instructions below
   * 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!
   * 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!

---++ Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0

See TWikiReleaseNotes04x00 and TWikiReleaseNotes04x01


#ManualUpgradeProcedure
---++ Upgrade Procedure

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.

The main steps are:

   1 Install the new TWiki version, configure it, and get it to work similar to the old version
   1 Install additional extensions (Plugins). Make sure to use the latest versions
   1 Copy all the non-default webs from the old installation to the new
   1 Copy the users from old installation to the new incl all their topics from Main
   1 Apply tailorings to your Skin (logos, menu bars etc)
   1 Apply preferences from old installation
   
---+++ Installation

   * 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.
   * Use the [[%SCRIPTURL{configure}%][configure]] script to configure TWiki.
      * If you are upgrading from a 4.0.x release, carry over the configure settings from the old release.
   * Additional resources
      * TWiki:TWiki.UpgradingTWiki04x00PatchReleases
      * TWiki:TWiki.InstallingTWiki#OtherPlatforms
      * TWiki:TWiki.ApacheConfigGenerator
      * TWiki:TWiki.SettingFileAccessRightsLinuxUnix
      * 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.
   * Make sure you have a working basic TWiki before you continue

---+++ Install Extensions

   * 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.
   * From TWiki-4.1.0 the [[%SCRIPTURLPATH{"configure"}%][configure]] script which you ran during installation supports installation of additional plugins.
   * Manual installation is possible. Follow the instruction on the Plugin page at twiki.org.
   * 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 [[%LOCALSITEPREFS%]] 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 <nop>%LOCALSITEPREFS%.
   * Typical plugin settings you may have altered.
      *  CommentPlugin - Set DEFAULT_TYPE
      * EditTablePlugin - Set CHANGEROWS, Set QUIETSAVE, and Set EDITBUTTON
      * InterwikiPlugin - Set RULESTOPIC
      * InterWikis - If you added your own rules you should save this topic and not overwrite it.
      * 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.
      * SmiliesPlugin - Did you add your own smileys? No smileys were added 4.0.0 and 4.0.2 so you can just leave this topic as it is.
      * TablePlugin - Set TABLEATTRIBUTES   
   * Remember that a plugin must be activated in [[%SCRIPTURLPATH{"configure"}%][configure]].

---+++ Copy your old webs to new TWiki

   * 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:
      * =find data -name '*,v' -exec rcs -u -M '{}' \;=
      * =find pub -name '*,v' -exec rcs -u -M '{}' \;=
   * 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.
   
---+++ Copy Users And Their Topics From Main Web

   * 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!
   * Manually merge all the users from the old =TWiki.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.
   * If you use =data/.htpasswd= for authentication copy this file from the old TWiki to the new.
      * 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 database. There is a script that performs this extra upgrade step for you - see =tools/upgrade_emails.pl=.
   * 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.

---+++ Apply Customizations To The Skin

   * Not many of the old Cairo skins work well with TWiki4.X.
   * Add Logos, update top bar and left bar as required.
   * 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.
   * Additional resources:
      * TWiki:TWiki.UpgradingTWiki04x00PatchReleases
      * PatternSkinCustomization
      * PatternSkinCssCookbook      
   
---+++ Apply Preferences From Old Installation

   * Transfer any customized and local settings from [[%TWIKIWEB%.TWikiPreferences]] to the topic pointed at by {LocalSitePreferences} ([[%LOCALSITEPREFS%]]). Per default this is =Main.TWikiPreferences=. This avoids having to write over files in the distribution on a later upgrade.
   * 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.
   * 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.
   * 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.

---++ Upgrading from Cairo to TWiki4 (additional advice)

---+++ Favicon

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.

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.

   * Attach a favicon.ico file to !WebPreferences in each web.
   * 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.

To change the location of favicon.ico in !TWikiPreferences to the TWiki web add this line to Main.TWikiPreferences

<verbatim>
   * Set FAVICON = %PUBURLPATH%/%TWIKIWEB%/%WEBPREFSTOPIC%/favicon.ico
</verbatim>

---+++ !TWikiUsers topic in Main web

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
   * *TWikiContributor* - placeholder for a TWiki developer, and is used in TWiki documentation
   * *TWikiGuest* - guest user, used as a fallback if the user can't be identified
   * *TWikiRegistrationAgent* - special user used during the new user registration process
   * *UnknownUser* - used where the author of a previously stored piece of data can't be determined


You additionally need to ensure that !TWikiUsers has the =Set ALLOWTOPICCHANGE = !TWikiAdminGroup, !TWikiRegistrationAgent=. Otherwise people will not be able to register.

%STOPINCLUDE%

__Related Topics:__ AdminDocumentationCategory, TWiki:TWiki.UpgradingTWiki, TWiki:TWiki.UpgradingTWiki04x00PatchReleases, TWiki:TWiki.InstallingTWiki#OtherPlatforms, TWiki:TWiki.ApacheConfigGenerator, TWiki:TWiki.SettingFileAccessRightsLinuxUnix

@


1.4
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1147664322" format="1.1" version="4"}%
d6 1
a6 1
_Upgrade from the previous TWiki 01-Sep-2004 Prodcution Release to TWiki-4.0.0_
d10 1
a10 1
TWiki-4.0.0 is a major new release. You can chose between an automated upgrade using a script or a manual update.
d17 1
a17 1
   * To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.0.0 Production Release, follow the instructions below
d19 1
a19 1
   * Not all Plugins written for TWiki Release 01-Sep-2004 are fully supported with Dakar. Make sure the Plugins you use can be upgraded as well!
d21 1
a21 1
---++ Major Changes Compared to TWiki Release 01-Sep-2004
d23 1
a23 45
See TWikiReleaseNotes04x00.

---++ Automated Upgrade Procedure

If you would prefer to do things manually, *or if you made custom modifications to distributed files* (except topics), then skip to the [[#ManualUpgradeProcedure][manual upgrade procedure]] below.

The upgrade script is called ="UpgradeTwiki"=, and is found in the root of the distribution. It can be run by any user, though you will need to make sure you correct the permissions so that the webserver user can write all files in the new installation when you have finished. The upgrade script does *not* write to your existing installation.

The upgrade script will upgrade the *TWiki core only*. Plugins will need to be upgraded separately.

Note: To upgrade from a Beta, *do not* use !UpgradeTWiki. Instead follow the steps outlined in [[#Upgrading_a_Beta][Upgrading a Beta]], below.

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 and attachments 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 existing_twiki's setlib.cfg&gt; &lt;full path to new_twiki&gt;=
   * confirm your system settings by pointing your browser to the =configure= script

Assuming all goes well, =UpgradeTwiki= will give you the final instructions.

Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.

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 are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password database. There is a script that performs this extra upgrade step for you - see =tools/upgrade_emails.pl=.
d27 1
a27 1
---++ Manual Upgrade Procedure
d31 70
a100 28
   1 Follow the installation instructions, and install the new release in a new directory.
   1 Copy your local webs over to the data and pub directories of the new install
      * You could also use softlinks to link the web directories in data and pub to the old installation area
   1 Unlock the rcs files in data and pub directories from the old installation using the following shell commands:
      * =find data -name '*,v' -exec rcs -r -u -M '{}' \;=
      * =find pub -name '*,v' -exec rcs -r -u -M '{}' \;=
   1 Examine your old TWiki.cfg, and for each local setting, set the corresponding value in the =configure= interface for the new install.
      *  If you can't use =configure=, then copy the *new* =TWiki.cfg= to =LocalSite.cfg=, and edit =LocalSite.cfg=. Remove all the settings that you didn't change in your previous install, and change the remaining settings to the values from your *old* TWiki.cfg.
   1 Transfer any customized and local settings from [[%TWIKIWEB%.TWikiPreferences]] to the topic pointed at by {LocalSitePreferences} ([[%LOCALSITEPREFS%]]). This avoids having to write over files in the distribution.
   1 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 the following procedure may help:
      1 Install a copy of the original TWiki release you were using in a temporary directory
      1 Use 'diff' to find changed files, and transfer the changes into the new Dakar install.
      1 Install updated plugins into your new area.
   1 Point your webserver at the new install.
   1 Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.
   1 If you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password database. There is a script that performs this extra upgrade step for you - see =tools/upgrade_emails.pl=.

You are *highly* recommended *not* to change any distributed files if you can avoid it, to simplify future upgrades!

---++ Upgrading a Beta
*If* you followed the recommendations and avoided modifying any distributed files, then this is quite straightforward:
   1 Follow the installation instructions, and install the new release in a new directory.
   1 Copy your local webs over to the data and pub directories of the new install
      * Be careful to copy over the user topics and TWikiUsers.txt in the Main web
   1 Copy over your =bin/LocalLib.cfg= and =lib/LocalSite.cfg= files
   1 Copy over any local files you created (such as .htpasswd and .htaccess files)
   1 Point your webserver at the new install.
*If* you changed any of the distributed files, you will have to continue from Step 5 above.
d111 1
a111 1
   * 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.
d119 11
d132 1
a132 1
__Related Topics:__ AdminDocumentationCategory, TWiki:TWiki.UpgradingTWiki
@


1.3
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1127433585" format="1.1" version="3"}%
d23 1
a23 1
See TWikiReleaseNotes04x00x00.
d104 17
@


1.2
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1127433585" format="1.1" version="2"}%
d14 6
a19 6
	* Please review the AdminSkillsAssumptions before you upgrade TWiki
	* Review TWiki:TWiki.TWikiUpgradeTo04x00x00 for latest information and experience notes.
	* To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
	* To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.0.0 Production Release, follow the instructions below
	* 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!
	* Not all Plugins written for TWiki Release 01-Sep-2004 are fully supported with Dakar. Make sure the Plugins you use can be upgraded as well!
d37 7
a43 7
	* 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 and attachments 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
d47 8
a54 8
	* 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 existing_twiki's setlib.cfg&gt; &lt;full path to new_twiki&gt;=
	* confirm your system settings by pointing your browser to =cgi-bin/configure=
d62 6
a67 5
	* =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.
a68 1
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.
d75 16
a90 15
	1 Follow the installation instructions, and install the new release in a new directory.
	1 Copy your local webs over to the data and pub directories of the new install
		* You could also use softlinks to link the web directories in data and pub to the old installation area
	1 Unlock the rcs files in data and pub directories from the old installation using the following shell commands:
		* =find data -name '*,v' -exec rcs -r -u -M '{}' \;=
		* =find pub -name '*,v' -exec rcs -r -u -M '{}' \;=
	1 Examine your old TWiki.cfg, and for each local setting, set the corresponding value in the =configure= interface for the new install.
		*  If you can't use =configure=, then copy the *new* =TWiki.cfg= to =LocalSite.cfg=, and edit =LocalSite.cfg=. Remove all the settings that you didn't change in your previous install, and change the remaining settings to the values from your *old* TWiki.cfg.
	1 Transfer any customized and local settings from [[%TWIKIWEB%.TWikiPreferences]] to the topic pointed at by {LocalSitePreferences} ([[%LOCALSITEPREFS%]]). This avoids having to write over files in the distribution.
	1 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 the following procedure may help:
		1 Install a copy of the original TWiki release you were using in a temporary directory
		1 Use 'diff' to find changed files, and transfer the changes into the new Dakar install.
		1 Install updated plugins into your new area.
	1 Point your webserver at the new install.
	1 Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.
d96 6
a101 4
	1 Follow the installation instructions, and install the new release in a new directory.
	1 Copy your local webs over to the data and pub directories of the new install
	1 Copy over your =bin/setlib.cfg= and =lib/LocalLib.cfg= files
	1 Point your webserver at the new install.
@


1.1
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="PeterThoeny" date="1093847381" format="1.0" version="1.1"}%
d6 1
a6 1
_Upgrade from the previous TWiki 01-Feb-2003 production release to TWiki 01-Sep-2004_
d10 1
a10 1
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.
d15 5
a19 3
	* 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
d21 1
a21 1
---++ Major Changes Compared to TWiki 01-Feb-2003
d23 1
a23 11
	* 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
d25 1
d27 1
a27 1
---++ Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release
d29 1
a29 2
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.
d31 1
a31 1
If you would prefer to do things manually than trust a beta script, skip to the [[#ManualUpgradeProcedure][manual upgrade procedure]] below.
d33 1
a33 1
The upgrade script is called ="UpgradeTwiki"=, and is found in the root of the distribution.
d38 1
a38 1
	* Where possible, merge the changes you've made in your existing topics into the new twiki
d47 1
a47 1
	* Check first if there is a newer =UpgradeTwiki= script available, see TWiki:Codev.UpgradeTwiki
d53 2
a54 1
	  =./UpgradeTwiki &lt;full path to new_twiki&gt;=
d58 2
d66 1
a66 2
	* =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
d68 1
a68 1
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.
d71 1
a71 1
---++ Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release
d73 1
a73 1
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.
d75 25
a99 71
	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]]
d101 1
a101 3
*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
d103 1
a103 5
	* Check TWiki:Codev/KnownIssuesOfTWiki01Sep2004 for known issues of TWiki 01-Sep-2004 production release

-- TWiki:Main.PeterThoeny - 29 Aug 2004 %BR%

%STOPINCLUDE%
@