Separate Site-Specific Settings.

Problem

When updating a twiki installation with the latest distro, a special care must be taken not to overwrite the Twiki.cfg file and lose the local configuration.

Proposal

Have Twiki to look for another file LocalSite.cfg that has the site-specific settings. This file should have the same format as TWiki.cfg (i.e: you can use do "LocalSite.cfg" to load it). If this file is loaded after TWiki.cfg then the site-specific settings will override those of the distro.

Implementation

Hopefully this is a one-line change on the BEGIN block in TWiki.pm:

BEGIN {
    do "TWiki.cfg";
    do "LocalSite.cfg";

    # Do a dynamic 'use locale' for this module
    if( $useLocale ) {
        require locale;
   import locale ();
    }
}

I'll ImplementIdeaBeforeTheCompetition sometime this week.

As usual, any feedback is welcome.

-- RafaelAlvarez - 02 Nov 2004

This implementation is flawed, as there are values in TWiki.cfg that may need the overriden values. CrawfordCurrie solution is to move do "LocalSite.cfg" to TWiki.cfg (see attached patch).

But by doing this another problem surfaced: Which is the right point to put the override? All the settings that are more likely to change are mixed with those that aren't likely to change, so perhaps a reordering of the settings in TWiki.cfg in in order.

-- RafaelAlvarez - 03 Nov 2004

Documentation

(to be inserted in the TWikiInstallationGuide on Step 2: Edit the Configuration Files.)

• You have two options to configure twiki:
  1. Use the file twiki/lib/LocalSite.cfg (Recommended)
     • This options allows for easier upgrades, as the local configuration won't be overwritten when installing the new release.
     • Create the file twiki/lib/LocalSite.cfg
     • Edit the file twiki/lib/TWiki.cfg. Copy those properties above the line do "LocalSite.cfg"; into twiki/lib/LocalSite.cfg, and change them to suit your installation.
  2. Edit the file twiki/lib/TWiki.cfg directly (Not Recommended)
     • This option is not recommended because it has the risk that the local configuration can be overwritten when installing a new release unless special care is taken.
• No matter the chosen option, you must take into account the following:
  • Set the file extension in the $scriptSuffix variable to cgi or pl if required.
  • RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
    • Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
      • Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
    • Set $storeTopicImpl = "RcsLite"; for the Perl based RCS

Comments

I have a preference for something that you will find when doing a search - could i put in a vote for localTWiki.cfg ?

also - you realise that you have just suggested / made a simple mutli-site TWiki config? The admin can put the entire TWikiRelease in one shared spot, and all a user has to do to run their own is to copy or softlink the bin dir to their own public_html area, and then edit a copy of setlib.cfg to point to their own localTWiki.cfg...

Bloody Brilliant I Say!

-- SvenDowideit - 02 Nov 2004

Yes. Brilliant! Go for it.

-- AntonAylward - 02 Nov 2004

ok. Here it goes: The patch agains today's MAIN branch. I guess that RafaelAlvarezWouldLikeToCheckIn.

-- RafaelAlvarez - 03 Nov 2004

Nice idea Rafael. Could you also provide the doc? (on this page)

-- PeterThoeny - 03 Nov 2004

Rafael, I checked this into DEVELOP and also added a mass of documentation to TWiki.cfg. You still need to provide the user documentation (installation guide) changes, as Peter requests. Peter, the changes in DEVELOP are labelled SeparateSiteSpecificTWikiConfiguration, as per the process in HowDoesTheDEVELOPBranchWork. You do not risk picking up any changes by merging TWiki.cfg alone. Of course there is no need to check in LocalSite.cfg, this will be created by sysadmins on a per-site basis if it is required.

-- CrawfordCurrie - 03 Nov 2004

I've set up TWiki many times on UNIX platforms but am just doing my first version on Windows at its a great hassle. Cygwin seesmt to install a lot of stuff I can't imagine using (gnome, xwin).

Barely working, Digest::SHA1 problems, yamma yamma. I make the mistake of applying the current beta.

ZAP! Now nothing works.

