Installing MediaWiki Guide

MediaWiki, the Wiki engine powering this site, is fully open-source and free. It seems to be robust, and reasonably fast. Configuring and installing it, however, is not so easy. This guide is a tutorial for MediaWiki administrators.

Dependencies

Required Software

• Apache
• PHP
• MySQL with InnoDB support! The tables created by MediaWiki will use the InnoDB engine. I don't think it is possible to use MyISAM tables.

Optional Software

• APC. This is a PHP accelerator. It no longer works in PHP 5.5, where it is normally replaced by OpCache (built in the core). However it seems opcache cannot be used yet with Mediawiki, so the best in PHP 5.5 is to install APCu instead of APC. Be sure to build it with PHP_TARGETS="php-5.5".
• memcached. This is a daemon caching SQL requests in memory. If you run two Wikis on the same machine, beware that it can cause serious problems. If there is a single memcached daemon running, and both Wikis use it, they will interfere and one Wiki will end up serving the contents of the other. A solution can be to run memcached on several machines, or maybe on the same machine but with different ports. However, this last option on Mac OS X seems to be tricky.
• ImageMagick, in order to generate the images thumbnails. This can also be done via PHP if GD support is included; however ImageMagick is recommended since it produces better quality thumbnails. Make sure you add the required USE flags on imagemagick (at least jpeg jpeg2k svg tiff webp xml). Don't forget to set $wgImageMagickConvertCommand to the correct location:

$wgImageMagickConvertCommand = "/usr/local/bin/convert";

Installation & Updates

Setup

• Installation is easy, just download MediaWiki from Sourceforge and uncompress the tarball in a directory that Apache can serve. Then follow the instructions on the README to perform the initial configuration. It involves running a PHP script that will configure the Wiki for you.

• Alternatively, you can use the www-apps/mediawiki ebuild on Gentoo, and install via webapp-config. If you do this, use the -c flag, you want files to be copied to your installation, not hard linked to the ebuild files. Also note that you may have to run composer for the installation to work (probably a bug on the ebuild or on the original tarball, who does not install every needed dependency correctly).

• Warning: the initial administrator account is named "WikiSysop", and is case sensitive. If you forget it, search it on the MySQL database directly.

• It is also recommended to increase your PHP memory_limit variable in php.ini. Else sometimes MediaWiki will fail with a message such as:

Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 80629 bytes) in /var/www/wikistuff/includes/Parser.php on line 206

I set this variable to 30 MB. Note that with PHP 5.2.4+ it should be set at least to 128MB.

• To be able to run update.php maintenance script, you may have to run the following command:

set global log_bin_trust_function_creators=1;

Multiple installations

• It is possible to serve multiple wikis (different databases and/or themes) from the same MediaWiki installation. Just create as many configuration files as you need (LocalSettings.php, which obviously needs to be renamed for each wiki), and then create a LocalSettings.php file with code discriminating based on the SERVER_NAME. Example:

<?php
	switch ($_SERVER["SERVER_NAME"])
	{
		case "wiki.shoopz.net":
			require_once "wiki_shoopz_net_settings.php";
			break;
	
		case "help.shoopz.com":
			require_once "help_shoopz_com_settings.php";
			break;
			
		default:
			echo "This wiki is not available. Check configuration.";
			exit(0);
	}
?>

• In order to add a new wiki, temporarily move your custom LocalSettings.php file. The wiki then believes it is not installed yet. Then point a browser at the wiki and follow the normal installation procedure. Once the installation script created your DB and your configuration file, move it from config/LocalSettings.php to a new file and modify the switch in LocalSettings.php accordingly. Also don't forget to move back LocalSettings.php.

• All this is not needed with Gentoo support for web applications.

Upgrading

• Normally it's enough to emerge the new version, install it with webapp-config (via upgrade), then run the maintenance script:

sudo -u apache php maintenance/update.php

• However, with recent versions it seems needed to also run composer locally (sudo -u apache composer update --no-dev). There can be permission issues, and usually I just change ownership of all MediaWiki files to the Apache user.
• Sometimes, changes to LocalSettings.php are required (if some settings were deprecated / removed by the MediaWiki team).

Removing and cleaning extensions

