1. shut down apache so nobody can make changes post-backup.
2. cd /usr/local ; mkdir tmp ; tar zcf tmp/www20050122.tgz www/ - wow, it's 174MB.
3. refer to http://twiki.org/cgi-bin/view/Codev/UpgradeTwiki
4. I had the new distfile already. So cd /usr/local/tmp ; cp /usr/ports/distfiles/TWiki20040902.zip .
5. Unzip that, then examine UpgradeTwiki. Looks like it needs to know old location and it'll put merged files in a third place.
6. cd /usr/local/www ; mv twiki twiki-old
7. cd /usr/local/tmp/tw ; ./UpgradeTwiki - tell it /usr/local/www/twiki-old/bin when it asks where setlib.cfg is.

It said:

That means that there should be all the normal TWiki directories here: bin, lib, pub, templates etc. right here.

Here's what's about to happen:

1) I'm going to create a new TWiki in /usr/local/www/twiki based on this new distribution
2) I'm going to update the TWiki.cfg in /usr/local/www/twiki/lib to match the existing one in your current TWiki
3) I'm going to merge the new TWiki data files from the release with all your existing information
4) I'm going to tell you what you need to do next!

First, you need to tell me where I can get config info about your existing TWiki.

Please tell me a path to either the setlib.cfg (preferred) or the TWiki.cfg...
/usr/local/www/twiki-old/bin
First, creating /usr/local/www/twiki structures...
bin
index.html
lib
license.txt
pub
pub-htaccess.txt
readme.txt
robots.txt
root-htaccess.txt
subdir-htaccess.txt
templates
TWikiDocumentation.html
TWikiHistory.html
UpgradeTwiki
Preparing to write a new format configuration file for you...


Great - found it OK, and it tells me that the rest of the config is in ../lib,
so that's where I'll be looking!

First, making a new copy of setlib.cfg in your new installation...
.../usr/local/www/twiki-old/bin/setlib.cfg has been copied into /usr/local/www/twiki/bin
Now reading the old TWiki.cfg  and generating the new...

There wasn't a definition for "$dispScriptUrlPath" in the old configuration...
 ...using the default: '  $scriptUrlPath '
There wasn't a definition for "$dispViewPath" in the old configuration...
 ...using the default: '  "/view" '
There wasn't a definition for "$displayTimeValues" in the old configuration...
 ...using the default: '  "gmtime" '
There wasn't a definition for "$siteCharsetOverride" in the old configuration...
 ...using the default: '  "" '
There wasn't a definition for "$htpasswdFormatFamily" in the old configuration...
 ...using the default: '  "htpasswd"  '
There wasn't a definition for "$authRealm" in the old configuration...
 ...using the default: '  "Enter your WikiName. (First name and last name, no space, no dots, capitalized, e.g. JohnSmith). Cancel to register if you do not have one." '
There wasn't a definition for "$doMapUserToWikiName" in the old configuration...
 ...using the default: '  "0" '
(You may want to check that the defaults used above work for you, edit if not!)
/usr/local/www/twiki/lib/TWiki.cfg created...


Merging your existing twiki data (/usr/local/www/twiki/data) with new release twiki data...

Usage: UpdateTopics <CurrentDataDir> <NewReleaseDataDir> [<DestinationDataDir]>
oates#
pub
pub-htaccess.txt
readme.txt
robots.txt
root-htaccess.txt
subdir-htaccess.txt
templates
TWikiDocumentation.html
TWikiHistory.html
UpgradeTwiki
Preparing to write a new format configuration file for you...


Great - found it OK, and it tells me that the rest of the config is in ../lib,
so that's where I'll be looking!

First, making a new copy of setlib.cfg in your new installation...
.../usr/local/www/twiki-old/bin/setlib.cfg has been copied into /usr/local/www/twiki/bin
Now reading the old TWiki.cfg  and generating the new...

There wasn't a definition for "$dispScriptUrlPath" in the old configuration...
 ...using the default: '  $scriptUrlPath '
There wasn't a definition for "$dispViewPath" in the old configuration...
 ...using the default: '  "/view" '
There wasn't a definition for "$displayTimeValues" in the old configuration...
 ...using the default: '  "gmtime" '
There wasn't a definition for "$siteCharsetOverride" in the old configuration...
 ...using the default: '  "" '
There wasn't a definition for "$htpasswdFormatFamily" in the old configuration...
 ...using the default: '  "htpasswd"  '
There wasn't a definition for "$authRealm" in the old configuration...
 ...using the default: '  "Enter your WikiName. (First name and last name, no space, no dots, capitalized, e.g. JohnSmith). Cancel to register if you do not have one." '
There wasn't a definition for "$doMapUserToWikiName" in the old configuration...
 ...using the default: '  "0" '
(You may want to check that the defaults used above work for you, edit if not!)
/usr/local/www/twiki/lib/TWiki.cfg created...


Merging your existing twiki data (/usr/local/www/twiki/data) with new release twiki data...

Usage: UpdateTopics <CurrentDataDir> <NewReleaseDataDir> [<DestinationDataDir]>
oates#

I... guess that means it worked, at least mostly. It didn't move the existing webs over though. Let's see if it even works, first. Nope, Main web doesn't exist. doh.

oates# pwd
/usr/local/www/twiki/bin
oates# cp /usr/local/www/twiki-old/bin/.htaccess .
oates#

Still barfed. Perhaps it was trying to indicate to me that I ought to run UpdateTopics. Except that script or file exists nowhere. Ah, it's a .pm included by UpgradeTwiki. So I think something barfed.

rm -r /usr/local/www/twiki and start again.

Follow the suggestion about changing calls to mkdir in UpdateTopics to mkdir (whatever,0775) - nope, got no farther.

