WikiFarm

Aus Free Software
Zur Navigation springen Zur Suche springen

This page describes how to set up a WikiFarm, a setup that allows you to have several wikis sharing a common code-base, settings, extensions, etc.

The problem

We host a great number of MediaWikis including, but not limited to,

Maintaining so many Wikis "the normal way" is of course non-trivial. Every MediaWiki has to be updated separately, updates to rarely used Wikis are easily forgotten, extensions have to be updated equally as often... you get the picture.


The solution: A WikiFarm

A WikiFarm solves all these problems (and then some):

  • The entire code-base is shared by all Wikis in the farm. That means that if you patch the source-code (i.e. with one of these patches), the patch is automatically used by all Wikis.
  • You can also define common settings that are used by all Wikis (but can still be overridden locally). Which settings are shared and which are not, is up to you.
  • The extensions- & skins-directory can also be shared. So if you install a new extension/skin, it can be used by all Wikis and you have to update extensions/skins only once for all Wikis. If you use common settings, you can also configure (some) extensions globally.
  • It becomes easy to upgrade all Wikis at once, using one trivial shell-script.


There are of course some problems:

  • Creating a new Wiki that is integrated into the farm right away not as trivial as it should be, see #Installing a new Wiki.


How it works

A WikiFarm is actually something rather trivial:

  • One directory containing the source-code of MediaWiki must exist somewhere. This directory contains almost everything a normal MediaWiki installation does - except at least LocalSettings.php.
  • The actual MediaWiki-installations (the directory that is served by the webserver) no longer contain any source-code, but only symlinks to the central directory and any files that are "local" to the Wiki, like LocalSettings.php or the upload-directory.

You can fine-tune the degree every installation is integrated into the farm. For example, a Wiki could choose not to use the shared skins-directory if the Wiki has a custom skin that shouldn't be used elsewhere and the standard-skins could still be the shared skins. The following chapters describe a maximum of integration, but almost every single step can be omitted for any number of Wikis in the farm.


Creating a WikiFarm

The central directory is, at first, simply the contents of the mediawiki tarball. We don't use the directory itself but a symlink to the source-code of the currently used version. A simple output of ls -l should make matters clear (output is abbreviated for clarity):

user@host:/var/www# ls -l
lrwxrwxrwx  1 root root        17 2007-09-15 00:38 mediawiki -> mediawiki-1.12.0/
drwxr-xr-x 17 root root  4096 2007-12-02 11:56 mediawiki-1.12.0
drwxr-xr-x 17 root root  4096 2007-12-02 11:56 mediawiki-1.11.0
drwxr-xr-x 16 root root  4096 2007-09-14 23:20 mediawiki-1.9.3

That way you can easily switch the code-base of all Wikis to another version. Note that a Wiki probably won't work after a simple code-switch since the database-layout changes between different versions, so you have to update the databases as well.

The next step is to install all extensions, skins & patches that should be available in all Wikis into the mediawiki-directory. Note that it is a very rare corner-case where you don't want an extension in the shared extensions-directory, since you can still simply not enable it in LocalSettings.php.

The final step is to create a file that has shared settings used by all Wikis, called CommonSettings.php for the remainder of the article. This extension can set almost any setting you like, of course it doesn't make much sense for something like the name of a Wiki. This file will be included by LocalSettings.php, at any point you wish. That means that each Wiki can override settings done by CommonSettings.php simply by setting it after the inclusion of CommonSettings.php. Likewise, CommonSettings.php can depend on LocalSettings.php to set a variable before CommonSettings.php is included.


Integrating a Wiki into the Farm

The existing Wiki must be the same version as the farm. So if the wiki uses an older version of MediaWiki upgrade to the version used in the farm first. Integrating a wiki is however simple:

  • Include CommonSettings.php in LocalSettings.php
  • Delete lines from LocalSettings.php that are set in CommonSettings.php
  • Copy custom code (i.e. extensions, skins) into the farm
  • Delete all files in the wiki-installation except LocalSettings.php, the images-directory and any other files that should be strictly local (favicon...)
  • Create some symlinks. Not all directories/files need to be symlinked, see the below output of ls -l for a complete list

After integration, the directory where the now-integrated wiki is located, should look like this:

user@host:/var/www/integrated-wiki# ls -l
total 12
-rw-r--r--  1 root     www-data 1406 2007-05-07 17:14 favicon.ico
drwxrwx--- 20 www-data www-data 4096 2007-04-10 15:47 images
lrwxrwxrwx  1 root     root       28 2007-07-06 15:23 includes -> /var/www/mediawiki/includes/
lrwxrwxrwx  1 root     root       28 2007-07-06 15:23 index.php -> /var/www/mediawiki/index.php
lrwxrwxrwx  1 root     root       29 2007-07-06 15:23 languages -> /var/www/mediawiki/languages/
-rw-rw-rw-  1 root     www-data 2558 2007-10-08 01:15 LocalSettings.php
lrwxrwxrwx  1 root     root       24 2007-07-06 15:23 math -> /var/www/mediawiki/math/
lrwxrwxrwx  1 root     root       32 2007-12-14 13:36 opensearch_desc.php -> /var/www/mediawiki/opensearch_desc.php
lrwxrwxrwx  1 root     root       24 2007-07-06 15:23 skins -> /var/www/mediawiki/skins
lrwxrwxrwx  1 root     root       24 2007-07-06 15:23 extensions -> /var/www/mediawiki/extensions
lrwxrwxrwx  1 root     root       36 2007-07-06 15:23 StartProfiler.php -> /var/www/mediawiki/StartProfiler.php

The only directory the webserver really needs write-access to is the images-directory, everything else can be read-only to the webserver. If upload is disabled, you can skip this directory entirely.


Installing a new Wiki

Creating a new Wiki that integrates directly into the farm is not as trivial as it should be, but is still easy and is a matter of

  • Creating a few symlinks
  • Creating a LocalSettings.php
  • Creating and populating the database (<-- this is the hard part)


Updating the farm

This is extremely simple if you have a command-line version of php installed. Simply switch the farm to the new code-base (so mediawiki points to mediawiki-new instead of mediawiki-old) and call update.php like this for every Wiki:

root@pluto:~# php /var/www/mediawiki/maintenance/update.php --aconf=/var/www/mediawiki/AdminSettings.php --conf=/var/www/integrated-wiki/LocalSettings.php

A sample-script can be found in the resource-page of this page. After the update, it may be necessary to upgrade some extensions as well.

Differences to normal MediaWiki installation

All includes, require_once, etc. that include something from the shared MediaWiki installation should use $IP instead of an absolute Path. It is usually set in LocalSettings.php but it should be set in CommonSettings.php instead, simply use this code:

if( defined( 'MW_INSTALL_PATH' ) ) {
       $IP = MW_INSTALL_PATH;
} else {
       $IP = dirname( __FILE__ );
}

then change every require_once etc. from

require_once( "/var/www/mediawiki/extensions/foo.php" );

to

require_once( "$IP/extensions/foo.php" );

The fact that many require_once in the MediaWiki code don't do this is actually the reason most symlinks are needed.