• To clean the database from tables installed by an old extension, there does not seem to be an automated procedure. Best is to look at the source code (for instance https://github.com/mediawiki4intranet/IntraACL/blob/master/storage/intraacl-tables-mysql.sql) and remove tables by hand.
• Normally stored procedures should also be deleted (such as https://github.com/mediawiki4intranet/IntraACL/blob/master/storage/intraacl-functions-mysql.sql). Note some of the procedures also create tables. The associated triggers should also be cleaned, for instance:

drop trigger if exists insert_category_closure_catlinks;

Configuration

• With recent (later than 1.32) MediaWiki versions, the edit toolbar is no longer present by default when editing an article. You must install this via an extension. The simplest is to load the WikiEditor extension who is installed by default, via the following line in LocalSettings.php:

wfLoadExtension('WikiEditor');

• Using an accelerator. I am not sure how it exactly works. This seems to be needed for using APC (at least as the "main" accelerator):

$wgMainCacheType = CACHE_ACCEL;
$wgMemCachedServers = array();

And this would setup support for a memcached server running on the local machine on port 11212:

$wgMainCacheType = CACHE_MEMCACHED;
$wgMemCachedServers = array (
 0 => '127.0.0.1:11212',
);

• Obtaining nice URLs: A guide to remove "index.php" from the URL is available online. However I don't find it very clear. The important steps are:
  • Unpack the MediaWiki in a directory NOT named "wiki", for example "wikistuff" will do.
  • In LocalSettings.php, set $wgScriptPath = "/wikistuff"; and $wgArticlePath = "/wiki/$1";
  • Write an Alias rule for Apache: add the line

Alias /wiki /filesystem/path/to/wikistuff/index.php

in the Apache configuration file. Note: don't add the second line as mentionned in the guide!

• Alias in Apache is just a primitive form of URL rewriting. The main installation directory for MediaWiki should not be named "wiki" because then pathes to static resources (skins, etc) will conflict with URLs for pages. I now name the installation directory just "mediawiki".

• Disabling automatic account creation and anonymous edits. Add the following lines to LocalSettings.php:

$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = false;

• Disabling anonymous reading. Add the following lines to LocalSettings.php:

# Pages anonymous (not-logged-in) users may see
$wgWhitelistRead = array( "Main Page", "Special:Userlogin", "-", "MediaWiki:Monobook.css" );

$wgGroupPermissions['*']['read'] = false;

• Customizing logo (note that it should start with the name of the wiki directory, eg /wiki here):

$wgLogo = "/wiki/path/to/logo.png";

• Allowing images uploads (set $wgUseImageMagick to false if you want to use GD instead of ImageMagick to create the thumbnails):

$wgEnableUploads = true;
$wgUseImageResize = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";

Search Features

• The default search feature is based on MySQL MyISAM engine full text search. It by default indexes only words of 4 characters at least, so searching for "tar" would not return anything. You can fix this by changing MySQL configuration, see this link.

Access Control Features

• By default, MediaWiki does not provide access control features, ie all pages are visible to everybody. It's possible to easily restrict access to logged users for the whole site, but if you want to have finer control (restrict access only to special pages), an extension is needed.
• With MediaWiki 1.34, a good option seems to use the Semantic ACL extension. It is relatively easy to install (you need the Semantic extension). Download the SemanticACL tarball, and copy it to the extensions directory. Then just follow online instructions to configure the extension. To use it just add this to the top of an article you want to restrict access to (note the | and space are important):

[[Visible to::users| ]]

• Semantic MediaWiki extension is installed by Composer (the composer.local.json file must be modified). You may need to manually change the ownership of a directory to the Apache user (if you run composer as root).
• Other options are listed on this page.
• Before that I used IntraACL extension, but it does not support recent versions of MediaWiki.

Usage

• Editing Guide, very helpful

• A guide for image placement and edition

Administration

• Deleting/removing an user is not possible with MediaWiki. You can, however, change the password with the following SQL request:

UPDATE user SET user_password = MD5(CONCAT(user_id, '-', 
  MD5('somepass'))) WHERE user_name = 'someuser';

Customization with styles / CSS

• Link to the official skins tutorial
• There is a site wide CSS style page, accessible at MediaWiki:Common.css. There is also a corresponding page for each user. Note that this CSS page can be modified directly, this is very nice. Of course you could also edit directly the CSS files present in the software distribution of MediaWiki.

Problems

• If the first page seems slow to load, it may be a redirect problem. I had this problem when accessing the wiki directly, which normally redirects to index.php/Main_Page, was very slow (15 seconds). It was a problem with the redirection via a 301 HTTP code. Changing the 301 code to a 302 in includes/Wiki.php solved the problem. However the root cause needs to be investigated (it is probably a problem with the lighttpd in front of Apache configuration).