Please, _please, please make this part of the production baseline!

-- AntonAylward - 03 Nov 2004

CrawfordCurrie found an error in my implementation, and fixed it (thanks ). As he stated above, the fix is on the DEVELOP branch and it changes only TWiki.cfg. I made a new patch against trunk with the fix and the documentation provided by Crawford. Enjoy.

-- RafaelAlvarez - 03 Nov 2004

I have been using this to configure I18N on a local TWiki and found it didn't work because it was too early in TWiki.cfg. I have moved it to the end of the file (just before the '1;') and it works a lot better - was there some reason to have it earlier? I haven't committed this to SVN yet but it works fine for me.

-- RichardDonkin - 12 Dec 2004

The reason to have it earlier is that there are some properties that depends on $dataDir (the RCS ones, IIRC), so if the local configuration is overriden at the end those preferences will have the wrong value.

Perhaps what we really need is to "split" TWiki.cfg into various overridable parts, or find a new way to store the twiki configuration

-- RafaelAlvarez - 13 Dec 2004

Good point... Another way to do this would be for the distro to only include TWiki.cfg.default, and for this to be merged into the main TWiki.cfg by UpgradeTWiki. Since the latter works pretty well, I'm not sure we really need LocalSite.cfg - this is really an artefact of not having an installer. Since many installations will need the shebang lines to be edited (even on Linux, e.g. if the distro includes Perl 5.6 but you need Perl 5.8 for I18N), it seems we should just do an installer...

Or we could have a proper config directory for TWiki.cfg, just as Apache has conf - that way, it's a bit clearer what happens if you just unzip a new distro.

Yet another idea that I just tried - include LocalSite.cfg twice, once in original place (to override $dataDir etc) and once at end (to override everything else). Seems messy but it does work unless LocalSite.cfg is doing cumulative operations.

One thing not tried is to include LocalSite.cfg just once, where it is now perhaps, but make all the assignments in TWiki.cfg after this point use the $var || "foo"= format - if you've overridden the variable earlier, it will take precedence. In fact, this would let you include LocalSite.cfg right at the top of TWiki.cfg, though then it wouldn't be able to use $dataDir etc.

-- RichardDonkin - 13 Dec 2004

I'm thinking of adding Richard's suggestion for all variables - that what the include LocalSite.cfg can be at the top of the TWiki.cfg - If there are no objections taht is

tho i was thinking

$var = "blah" unless defined ($var);

-- SvenDowideit - 20 Dec 2004

This is good - so how about the other files - see SharingInstallFilesBetweenSites

SecureTWikiPreferences seems to indicate that %MAINWEB%.TWikiPreferences can override TWikiPreferences. This is a known security issue, but I would lay a bet that most admins don't create and lock down this topic.

http://wikiconsulting.com/view/PublicWikisOverview/FieldSelect?fieldname=Version

shows that many sites still run old versions.

-- MartinCleaver - 20 Dec 2004

Main twiki prefs is a security concern when left empty or uncreated, but it is also a major feature when used right. It's basically the same as 'do LocalSite.cfg' in TWiki.cfg.

-- MattWilkie - 21 Dec 2004

I agree that it is a great feature, yet for some reason it has become "undocumented" *users told to use the one in the TWiki web) when we ought be encouraging its further use.

http://wikiconsulting.com/view/PublicWikisOverview/FieldSelect?fieldname=Exposed%20MAINWEB.TWikiPreferences&sortcol=2&table=1&up=1#sorted_table

shows that it is seldom used, presenting many hijacking opportunities in instances where this topic is non-existant. ALLOWWEBRENAME has to be restricted to TWikiAdminGroup; Cairo does this by default.

-- MartinCleaver - 21 Dec 2004

this feature was more than cooked into the core, with further enhancements courtesy of CrawfordCurrie.

-- RafaelAlvarez - 08 Aug 2008

this feature was more than cooked into the core, with further enhancements courtesy of CrawfordCurrie. I'm changing the state of the topic,

-- RafaelAlvarez - 08 Aug 2008