head 1.5; access; symbols; locks nobody:1.5; strict; comment @# @; 1.5 date 2004.08.30.06.26.18; author PeterThoeny; state Exp; branches; next 1.4; 1.4 date 2003.02.04.05.19.23; author PeterThoeny; state Exp; branches; next 1.3; 1.3 date 2003.02.02.00.06.00; author PeterThoeny; state Exp; branches; next 1.2; 1.2 date 2003.02.01.12.03.37; author PeterThoeny; state Exp; branches; next 1.1; 1.1 date 2002.12.17.08.46.58; author PeterThoeny; state Exp; branches; next ; desc @none @ 1.5 log @none @ text @%META:TOPICINFO{author="PeterThoeny" date="1093847178" format="1.0" version="1.5"}% %TOC% %STARTINCLUDE% ---# TWiki Upgrade Guide _Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003_ ---++ Overview This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version. ---++ Upgrade Requirements * To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below. * __NOTE:__ To upgrade from a *pre-01-Dec-2001* TWiki, start with %TWIKIWEB%.TWikiUpgradeTo01Dec2001. * 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 from TWiki 01-Dec-2001 * Form and script to [[ManagingWebs][create new webs]] * Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule: =readTopicText=, =saveTopicText=, =setTopicEditLock=, =checkTopicEditLock= * New Plugin hooks =registrationHandler=, =beforeEditHandler=, =afterEditHandler=, =beforeSaveHandler=, =writeHeaderHandler=, =redirectCgiQueryHandler=, =getSessionValueHandler=, =setSessionValueHandler= * Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R * Possible to omit e-mail address in %NOTIFYTOPIC%, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group * New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite) * New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in =%SEARCH{}%= variable, FormattedSearch and WebSearch * Many more enhancements, see the complete change log at TWikiHistory ---++ Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release The following steps describe the upgrade assuming that =$TWIKIROOT= is the root of your current 01-Dec-2001 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 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. * Specific changes to templates and skins: * Replace =%WIKIHOMEURL%= with =%WIKILOGOURL%= * Replace img tag's =src=%PUBURLPATH%/wikiHome.gif= with =src=%WIKILOGOIMG%= * Replace img tag's =alt="TWiki Home"= with =alt="%WIKILOGOALT%"= * Replace meta tag's =charset=iso-8859-1"= with =charset=%CHARSET%"= * Add =%TOPIC%= to form action of GoBox * For internationalized sites, URL encode webs and topics in all form actions, e.g. replace =.../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"= with =.../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%= 1. *Update script files*: * Overwrite all script files in =$TWIKIROOT/bin= with the new ones. * If necessary, change the script names 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 =$TWIKIROOT/bin/.htaccess= to include a directive for the new =manage= script:%BR% =<Files "manage">= %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/*= * If on Non-Unix host, 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, e.g. =chmod -R 664 $TWIKIROOT/lib/*= 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, e.g. =www-data=: * Change the lock user in the temporary =twiki/data/*= directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
=for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done= * 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.*=, =WebNotify.*=, =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=. * Move the =data/_default= directory from the temporary location to your =$TWIKIROOT/data= directory. * Move the =data/Sandbox= directory from the temporary location to your =$TWIKIROOT/data= directory %BR% (The *Test* web has been renamed to *Sandbox* in this release.) * There are now *two webs in parallel* (Test and Sandbox) for the purpose of testing (experimenting) TWiki. %BR% Move all relevant topics from Test web to Sandbox web, or motivate the users to do. * 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=)*: * Merge the new files =WebHome.txt= and =WebPreferences.txt= of your other webs to make sure, you have the improvements applied also in your other webs. 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. *Update TWiki.TWikiPreferences to authorize users to create webs*: * Add =ALLOWWEBMANAGE= to the =FINALPREFERENCES= list so that nobody can overwrite the setting: * Set FINALPREFERENCES = WIKIWEBMASTER, PREVIEWBGIMAGE, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE * Set users or groups allowed to [[TWiki.ManagingWebs][create new webs]]: * Set ALLOWWEBMANAGE = Main.TWikiAdminGroup 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; fix 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 TextFormattingRules. *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/KnownIssuesOfTWiki01Feb2003 for known issues of TWiki 01-Feb-2003 production release -- Main.PeterThoeny - 01 Feb 2002 %BR% -- Main.MartinRaabe - 15 Jan 2003 %META:TOPICMOVED{by="PeterThoeny" date="1093847178" from="TWiki.TWikiUpgradeGuide" to="TWiki.TWikiUpgradeTo01Feb2003"}% @ 1.4 log @none @ text @d1 107 a107 105 %META:TOPICINFO{author="PeterThoeny" date="1044335963" format="1.0" version="1.4"}% %TOC% %STARTINCLUDE% ---# TWiki Upgrade Guide _Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003_ ---++ Overview This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version. ---++ Upgrade Requirements * To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below. * __NOTE:__ To upgrade from a *pre-01-Dec-2001* TWiki, start with %TWIKIWEB%.TWikiUpgradeTo01Dec2001. * 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 from TWiki 01-Dec-2001 * Form and script to [[ManagingWebs][create new webs]] * Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule: =readTopicText=, =saveTopicText=, =setTopicEditLock=, =checkTopicEditLock= * New Plugin hooks =registrationHandler=, =beforeEditHandler=, =afterEditHandler=, =beforeSaveHandler=, =writeHeaderHandler=, =redirectCgiQueryHandler=, =getSessionValueHandler=, =setSessionValueHandler= * Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R * Possible to omit e-mail address in %NOTIFYTOPIC%, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group * New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite) * New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in =%SEARCH{}%= variable, FormattedSearch and WebSearch * Many more enhancements, see the complete change log at TWikiHistory ---++ Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release The following steps describe the upgrade assuming that =$TWIKIROOT= is the root of your current 01-Dec-2001 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 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. * Specific changes to templates and skins: * Replace =%WIKIHOMEURL%= with =%WIKILOGOURL%= * Replace img tag's =src=%PUBURLPATH%/wikiHome.gif= with =src=%WIKILOGOIMG%= * Replace img tag's =alt="TWiki Home"= with =alt="%WIKILOGOALT%"= * Replace meta tag's =charset=iso-8859-1"= with =charset=%CHARSET%"= * Add =%TOPIC%= to form action of GoBox * For internationalized sites, URL encode webs and topics in all form actions, e.g. replace =.../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"= with =.../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%= 1. *Update script files*: * Overwrite all script files in =$TWIKIROOT/bin= with the new ones. * If necessary, change the script names 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 =$TWIKIROOT/bin/.htaccess= to include a directive for the new =manage= script:%BR% =<Files "manage">= %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/*= * If on Non-Unix host, 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, e.g. =chmod -R 664 $TWIKIROOT/lib/*= 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, e.g. =www-data=: * Change the lock user in the temporary =twiki/data/*= directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
=for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done= * 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.*=, =WebNotify.*=, =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=. * Move the =data/_default= directory from the temporary location to your =$TWIKIROOT/data= directory. * Move the =data/Sandbox= directory from the temporary location to your =$TWIKIROOT/data= directory %BR% (The *Test* web has been renamed to *Sandbox* in this release.) * There are now *two webs in parallel* (Test and Sandbox) for the purpose of testing (experimenting) TWiki. %BR% Move all relevant topics from Test web to Sandbox web, or motivate the users to do. * 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=)*: * Merge the new files =WebHome.txt= and =WebPreferences.txt= of your other webs to make sure, you have the improvements applied also in your other webs. 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. *Update TWiki.TWikiPreferences to authorize users to create webs*: * Add =ALLOWWEBMANAGE= to the =FINALPREFERENCES= list so that nobody can overwrite the setting: * Set FINALPREFERENCES = WIKIWEBMASTER, PREVIEWBGIMAGE, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE * Set users or groups allowed to [[TWiki.ManagingWebs][create new webs]]: * Set ALLOWWEBMANAGE = Main.TWikiAdminGroup 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; fix 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 TextFormattingRules. *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/KnownIssuesOfTWiki01Feb2003 for known issues of TWiki 01-Feb-2003 production release -- Main.PeterThoeny - 01 Feb 2002 %BR% -- Main.MartinRaabe - 15 Jan 2003 @ 1.3 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="PeterThoeny" date="1044144360" format="1.0" version="1.3"}% d49 1 a49 1 * Replace meta tag's =charset=iso-8859-1"= with =charset=%CHARSET%"= @ 1.2 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="PeterThoeny" date="1044101017" format="1.0" version="1.2"}% d28 1 a28 1 * New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands d44 8 a51 1 * If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files. d84 1 a84 1 1. *Update pub/TWiki files*: d87 1 @ 1.1 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="PeterThoeny" date="1040114818" format="1.0" version="1.1"}% d7 1 a7 1 _Upgrade from TWiki 01-Dec-2001 to TWiki 01-Jan-2003 (previous to new full release)_ d11 1 a11 1 This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Jan-2003. The new version involves several new features and numerous enhancements to the previous version. d15 1 a15 1 * To upgrade from a 01-Dec-2001 standard installation to the latest 01-Jan-2003 TWiki Production Release, follow the instructions below. d23 8 a30 2 * *AND Search* - With regular expression enabled, use =";"= as the AND operator in FormattedSearch and WebSearch * (to be completed) d32 1 a32 1 ---++ Upgrade Procedure from 01-Dec-2001 to 01-Jan-2003 Release d34 1 a34 3 The following steps describe the upgrade assuming that =$TWIKIROOT= is the root of your current 01-Dec-2001 release. *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. d37 1 a37 1 * Back up all existing TWiki directories =$TWIKIROOT/bin=, =$TWIKIROOT/pub=, =$TWIKIROOT/data=, =$TWIKIROOT/templates=. d43 2 d47 1 a47 1 * If necessary, change the script names to include the required extension, ex: =.cgi= d49 6 a54 1 * Pay attention to the file and directory permissions, the scripts need to be executable, e.g. 775. a55 1 * Make a backup copy of =$TWIKIROOT/lib/TWiki.cfg= to =TWiki.cfg.save= d60 1 a60 1 * Pay attention to the file and directory permissions, the library files should not be executable, but set to e.g. 664. d63 1 a63 1 * 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, e.g., =www-data=: d67 3 a69 3 * Remove the files you do *not* want to upgrade: =InterWikis.*=, =TWikiRegistration.*=, =WebNotify.*=, =WebPreferences.*=, =WebStatistics.*= and all =WebTopic*= files. * Rename =$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. d71 3 a73 2 * Move all =*.txt= and =*.txt,v= files from the temporary =data/_default= directory to your =$TWIKIROOT/data/_default= directory. * Move the =data/Sandbox= directory from the temporary location to your =$TWIKIROOT/data= directory. d75 2 d80 5 d90 1 a90 3 ---++ General Format Changes * (to be written) d94 1 a94 1 * Check TWiki:Codev/KnownIssuesOfTWiki01Jan2003 for known issues of TWiki 01 Jan 2003 (production release) d96 2 a97 1 -- Main.PeterThoeny - 17 Dec 2002 @