Looks like maybe it's a perl issue - perl 5.6 vs 5.8. So make a list of all the installed perl packages, then pkg_delete -f them and perl itself. Just after I did that it occurred to me that it may have been easier to just upgrade twiki on another system with perl 5.6, then copy everything back. sigh.

That didn't work either. Put perl 5.8.5 and all the p5 stuff back. Now that I re-re-read the twiki.org discussion, I see he was dealing with a very old, not a fairly new, version of perl. But it appears that isn't the issue anyway.

Ah. I didn't want to move the old one out of the way.

Patch rejected: ./TWiki/TWikiInstallationGuide.txt.rej
Patch rejected: ./TWiki/GoodStyle.txt.rej
Patch rejected: ./TWiki/TWikiPreferences.txt.rej
Patch rejected: ./Main/TWikiGroups.txt.rej
Patch rejected: ./Main/TWikiAdminGroup.txt.rej
Patch rejected: ./Main/WebPreferences.txt.rej
Patch rejected: ./Main/WebNotify.txt.rej
Patch rejected: ./Main/TWikiUsers.txt.rej

OK - the merge process completed successfully...
Now I'm giving write access to pub & data in the newly set up TWiki, so your web server can access them...

I copied in your existing .htaccess into /usr/local/www/twiki-new/bin.

        The significant differences between the new template for .htacess and your previous one are:

--- /usr/local/www/twiki-new/bin/.htaccess      Sat Jan 22 15:15:11 2005
+++ ./bin/.htaccess.txt Sun Jul 25 03:31:02 2004
+AuthUserFile !FILE_path_to_TWiki!/data/.htpasswd
+AuthName 'Enter your WikiName: (First name and last name, no space, no dots, capitalized, e.g. JohnSmith). Cancel to register if you do not have one.'
-SSLRequireSSL
-AuthName "UWdir Authentication"
-PerlAuthenHandler Apache::AuthenCache Apache::AuthenURL Apache::AuthenCache::manage_cache
-PerlSetVar AuthenCache_CacheTime 43200
-PerlSetVar AuthenURL_method HEAD
-PerlSetVar AuthenURL_url http://ego.uwaterloo.ca/Authen
-ErrorDocument 401 /twiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
+ErrorDocument 401 !URL_path_to_TWiki!/bin/oops/TWiki/TWikiRegistration?template=oopsauth
-<Files "manage">
+<Files "rdiffauth">
-<Files "installpasswd">
+<Files "manage">
-<Files "register">
-       require valid-user
+<Files "installpasswd">
+       require valid-user
You may need to apply some of these differences to the new .htaccess that I created... that's up to you.
(I'm not gonna mess with security settings at all!)

Putting in default WebLeftBar and WebAdvancedSearch...
Adaptivedb
Hardware
Printing
Irix
Email
Mac
CSCF
Faculty
Macs
Freebsd
Researchgroups
Linux
Windows
Sandbox
(already has one)
_default
(already has one)
Trash
(already has one)
TWiki
(already has one)
Main
(already has one)
Know

Congratulations... you made it this far!



Now: you need to

 - Check the files listed above (if any) who's patches were rejected.

   For these files, you'll want to check the .rej file (in the same directory as the file)
   and see whether there are changes in there that you need to make manually.

 - Check the files list above that have 'no common versions' - in those cases, your
   new install will still work, but you need to be aware the topic file that is in
   place is your old one... no changes from the new release have been included.

 - Check if you modified your old version of setlib.cfg: if you did,
    then you need to do the same to the new one (which you will find in ./bin).

   (There are only two reasons I can think of why you might have done that:
     1) You wanted to workaround the Apache2 hang bug or
     2) You needed to point to a local perl library for some reason.  )

 - Setup authentication for the new TWiki

    If you are using htaccess, then check the diffs above make sense.
    If you are using some other method, you'll need to figure out what you need to do (sorry!)

 - Set the permissions appropriately for the new TWiki.

   I have given pub and data global read and write access, so your new TWiki
   will work, but you might want tighter controls.

 - If you are one of the few people who modified @storeSettings, then you need to
   look in TWiki.cfg and see if you need to make changes (I installed new the default ones)

   If you don't know what this means, it probably doesn't apply to you.

 - Re-install plugins you were using

 - Copy over custom templates you put in the original templates directory

 - anything else I haven't thought of

 - Archive your old installation

 - Move the newly created twiki directory (/usr/local/www/twiki-new) to the place where your previous version was.

 - Rearrange sub-directories the way you like them, if needed.
   (some sites have bin in a very different place to the rest, for example)

 - Use your browser to check the whole thing: visit the 'testenv' script, which I am guessing is at:

      http://oates.cs.uwaterloo.ca/twiki/bin/testenv

   make sure there are no unwarranted warnings, and press the 'relockrcs' button if advised to do so,

   and finally: visit TWikiPreferences, which I'm guessing is at:

      http://oates.cs.uwaterloo.ca/twiki/bin/view/TWiki/TWikiPreferences

   ... it should be working, and you can edit the new WIKIWEBMASTER setting!

Once all that was done, I merged a few of those rejected patches and forgot about others. I went and edited the wiki web master, and also, one important thing: the TWiki.cfg file required editing so it would turn UWdir userids back into wikinames. The variable to be concerned with is userListFilename. I also had to re-add the .htaccess file settings.

-- MikePatterson - 13 Feb 2005

Postmortem: a portupgrade -a -PP -r almost killed the twiki. I did a mv /var/db/pkg/twiki20030201 ~ and then pkgdb -F and now it thinks that twiki isn't installed from ports, so it shouldn't ever touch it again.