Foswiki Upgrade Guide
This guide covers upgrading from a previous version of Foswiki or TWiki (such as Cairo or TWiki4.0) to Foswiki 1.0
Overview
Foswiki is in reality the TWiki project continued under a new name.
The brand name change has had a large impact on many things that also impact an upgrader. They are however mostly visible "under the hood" and a
TWikiCompatibilityPlugin
is provided that makes Foswiki compatible with most Plugins made for TWiki.
Foswiki is 100% compatible with all content of existing TWikis which is the most important factor when you upgrade.
Upgrading from TWiki to Foswiki
If you upgrade from TWiki to Foswiki, you are strongly adviced to read the
Foswiki:System.ReleaseNotes01x00 (also available in HTML version in the root of your installation) where all the changes from TWiki 4.2.3 to Foswiki 1.0.0 are listed.
Upgrade Requirements
- Please review the Foswiki:System.AdminSkillsAssumptions before you upgrade Foswiki
- To upgrade from an old TWiki Release to the latest Foswiki Production Release, follow the instructions below
- Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write. Make sure you take a backup!
- Not all Plugins from TWiki are compatible with Foswiki. But most publicly available Foswiki:Extensions have been republished in a version converted to the Foswiki namespace.
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 or Foswiki release.
The main steps are:
- Install the new Foswiki version, configure it, and get it to work similar to the old version
- Install additional extensions (Plugins). Make sure to use the latest Foswiki versions
- Copy all the non-default webs from the old installation to the new
- Copy the users from old installation to the new incl all their topics from Main
- Apply tailorings to your Skin (logos, menu bars etc)
- Apply preferences from old installation
Installation
- Follow the installation instructions in INSTALL.html which you find in the root of the new installation. Install the new release in a new directory. Do not install on top of the old release.
- Use the
configure
script to configure Foswiki.
- If you are upgrading from a TWiki 4.x.x release, you can not carry over the configure settings from the old release. If you upgrade from an older Foswiki release you can reuse your configure settings.
- You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.
- You can also choose to start with a fresh configuration and walk through all the settings using your old LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg. When upgrading from TWiki to Foswiki you always have to start with a fresh configuration.
- If at any time during the installation you want to start over from fresh all you need to do is delete the
lib/LocalSite.cfg
file and re-run configure.
- Additional resources
- Make sure you have a working basic Foswiki before you continue
Install Extensions
- Note that not all extensions that worked in Cairo had been updated to work with Foswiki. We are continuously releasing Foswiki versions of the plugins on Foswiki:Extensions. When we release a Foswiki version we test them to make sure Foswiki plugins as a minimum runs on Foswiki. Installing TWiki Extensions such as Plugins requires that the perl name space is changed from TWiki to Foswiki. A
TWikiCompatibilityPlugin
is provided which makes most unmodified TWiki Plugins work on Foswiki. If a plugin exists in the Foswiki:Extensions repository it is highly recommended to install it from there so get an extension which has been converted to the Foswiki namespace.
- The
configure
script which you ran during installation supports installation of additional plugins.
- Manual installation is possible. Follow the instruction on the Plugin page at foswiki.org.
- Check the plugin topics from your old TWiki/Foswiki installation. There may be plugin settings that you want to transfer to the new Foswiki installation.
Hint: For an easier upgrade later on, set the plugin preferences settings in the Main.SitePreferences
topic, not in the plugin topic. To identify the plugin, prefix the name of the setting with the capitalized name of the plugin. For example, to change the DEFAULT_TYPE
setting of the CommentPlugin
, create a COMMENTPLUGIN_DEFAULT_TYPE
setting in Main.SitePreferences.
- Typical plugin settings you may have altered.
-
CommentPlugin
- Set DEFAULT_TYPE
-
EditTablePlugin
- Set CHANGEROWS, Set QUIETSAVE, and Set EDITBUTTON
-
InterwikiPlugin
- Set RULESTOPIC
-
InterWikis
- If you added your own rules you should save this topic and not overwrite it.
-
SlideShowPlugin
- Make sure you did not change the embedded 'Default Slide Template' If you did you should save it. It is a bad idea to do. It is better to define your own slide show templates as separate topics that do not get overwritten when you upgrade.
-
SmiliesPlugin
- Did you add your own smileys? No real changes were made to the smilies topic October 2005 so you can just leave this topic as it is.
-
TablePlugin
- Set TABLEATTRIBUTES
- Remember that a plugin must be activated in
configure
.
- To avoid having to re-apply plugin settings each time you upgrade a plugin or Foswiki itself, define the altered plugin settings in
Main.SitePreferences
instead
Copy your old webs to new Foswiki
- When upgrading from TWiki Cairo or earlier it may be necessary to unlock the rcs files in data and pub directories from the old installation using the following shell commands:
-
find data -name '*,v' -exec rcs -u -M '{}' \;
-
find pub -name '*,v' -exec rcs -u -M '{}' \;
- Copy your local webs over to the data and pub directories of the new install. Do not copy the default webs: System (or TWiki), Main, Trash, Sandbox, _default, and _empty.
- Make sure all data and pub files and directories are owned by the webserver user.
- Note: Foswiki's
WebChanges
topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or to change them in the sequence of old file timestamps.
Copy Users And Their Topics From Main Web
- Copy all the topics from the Main web and corresponding pub/Main directories from the old TWiki/Foswiki to the new Foswiki but do not overwrite any of the new topics already inside the new Main directory!
- Manually merge all the users from the old
Main.WikiUsers
topic to the new Foswiki. Foswiki does not ship with a Main.WikiUsers
topic. When you register the first user Foswiki now checks for an existing Main.WikiUsers
and if it does not exist it gets created.
- For upgrades from TWiki to Foswiki the
TWikiUsers
topic must additionally be renamed to WikiUsers
. If you upgrade from Cairo you can simply use the old file renamed to WikiUsers
and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.X simply use the old topic renamed to WikiUsers
.
- For upgrades from TWiki to Foswiki also copy the
Main.TWikiAdminGroup
topic so that topics you have protected with ALLOWTOPICCHANGE or ALLOWWEBCHANGE set to TWikiAdminGroup are still protected. Otherwise people can create the TWikiAdminGroup
and put themselves in it.
- If you use
data/.htpasswd
for authentication copy this file from the old TWiki/Foswiki to the new Foswiki.
- If you upgrade from Cairo and you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password file. There is a script that performs this extra upgrade step for you - see
tools/upgrade_emails.pl
.
- The old sandbox web may have a lot of useful topic and users may use it actively for drafts. Manually select the topics (remember the corresponding pub directories) from the old Sandbox web and copy them to the new Foswiki. Decide if you want to overwrite the sandbox homepage and left menu bar or keep the new.
- If you added or removed fields from the user topic form you may also have tailored
System.UserRegistration
. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new System.UserRegistration
topic.
- Upgraders from TWiki must note that
TWikiRegistration
was renamed to UserRegistration
in Foswiki.
- Foswiki ships with
NewUserTemplate
and UserForm
in the System web. If you choose to tailor anything you are strongly adviced to copy NewUserTemplate
and UserForm
to the Main web and tailor the Main web copies. Foswiki will look for the NewUserTemplate
in the Main web first and if it does not exist it uses the default from the System web. By creating a Main.NewUserTemplate
and its Main.UserForm
you will not loose your tailorings next time you upgrade Foswiki.
- Make sure all data and pub files and directories are owned by the webserver user.
Apply Customizations To The Skin
- Not many of the old TWiki Cairo skins work well with Foswiki
- Add Logos, update top bar and left bar as required.
- Apply any desired changes to style sheets and templates. The default PatternSkin has been totally rewritten since Cairo and once more in 4.0.2. Since then changes to PatternSkin have been minor and you may be able to carry over most simpler tailorings directly from 4.0.2-4.0.5.
- Additional resources:
-
System.PatternSkinCustomization
-
System.PatternSkinCssCookbook
- From Foswiki 1.0.0 the
WebLeftBar
topic is no longer shipped with the distribution. Foswiki 1.0.0 PatternSkin will use the topic WebLeftBarExample
if there is no WebLeftBar
topic in the current web. To make your own WebLeftBar
simply make it a copy of WebLeftBarExample
and change it as you desire. Next time you upgrade you can be safe that your WebLeftBar
topic is not being overwritten by the upgrade.
Apply Preferences From Old Installation
- Transfer any customized and local settings from
System.DefaultPreferences
to the topic pointed at by {LocalSitePreferences}. Per default this is Main.SitePreferences
. This avoids having to write over files in the distribution on a later upgrade.
- Upgraders from TWiki should note that the
Main.TWikiPreferences
is renamed to SitePreferences
, and TWiki.TWikiPreferences
is renamed to System.DefaultPreferences
in Foswiki.
- If you changed any of the topics in the original TWiki/Foswiki distribution, you will have to transfer your changes to the new install manually.
- Compare the
WebPreferences
topics in the old TWiki/Foswiki Installation with the default from the new Foswiki installation and add any new Preferences that may be relevant.
Customization of Special Pages
Some pages in the Foswiki web are meant to be customized after choice of authentication. If you do not use the internal Foswiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. If you have made such customizations remember to replace these topics in the System web with the tailored versions from your old installation. If you upgrade from TWiki remember that the old TWiki web is called System web in Foswiki. The topics are:
-
System.ChangePassword
-
System.ResetPassword
-
System.ChangeEmailAddress
Upgrading from TWiki Cairo to Foswiki (additional advice)
Favicon
Foswiki's PatternSkin use the favicon feature which most browsers use to show a small icon in front of the URL and for bookmarks.
By default the same favicon is used in all webs and stored in %PUBURLPATH%/%SYSTEMWEB%/ProjectLogos/favicon.ico
You can replace this globally by attaching a favicon to any topic and point to it with a setting in %USERSWEB%.SitePreferences
You can also have a unique favicon for each web by applying similar setting in WebPreferences in each web.
The setting you need must look similar to this
* Set FAVICON = %PUBURLPATH%/webname/topicname/favicon.ico
WikiUsers topic in Main web
As part of the rebranding from TWiki to Foswiki, the TWikiUsers topic was renamed to WikiUsers but the format is the exact same.
Your Cairo TWikiUsers topic will work in Foswiki but you will need to ensure that these 4 users from the default Foswiki version of WikiUsers are copied to the existing WikiUsers topic. WikiGuest is probably already there but the others are new
- ProjectContributor - placeholder for a Foswiki developer, and is used in Foswiki documentation
- WikiGuest - guest user, used as a fallback if the user can't be identified
- RegistrationAgent - special user used during the new user registration process
- UnknownUser - used where the author of a previously stored piece of data can't be determined
Important Changes since TWiki 4.0.5
Supported Perl version
TWiki 4.0.5 worked on Perl version 5.6.X. Reports from users has shown that unfortunately Foswiki does not support Perl versions older then 5.8.0. It is especially the Wysiwyg editor and support for international character sets that requires new features in Perl 5.8.X.
Template spec changed
Until TWiki 4.0.5 SkinTemplates (formerly TWikiTemplates) the text inside template definition blocks (anything between %TMPL:DEF{"block"}% and %TMPL:END% was stripped of leading and trailing white space incl new lines.
This caused a lot of problems for skin developers when you wanted a newline before or after the block text.
From TWiki 4.1.0 and continuing in Foswiki this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. But if you use an older skin or have written your own you will most likely need to make some adjustments.
It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF{"block"}% needs to be removed. Ie. the content of the block must follow on the same line as the TMPL:DEF.
The spec change have the same impact on CommentPlugin templates where you may have to remove the first line break after the TMPL:DEF. See the
System.CommentPluginTemplate
for examples of how comment template definitions should look like in TWiki-4.1.X
An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.
<verbatim>
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%
|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%
</verbatim>
From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.
<verbatim>
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%
</verbatim>
The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.
Important Changes since TWiki 4.1.0
New location for session and other temporary files
The directory for passthrough files and session files have been replaced by a common directory for temporary files used by Foswiki. Previously the two configure settings
{PassthroughDir}
and
{Sessions}{Dir}
were by default set to
/tmp
. These config settings have been eliminated. Foswiki creates the tmp directory and other temporary directors under the directory defined by the configure setting
{WorkingDir}
Important Changes since TWiki 4.1.2
New WYSIWYG Editor
Foswiki now ships with a new WYSIWYG editor based on TinyMCE replaces the Kupu based editor.
TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the Kupu editor
The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that less Foswiki Applications are negatively affected by editing WYSIWYG
When TinyMCEPlugin is enabled the Edit button per default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way
The WYSIWYG button has been removed.
NEWTOPICLINKSYMBOL removed
The NEWTOPICLINKSYMBOL preference which was deprecated in TWiki 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use NEWLINKFORMAT.
UserForm and NewUserTemplate Customization
When a new user registers on Foswiki his user topic is created based on the
NewUserTemplate
and
UserForm
.
The
NewUserTemplate
was located in the TWiki web and the
UserForm
in the Main web. When you earlier upgraded TWiki these were some of the topics you had to take care not to overwrite.
In Foswiki the
UserForm
and
NewUserTemplate
are distributed in the System web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade Foswiki your tailored template and form will not be overwritten.
WikiUsers no longer distributed
The
Main.WikiUsers
topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade Foswiki.
This file is not included in the Foswiki distribution. When you register the first time Foswiki creates the
Main.WikiUsers
topic in the Main web if it does not exist already. This means that you can now upgrade Foswiki without risk of overwriting the important
WikiUsers
topic.
- For new installers this makes no difference at all
- For upgraders this is one less problem to worry about as your important Main.WikiUsers topic now no longer gets overwritten when upgrading.
New working
directory
A new directory
working
which per default is located in the twiki root, has been introduced which contains:
- registration_approvals - with 4.2.0 it is moved to here from the data directory)
- tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.
- work_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.
Note: Remember to restrict access to this new directory when you upgrade.
The configuration setting
{WorkingDir}
defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is
working
under your installation root.
Take care for that change if you run your own routine to delete obsolete session files, which will now be found under
working/tmp/cgisess*
.
New Internal Admin Login
Foswiki has a new
Internal Admin Login feature which uses "admin" (configurable) as username and the password used for configure to become temporary administrator. When you do a new installation you need to use this feature as Main.AdminGroup is now access restricted by default to avoid security attacks during the hours an installation may take. From configure there is a link to the AdminGroup topic and on AdminGroup the step by step instructions are written in a yellow box. Our advice is not to remove this help text in case you need it later.
Related Topics: AdminDocumentationCategory,
Foswiki:Support.UpgradingFromOlderTWikiReleases,
Foswiki:Support.UpgradingFromTWiki4x2Releases,
Foswiki:Support.UpgradingPatchReleases,
Foswiki:Support.ApacheConfigGenerator,
Foswiki:Support.SettingFileAccessRightsLinuxUnix