Extension:Simple Farm

Simple Farm is a simple MediaWiki farm extension allowing users to run several wikis with just one physical MediaWiki directory. The extension loads a certain wiki by either a virtual script path (using a tiny bit of mod-rewrite) or by using sub-domains (requiring some more mod-rewrite). It is also possible to mix these methods for the same farm, not all members have to use the same method. Furthermore, 'Simple Farm' comes with a maintenance script which allows users to maintain several farm members at the same time, e.g. doing database updates for all or certain farm members by executing just one command. A certain farm can also be chosen via command-line access, using an environment variable.

How it Works
Simple Farm kicks in before MediaWiki has initialized all of its components. At this stage the wiki has not even made a connection to its database, global variables and functions are not all initialized, though most Extensions might already be registered. At this stage, Simple Farm takes over initialization to load a wiki from a certain database and set required global configuration variables accordingly. After that job is done, it is even possible to load further global settings according to one farm member's specific needs.

Basically the same happens in maintenance mode via the command-line. There is one script which will take commands which should be executed for one or more specific farm members. Then the script will connect to one wiki to have MediaWiki's maintenance functionality available, and from there it will handle the commands for each farm member's wiki independently.

Setup and Installation
First of all, you have to download the code and place the SimpleFarm directory within your MediaWiki extensions directory. Then add the following code near the bottom of your LocalSettings.php file:

FarmMembers.php would be a new php file with the necessary farm setup you had to create within your MediaWiki installation directory. The content of that file will be explained next. The comment at the bottom is just a placeholder for additional per farm member configuration. Finally, you won't get around applying some rewrite rules to your wikis environment.

Setting-up Farm Members
This section will introduce available settings to control the farms behavior and to register members. This configuration might be in a separate php file so you won't have it all over your LocalSettings.php.

is the config variable to define all the members of the wiki farm. It is an array containing a sub-array per farm member. The following associative Array keys are obligatory: Furthermore, one of the following methods has to be chosen: and/or:
 * db : The farms database name
 * name : The name of the farm member wiki. This value will end up in $wgSitename.
 * addresses: one or more (as array of strings) server names associated with the wiki. Can be used for sub-domain based farm members like farm1.mw.org, farm2.mw.org..., farmX.mw.org If this method is chosen, $wgScriptPath must be set in LocalSettings.php. Even if this method is not chosen, the addresses key should contain one address anyway.
 * scriptpath : Virtual script path to the particular wiki directory. Can be used for a rewrite rules based wiki farm setup. This will set the $wgScriptPath variable automatically. There should be a .htaccess file in the parent directory of the farm to redirect all paths to the farms MediaWiki directory. Example: mw.org/farm1, mw.org/farm2..., mw.org/farmX where for the first member the value had to be , for the second   and so on.

The following key is optional:
 * maintain : Flag whether or not the wiki is in maintaining mode right now. The following flags are allowed:
 * /  : Normal mode, no maintenance is going on right now.
 * : Blocks simple browser access to the wiki but accessing the wiki with maintain url parameter still is possible.
 * : Blocks all attempts to access the wiki except for command-line based maintenance.
 * : Block all attempts to access the wiki, even command-line maintenance.

Example for address-based setup
A valid address-based setup in a FarmMembers.php could look like this:

Example for scriptpath-based setup
A valid scriptpath-based setup in a FarmMembers.php could look like this:

Settings per Member
Simple Farm will just set the most important configuration variables, you might want to set certain configuration variables according to the chosen farm member. There are several ways of doing that, the two most convenient are presented here.

Using a Configuration File per Member
You can simply add the following lines to your LocalSettings.php after the  line. Now you can create a new directory wikiconfigs within your MediaWiki installation directory which can contain several files named after each wikis database name +. In these files you can apply settings just like in Localsettings.php with the exception that they will only apply for a particular farm member.

Using $egSimpleFarmMembers
It is possible to add further, custom keys to each farm member array within. Within LocalSettings.php they can then be accessed via. It is recommended to put a prefix in front of these additional keys (e.g. ) or to simply use the name of the global configuration variable they will end up in. This will prevent complications with future option keys added by Simple Farm extension.

