Extension:MediaWikiFarm/Quick start

This page is a quick start guide to install and configure a farm of wikis using the Mediawiki extension MediaWikiFarm in multi-versions mode. The installation is made on Ubuntu 16.04, with Nginx and MySQL (other backends are supported but not covered here). The guide does not cover the installation and general configuration of these softwares, nor topics such as security. It is advised to read the Concepts page beforehand.

Overview

Farm

In multi-versions mode, covered by this guide, MediaWikiFarm allows you to manage farms of wikis with different versions of Mediawiki. At the end of this guide, a farm of two wikis will be set, with these Mediawiki versions:

tintin.moulinsart.example: 1.27.3 (last LTS version)
milou.moulinsart.example: 1.29.1 (last stable version at the writing of this guide)

Note that MediaWikiFarm is compatible with any MediaWiki version, hence you can use any you want.

As an important note for fully understanding, Milou is the original name of Snowy in the beautiful Belgian French language, and Moulinsart is Marlinspike Hall.

Directories

Mediawiki and MediaWikiFarm will be installed using these directories:

Mediawiki Configuration directory: /etc/mediawiki
Cache directory: /tmp/mediawiki
Code directory: /opt/mediawiki
- MediaWikiFarm directory: /opt/mediawiki/mediawikifarm
  - MediaWikiFarm configuration directory: /opt/mediawiki/mediawikifarm/config/
- Mediawiki 1.27.3 directory: /opt/mediawiki/1.27.3
- Mediawiki 1.29.1 directory: /opt/mediawiki/1.29.1

Make sure that the following directories exist and create them if needed:

mkdir /etc/mediawiki
mkdir /tmp/mediawiki
mkdir /opt/mediawiki

Third-party softwares configuration

Hosts

As wikis created by this guide are fictional, you should add these entries into your /etc/hosts file:

127.0.0.1 tintin.moulinsart.example
127.0.0.1 milou.moulinsart.example

Nginx

Make sure that PHP is activated and that the root directive is set to /opt/mediawiki/mediawikifarm/www. Then reload nginx service:

service nginx reload

MySQL

You will create a database by wiki, and a MySQL user by database (it is also possible to share a database and a MySQL user for several wikis). Here are the SQL commands to do so:

CREATE DATABASE tintinmoulinsart;
CREATE USER tintinmoulinsart@localhost IDENTIFIED BY 'tintin';
GRANT ALL ON tintinmoulinsart.* TO tintinmoulinsart@localhost;

CREATE DATABASE miloumoulinsart;
CREATE USER miloumoulinsart@localhost IDENTIFIED BY 'milou';
GRANT ALL ON miloumoulinsart.* TO miloumoulinsart@localhost;

Mediawiki

Mediawiki versions are stored in subdirectories of the code directory. You can use any name for these subdirectories, but it is advised to use meaningful ones.

You start by downloading Mediawiki 1.27.3 using Git:

cd /opt/mediawiki
mkdir 1.27.3 && cd 1.27.3
git clone https://gerrit.wikimedia.org/r/mediawiki/core.git .
git checkout tags/1.27.3
composer install --no-dev

Then, you can download Mediawiki 1.29.1:

cd /opt/mediawiki
mkdir 1.29.1 && cd 1.29.1
git clone https://gerrit.wikimedia.org/r/mediawiki/core.git .
git checkout tags/1.29.1
composer install --no-dev

When you download Mediawiki with Git, you also need to download desired skins and extensions. For now, you only need the default skin, Vector:

cd /opt/mediawiki/1.27.3/skins
git clone -b REL1_27 https://gerrit.wikimedia.org/r/mediawiki/skins/Vector

cd /opt/mediawiki/1.29.1/skins
git clone -b REL1_29 https://gerrit.wikimedia.org/r/mediawiki/skins/Vector

MediaWikiFarm

Installation

You can use the latest available version of MediaWikiFarm in Git, as it is compatible with any version of Mediawiki:

cd /opt/mediawiki
mkdir mediawikifarm && cd mediawikifarm
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/MediaWikiFarm .
composer install --no-dev

Directories configuration

You need to create the file /opt/mediawiki/mediawikifarm/config/MediaWikiFarmDirectories.php. A sample is available in the directory /opt/mediawiki/mediawikifarm/docs/config/. Copy it and check that directories are those in Directories overview.

cp /opt/mediawiki/mediawikifarm/docs/config/MediaWikiFarmDirectories.php /opt/mediawiki/mediawikifarm/config/.
vi /opt/mediawiki/mediawikifarm/config/MediaWikiFarmDirectories.php

Farms configuration

The file /etc/mediawiki/farms.yml describes your farms:

myfarm:
  server: '(?<wiki>[a-z]+)\.(?<family>[a-z]+)\.example'
  variables:
    - variable: 'family'
    - variable: 'wiki'
  suffix: '$family'
  wikiID: '$wiki$family'
  versions: 'versions.yml'
  config:
    - file: 'conf/$family/$wiki.yml'
      key: '$wiki$family'

You can have several farms, but only one is configured here: myfarm. Paths are relative to the configuration file farms.yml.

Available Mediawiki versions for the farm are listed in the file versions.yml.
Wikis of the farm have the following format for their URLs: <wiki name>.<family name>.example.
Each wiki has a configuration file conf/<family name>/<wiki name>.yml. You can also set up configuration files by farm, suffix or wiki, in YAML, JSON or PHP syntax.

Mediawiki versions configuration

Here is an example of the file versions.yml that will work for the farm that you are setting up (several formats are possible):

miloumoulinsart: 1.29.1
default: 1.27.3

Wikis configuration

Here is an example of the configuration file conf/moulinsart/tintin.yml:

wgDBtype: 'mysql'
wgDBserver: 'localhost'
wgDBname: 'tintinmoulinsart'
wgDBuser: 'tintinmoulinsart'
wgDBpassword: 'tintin'
wgScriptPath: ''
wgUseSkinVector: true

And similarly for the configuration file conf/moulinsart/milou.yml:

wgDBtype: 'mysql'
wgDBserver: 'localhost'
wgDBname: 'miloumoulinsart'
wgDBuser: 'miloumoulinsart'
wgDBpassword: 'milou'
wgScriptPath: ''
wgUseSkinVector: true

These examples contain mainly database configuration, but you can add any Mediawiki configuration that you want.

Databases initializations

You need to initialize the databases using the following commands:

cd /opt/mediawiki
php 1.27.3/maintenance/install.php --confpath=/dev/null --dbtype=mysql --dbserver=localhost --dbuser=tintinmoulinsart --dbpass=tintin --dbname=tintinmoulinsart --lang=en --pass=mdpwiki "Tintin's wiki" "Tintin"
php 1.29.1/maintenance/install.php --confpath=/dev/null --dbtype=mysql --dbserver=localhost --dbuser=miloumoulinsart --dbpass=milou --dbname=miloumoulinsart --lang=en --pass=mdpwiki "Milou's wiki" "Milou"

Outcome

Your wikis are now available at: