TWikiUpgradeGuide < TWiki

Webs
Main
Sandbox
TWiki
You are here: FS > TWiki Web > TWikiUpgradeGuide	r2 - 22 Sep 2005 - 23:59 - TWikiContributor
EditAttachPrintable
Start of topic | Skip to actions
%TOC%
%STARTINCLUDE%
---# TWiki Upgrade Guide

Upgrade from the previous TWiki Sep-2004 "Cairo" production release to TWiki "Dakar"

---++ Overview

Dakar 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 Cairo standard installation to the latest Dakar Production Release, follow the instructions below
	* __NOTE:__ To upgrade from a *pre-Cairo* TWiki, start with %TWIKIWEB%.TWikiUpgradeToCairo
	* To upgrade from a Beta of the new release, or if you made custom modifications, read through all new reference documentation, then use the procedure below as a guideline
	* Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but will not be able to write. Make sure you take a backup!
	* Not all Cairo plugins are supported with Dakar. Make sure the plugins you use can be upgraded as well!

---++ Major Changes Compared to TWiki Cairo

SEE TWiki:Codev.DakarReleaseNotes FOR NOW

---++ Automated Upgrade Procedure

If you would prefer to do things manually, 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 permissions so 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.

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 =cgi-bin/configure=

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 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

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.

	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 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 local settings from TWiki.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (usually Main.TWikiPreferences). 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.

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

%STOPINCLUDE%

__Related Topics:__ AdminDocumentationCategory
End of topic
Skip to actions | Back to top
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding FS? Send feedback