Wherever  is defined:

In LocalSettings.php (after the  line.) these additional keys can be accessed:

In case one of the accessed keys is not defined for one farm, false will be returned! Instead of using  a prettier   could be used if PHP 5.3 is running on the server.

Setting-up Rewrite Rules
The webservers rewrite rules have to direct any web request to a particular wiki farm member to the physical directory of the Simple Farm wiki installation. Rewrite rules and sytanx depends on the webservers software. The following examples are for the widely spread Apache HTTP Server. The .htaccess file for these code examples has to be in the same directory the wiki directory is stored in, not within the wiki directory.

For addresses based farm members
Note: For a domain/page_name setup, you can use this method

This rewrite example works if you use the addresses based  configuration. So this would be the way to direct urls like:,  ... ,   to the MediaWiki directory.

Important: This assumes that $wgScriptPath is set to  and $wgArticlePath is set to

Many thanks to Stephan Jauernick for this set of rules.

For scriptpath based farm members
The following rewrite example works if your farm member setup in  uses the scriptpath key to define where the wiki lays virtually. So this can be used to direct urls like:,  ... ,   to one directory.

Important: The name of the physical wiki directory can't be used as a farm members virtual path name. If you want a path name wiki for one of the farm members, you have to rename the physical MediaWiki drectory into something else, e.g. mw and adjust the path within the rewrite rules as well.

Configuration Variables
Besides the required setup, there are some optional configuration variables controlling some of Subpage Funs behavior:


 * $egSimpleFarmMembers : Please see the section for detail information.


 * $egSimpleFarmMainMemberDB : Database name of one of the  wikis. If null (default), it will be set when   was called. The default value is the first key of   then. This main member is important for maintenance since the generic maintenance script will connect to the main member first to have full basic MediaWiki maintenance support.


 * $egSimpleFarmIgnoredDomainPrefixes : In case some farm members work sub-domain wise, this array can contain sub-domain prefixes which will be ignored when choosing to which farm member the given sub-domain name belongs to. By default, this is set to, which means in something like  http://www.member1.myfarm.com  the www.member1 part would be considered the string to choose the farm member from but since www is set to be ignored, only member1 will be left. Of course, the same can be achieved by using rewrite rules.


 * $egSimpleFarmWikiSelectEnvVarName : Name of the environment variable used to select a wiki via command-line access if only one wiki should be selected directly instead of using the provided maintenace script. By default the name of this environment variable is.


 * $egSimpleFarmErrorNoMemberFoundCallback : Allows to define a PHP callback function which should be called in case no wiki has been found. This can happen in case somebody is using an url which would require a non-existing farm member. Note: It would be nice if we could use the hook system of MediaWiki instead, but at this stage, the hook system has not even initialized. There might be a more complex system for this in the future.

Affected Configuration Variables
There are several global configuration variables which will be affected by Simple Farm. Some might just be conditionally be affected, others in any case. Be aware, that setting any of these variables before  might overwrite their value!

The following variables are affected:

Mass Maintenance
To make maintenance tasks like updating all database tables easy throughout the farm, Simple Farm introduces a new maintenance script to select all or certain farm members and run another (MW core) maintenance script on all of these farm members.

By default the location of that Script within the MediaWiki installation is

Besides MW default maintenance script parameters (such as ), the script allows the following parameters: It requires one argument, if not in preview mode, argument 1 which should be set to the shell command that should run on all selected farm members.
 * --farmexclude : Comma-separated list of farm members (by database names) to deselect for farming.
 * --farmonly : Comma-separated list of farm members (by database names) for doing some farming on.
 * --farmpreview : A preview mode. If set, this will output all selected wikis for farming without running any actual farming script on them.

Examples:

Single Farm Maintenance
For command-line access accessing just one single farm, it is easiest to use the command-line while setting the environment variable for selecting a farm member. For example: If the environment variable is not set, the main farm member (set in ) will be chosen for the maintenance action.