Cairo Release Upgrade Guide
With the Cairo Release, for the first time, comes a helper script for
upgrading from a previous version.
This feature is still beta - it's the first time it's been released! Thus there is the potential for it not to do quite what you wanted.
However, it should be worth giving it a try: it won't mess up your existing
TWiki installation: it leaves that untouched.
If you would prefer to do things manually than trust a beta script,
some instructions are further below.
Using the Upgrade Script
The upgrade script is called "UpgradeTWiki", and is found in the
root of the distribution.
- 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:
- Create a new directory for your new installation: I will 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:
./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.
As of the time of writing this guide, UpgradeTWiki
has only been tested under Unix, and not heavily
tested at that. That's why it's beta.
If you use it, and would be kind enough to add your experiences to the comments below, it would be much appreciated. The report of your experience will help to make UpgradeTWiki
If you want to upgrade manually, you basically have to do the things that are described above that UpgradeTWiki
tries to do for you:
- Update bin/setlib.cfg to match the existing one
- Update lib/TWiki.cfg to match your existing one (can be non-trivial if you made many setup changes)
- Merge changes you made in your existing installation's topics with the new topic files that come with the distribution
- Setup the new bin/.htaccess appropriately
- Setup authentication for the new installation appropriately: if you are using .htpasswd, then it is as simple as copying the existing one in data/ to the new data/ directory
- Set file access privileges appropriately: your web server needs to have read & write on pub/ and data/, and should not have access to templates or lib.
- Reinstall Plugins and custom templates
- For each existing web:
---++ Preferences Control Settings
* Allow topic level preferences, on or off: If set to =on=, topic preferences will be read, and will override any web- or site-level preferences not set as =FINALPREFERENCES=. By default, user preferences will override topic preferences.
* Set READTOPICPREFS = on
* Topic level overrides user level preferences, on or off: If set to =on=, topic preferences will override user preferences. The user can in turn override this behavior by setting further =FINALPREFERENCES= in his or her user topic.
* Set TOPICOVERRIDESUSER = off
- Add both settings to FINALPREFERENCES:
- Site-level preferences that are not allowed to be overridden by WebPreferences and user preferences:
- Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER
- 16 Aug 2004
Added pointer to WebLeftBarExample
(attribution by MG
Made pointer to WebLeftBarExample
point to something that exists.
In the process, took out an interwiki link. Not sure what the original intent was.
Added pointer to WebLeftBarCookbook
and reference to PatternSkin
- 16 Aug 2004
I have successfully used UpgradeTWiki
in a first-try test. I plan to go live with the upgrade after I have mapped out and planned for all remaining issues not handled by the script. (Moved further issue discussion to UpgradeTWiki
- 03 Nov 2004