stale_content1Add my vote for this tag create new tag
, view all tags

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.

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:

  • 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 more robust.

Manual Upgrade

If you want to upgrade manually, you basically have to do the things that are described above that UpgradeTWiki tries to do for you:

  • Unpack
  • 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
    • This is particularly important for topics that contain configuration information, such as TWikiPreferences, WebPreferences etc and well as Main.Users
  • 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.

  • Add both settings to FINALPREFERENCES:
  • Site-level preferences that are not allowed to be overridden by WebPreferences and user preferences:

-- MartinGregory - 16 Aug 2004


Added pointer to WebLeftBarExample.

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

-- MartinGregory - 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 page.)

-- AlanDayley - 03 Nov 2004

Edit | Attach | Watch | Print version | History: r32 < r31 < r30 < r29 < r28 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r32 - 2005-06-24 - FranzJosefSilli
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.