Chapter 2 Setting up MediaWiki

You can see the following page to see what versions of PHP, and of the different database systems, each version of MediaWiki is compatible with:

Docker is extremely popular software that uses an approach called virtualization to simulate an entire an entire mini-operating system within your real operating system. The mini-OS is referred to as a “container”, while the package that defines it is called an “image”, and this approach makes it much easier for package/image developers to ensure that what gets downloaded will work correctly regardless of the machine it is run on. Docker, or at least virtualization (since there are some notable Docker competitors, like Podman) seems to represent the future of MediaWiki installation. Some of the notable Docker-based MediaWiki pages are:

If you have Git installed, you can download MediaWiki with the following call:

This will create a directory named “core”, which you can (and should) then rename, ideally to “w”.

Once you've completed all the setup steps, a LocalSettings.php file will be created automatically, and a new database should be created as well on your database system.

Most, though not all, of MediaWiki's skins include a spot for a logo, at the top left-hand corner of the screen (or top right-hand, if the wiki is in a right-to-left language). In MediaWiki, the logo is the customary way to individualize one's wiki – for better or worse, most skins don't display the name of the wiki anywhere on the page (other than indirectly at the bottom, in the “About ___” link). So the logo should show the name of the wiki, and ideally some representative graphic – though that part is strictly optional; it's much better to have a logo that just states the wiki name than no logo at all.

MediaWiki wikis do have a default logo, which is the standard MediaWiki logo with the words “Set $wgLogos with the URL path to your own logo image” over it. As the instructions say, you need to specify a value for $wgLogos in your LocalSettings.php file. $wgLogos is a relatively new setting (before version 1.35, it was just called $wgLogo and took a single string); its current configuration is somewhat unnecessarily complicated, and looks to be simplified in the future, but the simplest way to set is is to add something like this to LocalSettings.php:

The logo image can be located either within the MediaWiki directory, or at some arbitrary URL. By default, it's located at /skins/common/images/wiki.png – you shouldn't replace that file with your logo image, though, because then you run the risk of it being overwritten when you update the MediaWiki code.

By default, MediaWiki URLs appear in a format like:

However, the preferred format is something more like:

This is the format that Wikipedia and other Wikimedia sites use. The “wiki” directory can have any name, though “wiki” makes sense for obvious reasons.

There are various approaches to changing the URL format, based primarily on whether you have root access on the server on which the wiki resides. You can see all the steps required for the various approaches here:

As new versions of MediaWiki come out, you're generally advised to keep updating to the latest version – there are always bug fixes, interface improvements, and interesting new features. It's generally pretty easy to update, though it depends on whether you're using Git or not. If you are, you can just run a “git pull” in the directory housing your MediaWiki code. Then, you'll need to call the script “update.php”, located in MediaWiki's maintenance/ directory – it goes through the database and adds or modifies database tables to fit the new DB schema for this version. update.php tends to work very well – it even works when upgrading from extremely old versions.

If you're downloading the new MediaWiki version as a package, instead of via Git, then you'll need to move the images/ directory, the extensions/ directory (or at least parts of it), and LocalSettings.php into this new directory, and rename both it and the old MediaWiki directory so that the wiki URL will now point to this one. As before, you'll need to call update.php.

And if you're using any extensions besides the ones that come pre-bundled with MediaWiki, then you might have to get the latest versions of those as well. Extensions that don't work with a certain MediaWiki version tend to break pretty easily when you try them out, so it should be fairly straightforward to see if any extensions need updating.

A crucial part of the MediaWiki system is the plugins, or extensions, that have been developed to be added to the MediaWiki core application. Over 1,500 publicly-released extensions exist in some form currently; though many of these are obsolete or redundant, and many never fully worked in the first place, so the number of extensions that could conceivably be used at any one time is probably closer to several hundred. Extensions in MediaWiki cover a very wide range of functionality. Some of it is rather essential functionality, which could easily belong directly within MediaWiki but was never added for one reason or another. An example is the Cite extension, which defines tags that can be used to show footnoted references; it's heavily used on Wikipedia, and there's no strong reason why it's not part of core MediaWiki.

Almost all MediaWiki installations include at least a few extensions; Wikipedia uses dozens of them.

The core MediaWiki code is structured in a way that makes it easy to install extensions, and develop them: the key element is the widespread use of hooks. Hooks are lines in the code that outside functions can register themselves to be called at. When a hook runs, every function that has registered itself with that hook is called, and each one can then perform its own actions. A simple example of the use of hooks would be an extension that displays ads on each wiki page. The extension would most likely register with one or more hooks in the code that are called when the the display of the page is generated, in order to add its own snippets of HTML to the page. The big advantage of hooks is that they let extensions run without the administrator having to modify the core MediaWiki code – something that makes installing and upgrading the code much easier.

Some extensions define their own special pages; some define their own parser functions, tags, behavior switches, etc.; and some add their own tables to the database. The more involved extensions may do all of these things: use hooks, add tables to the database, define special pages to (in some cases) display and modify their data, and define various commands, like parser functions and the rest.

This book covers a fairly large number of extensions, but it doesn't cover all of them – and the “ecosystem” of extensions keeps changing, with new extensions being created, others becoming unnecessary due to changes in MediaWiki, and others becoming unusable as they stop being maintained. So it's important to know how to find extensions, and how to determine which ones are useful.

Once you've found an extension that you want to use, the next step is of course to install it. Many applications make it easy to install extensions or plugins, directly from within the user interface; that includes both consumer applications like Google Chrome, and server-side applications like WordPress. MediaWiki, unfortunately, is not one of them – code has to be downloaded and installed manually.

So you will have to get the code for each extension yourself, in one way or another. How you do this depends on the extension, as well as on your system. Most of the MediaWiki extensions, including nearly all of the actively-maintained ones, can be found on the Wikimedia Git repository (Git is a version-control system). A few extensions, though, have their code located elsewhere, such as on the site GitHub, or in some cases (though this is not recommended), directly on the extensions' wiki pages on mediawiki.org. Every extension should have its download details available on its mediawiki.org page.

If you have Git on your server, and the extension you want to install can be downloaded with one of those, then that's the ideal way to do it. If you don't have Git and thus can't automatically download an extension, there are a few alternatives. One is to get the extension as part of a package or bundle.

Notable distributions of MediaWiki and extensions (as well as skins) include: