Extension:MediaWikiFarm/Installation

This page explains how to install MediaWikiFarm, how to transition MediaWikiFarm from mono-version to multi-versions mode, and various compatibility details between MediaWiki and MediaWikiFarm. Only the system configuration is explained here, the day-to-day configuration of MediaWikiFarm and MediaWiki instances will be detailled in the next chapter.

The two modes (mono-version and multi-versions) are strictly exclusive; any mix could produce errors, and even data corruption could happen (e.g. if you run maintenance/update.php on a wrong MediaWiki version). However, a transition path between mono-version and multi-versions mode has been created and should be safe.

Original installations could be either in mono-version mode or multi-versions mode, there is no need to begin in mono-version mode.

There shouldn’t be any interruption of service if everything is followed carefully.

Preparation

It is out of scope to explain out to install and configure the full HTTP stack, neither how to make it compatible with a MediaWiki farm and evolve with the time. For a raw overview, you must configure in a multisite fashion: the DNS servers, the HTTP servers, and possibly the associated security versions DNSSEC and HTTPS, and possibly the domain names depending of your specific configuration. It is also out of scope the installation and configuration of other services and backends: database servers, memcached servers, other caching or performance services, MediaWiki external services as Parsoid, Mathoid, Citoid, etc. You should also be comfortable with command line on a *nix system.

It is assumed you have an existing MediaWiki (standalone) installation. A new installation is theoretically possible, but it has not been tested.

Before installing the files, you must prepare these informations:

• regular expression(s) for your farm(s) with named patterns;
• configuration directory where will be placed MediaWiki configurations, the default is /etc/mediawiki;
• cache directory, a directory where config files will be cached; the default is /tmp/mw-cache; it can speed up MediaWikiFarm from 9ms to 2ms (without OpCache).

For your initial configuration, you can choose the regular expression of your farm simply as the name of your existing wiki, e.g. "mywiki.example.org". If you do that, the suffix and wikiID can be fixed without variables, but you should quickly think how you want to organise your wikis and farms to change these to significant values before you have too much things in your config files.

Download the MediaWikiFarm extension. On the contrary of other MediaWiki extensions, there is (and there will be) only one Git branch for MediaWikiFarm (no REL1_XX branches), and all versions of MediaWikiFarm will be always compatible with all MediaWiki versions, except if in the future there are MediaWiki versions incompatible with other older MediaWiki versions. Future MediaWikiFarm versions will only add security and bug fixes, as well as features compatible with ideally all MediaWiki versions but at least all recent MediaWiki versions. MediaWikiFarm follows semantic versioning.

Config files can be read in YAML, JSON, or PHP syntax. The two later have native PHP functions, but the former need an external library. So if you want to use the YAML syntax, it is entirely possible but it creates a dependency (it is the only dependency).

Create the configuration directory and make it readable for PHP. Copy the farms.json, farms.php, or farms.yml(depending on your preference) from docs/config to this configuration directory. In the placeholder section, replace with your farm regex, and replace the suffix and wikiID keys with the variables coming from your regex. You will notice the only config file is LocalSettings.php, it will be your existing config file (see below).

Now jump to mono-version or multi-versions mode.

Mono-version mode

In this mode, MediaWikiFarm can be installed (almost) like any other MediaWiki extension, but the configuration is different.

1. Copy the extension MediaWikiFarm and install it in the subdirectory $IP /extensions/MediaWikiFarm;
2. If you downloaded it from Git and want the YAML syntax, go inside the directory and run composer install --no-dev (see Composer if needed);
3. Copy your existing $IP/LocalSettings.php file to the configuration directory;
4. Verify there is no relative path inside: __FILE__ and __DIR__ should probably be replaced by their original value to avoid any missing file require (it’s fine to use the MediaWiki installation variable $IP);
5. Copy the LocalSettings.php file from docs/config/ to the same directory as your existing $IP/LocalSettings.php, as $IP/LocalSettings.new.php;
6. Check and/or customise the directory paths within $IP/LocalSettings.new.php;
7. Make MediaWikiFarm live by overwriting your existing $IP/LocalSettings.php with the contents of $IP/LocalSettings.new.php.
8. $IP/LocalSettings.new.php can now be deleted.

Multi-versions mode

Decide on the path where will be MediaWiki versions, this will be called the code directory. It is recalled each MediaWiki version (version + flavour more exactly) will be in a subdirectory of this code directory, and the names of these subdirectories will be the names of the versions. This code directory is independent from the configuration directory.

It is assumed here all the directories are not used on the live website; if it is not the case, you must be more careful.

1. Create this directory, copy your existing MediaWiki installation in a subdirectory, and rename this subdirectory to an understandable name, for instance the name of the MediaWiki version (e.g. "1.28.1").
2. Copy the extension MediaWikiFarm in a subdirectory of this code directory. You can name this subdirectory as you want.
3. Go inside this directory; if there is no Composer vendor directory and you want the YAML syntax, run composer install --no-dev (see Composer if needed);
4. Always in the MediaWikiFarm directory, copy inside the file docs/config/MediaWikiFarmDirectories.php in the directory config, and check or customise the directory paths inside.
5. Go inside your MediaWiki installation and copy your existing LocalSettings.php file in your configuration directory.
6. Verify there is no absolute path inside: __FILE__ and __DIR__ should probably be replaced by their corresponding value in the MediaWiki installation directory to avoid any missing file require (it’s fine to use the MediaWiki installation variable $IP).
7. Go inside your MediaWiki installation and replace the existing $IP/LocalSettings.php by the MediaWikiFarm file docs/config/LocalSettings.multiversion.php (and renaming it with the classical name $IP/LocalSettings.php).
8. /!Make MediaWikiFarm live by changing your Web server configuration to make entry points index.php and others point to the files www/index.php and others in the MediaWikiFarm directory.

Transition from mono-version to multi-versions mode

1. Be sure you have the last version of the extension MediaWikiFarm; if not, update.
2. Follow the instructions to create a multi-versions installation, just don’t do the last step.
3. Convert all your files containing the lists of existing wikis from lists to dictionaries, the key being the wikiID and the value the version (name of the subdirectory). In YAML syntax, each line was (e.g.) - wikiname and becomes wikiname: 1.25.5.
4. /!\ Make multi-versions MediaWikiFarm live by changing your Web server configuration to make entry points index.php and others point to the files www/index.php and others in the MediaWikiFarm directory.
5. In the MediaWiki installation, replace the mono-version MediaWikiFarm LocalSettings.php files to multi-versions MediaWikiFarm LocalSettings.php: these files can be found in the MediaWikiFarm directory docs/config/LocalSettings.multiversion.php (and rename it with the classical name $IP/LocalSettings.php).
6. Remove the MediaWikiFarm extension from the classical directory $IP/extensions/MediaWikiFarm.

For information, transition from multi-versions to mono-version mode is simply the contrary of the steps 6, 5, 4, 3, but care must be done because MediaWiki could not like change from one version to another without a clean transition path.

Compatibility between MediaWikiFarm and MediaWiki

TO BE IMPROVED

• Ghost LocalSettings (no need to put a LS.php in MediaWiki directory): only for MediaWiki >= 1.17
• PHP 5.2 for MediaWiki < 1.13 (to be checked): no YAML for MediaWikiFarm there since YAML library is PHP 5.3+
• Extension loading mechanisms (Composer, require_once, wfLoad) issues: loading order, inter-extensions mechanisms (e.g. ULS must be require_once before Translate require_once, even if ULS is wfLoad-compatible)
• Warning about order between require_once and configuration parameters: some require_once extensions could expect some variables are already set (wgServer etc)