Chapter 2 Setting up MediaWiki
The MediaWiki environment
MediaWiki is a program written in PHP , a very popular language for web applications. It can run on any operating system that PHP can run on, which is all the major ones. Similarly, it can run on any major web server. MediaWiki requires a database, which can be of type MySQL/MariaDB, PostgreSQL or SQLite. (Support for both Microsoft SQLServer and Oracle was dropped in 2019).
By far the most popular setup for MediaWiki is what's known as the “ LAMP stack”: Linux, Apache, MySQL and PHP. Only the last of these is required, but the other three are encouraged. Users have also had success with Nginx instead of Apache, in what is known as a “LEMP stack”; it seems to handle large amounts of web traffic better.
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:
Download and installation
There are a number of ways to download and install MediaWiki, both through conventional means and, more recently, via a number of (mostly Docker-based) packages.
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:
- Canasta (https://canasta.wiki) – a MediaWiki Docker image that comes with its own command-line interface, and a large set of pre-installed extensions and skins.
- Docker's own MediaWiki image (https://hub.docker.com/_/mediawiki) – created with no involvement from the Wikimedia Foundation, but it's easy to install, and seems to work fine.
- MediaWiki-Docker (https://www.mediawiki.org/wiki/MediaWiki-Docker) – “a Docker based development environment” that comes pre-installed with MediaWiki core; so you still need to download (and install) MediaWiki in the standard way in order to use it.
- mwcli (https://www.mediawiki.org/wiki/Cli) – a “MediaWiki Command-Line Interface” that installs via Docker, similar in concept to Canasta, although it does not include any extensions or skins.
If you want to simply download and install MediaWiki in the standard way, there are essentially two ways to do it: as a “tarball”, or a single archive file; or via Git , a version-control system. Using Git is the recommended method, because it's easier to install, and it lets you upgrade your code much more easily later on. But if you don't have Git, you can get the code from here:
When MediaWiki is downloaded as a tarball, it comes pre-bundled with some number of extensions , contained in the extensions/ directory. The current set of extensions is: AbuseFilter, CategoryTree, Cite, CiteThisPage, CodeEditor, ConfirmEdit, Gadgets, ImageMap, InputBox, Interwiki, Math, MultimediaViewer, Nuke, OATHAuth, PageImages, ParserFunctions, PdfHandler, Poem, Renameuser, Replace Text, Scribunto, SecureLinkFixer, SpamBlacklist, SyntaxHighlight, TemplateData, TextExtracts, TitleBlacklist, VisualEditor and WikiEditor. (Most of these extensions will be discussed in some detail later in the book.)
If you have Git installed, you can download MediaWiki with the following call:
git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git
This will create a directory named “core”, which you can (and should) then rename, ideally to “w”.
Once you've downloaded the main MediaWiki code, go to the URL for that code in a browser. At that point, assuming you have PHP, a database system and a web server running, the MediaWiki code should get executed correctly, and it will then look for a file called LocalSettings.php – by default, it's not there, and its absence tells MediaWiki that this is a new installation. LocalSettings.php is the initialization file for MediaWiki, holding all the user-modifiable settings for the wiki; we'll get to many of them over the course of this book. Since LocalSettings.php is not there, MediaWiki will guide you on the browser through a series of steps where you have to specify the wiki's name, the name of the database to be created, and other settings, including the username and password for the wiki's first user (by default, the username is “WikiSysop ”). This user is important even if you plan to create a different one for yourself later, because it has administrator privileges, so if you want to give yourself administrator privileges (and you will), the best way to do it is via that user.
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.
Setting the logo
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:
$wgLogos['icon'] = '/path/to/your/logo';$wgLogos['1px'] = '/path/to/your/logo';
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.
Changing the URL structure
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:
We'll just note that there are some cases when users want to have a URL structure that looks simply like:
It's certainly a clean-looking URL, but this approach is not recommended, because, among other reasons, it makes it tricky to have helper files like robots.txt and favicon.ico. You can see a longer discussion of this approach here:
Finally, you can also change the name of the start page, which by default is (in English) “Main Page”, by changing the contents of the page “MediaWiki:mainpage”. This is an example of interface text editable via the wiki, of which there are hundreds of examples – see here for a complete description.
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.
The site mediawiki.org is the main resource for finding out about extensions. Every extension is meant to have a page there, so you can do text searches to find specific functionality you're looking for. You can also use the “Extension Matrix”, which is actually a collection of pages, which hold different views of the full collection of extensions:
If you do find an extension, it's useful to know whether it will work on your system. There are a few clues you can use for that. Every extension page should have an infobox, listing important information about that extension. One of the fields is “Status”, which can be either “Experimental”, “Unstable”, “Beta”, “Stable” or “Unknown”, with “Stable” of course being the preferred one. This status is usually just set by the extension's authors, though, so it may be out-of-date, and it may not have been accurate in the first place.
Extension pages usually also list what versions of MediaWiki the extension is compatible with. This information can again be out of date (especially if it reads something like “MediaWiki 1.20 and higher”), but it can also be useful information.
Extension pages will also usually specify, at the bottom, whether they are in use by any official Wikimedia projects, and whether any packages of extensions (see the next section) and/or wiki farms include them. The more of these appear at the bottom of an extension's page, the more likely it is that the extension is usable – and useful.
Another good way to check the viability of an extension is to look at its talk page. If the extension hasn't worked with versions of MediaWiki from the last two years, there will probably be at least a few messages to that effect. You can also get a sense from the talk page of how committed the authors or maintainers are to maintaining the code and supporting users.
Conversely, if there are no or few talk-page messages, that's quite possibly a sign that people don't find the extension useful (or comprehensible).
Finally, simply the fact that an extension's code is contained on the MediaWiki Git repository is to some extent, for reasons of both cause and effect, a positive sign about its maintenance.
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:
- BlueSpice (https://bluespice.com)
- Canasta (https://canasta.wiki)
- Open CSP (https://open-csp.org)
- semantic::core (https://semantic.wiki/de/core)
Besides downloading packages, you can also usually download extensions directly. One easy way to download extensions is via the “Extension Distributor ”:
It's a page on mediawiki.org that creates a downloadable file on the fly, for any extension that's in the MediaWiki Git repository, and any applicable version of MediaWiki. However, for most extensions, these files represent a random snapshot that may not even hold a working set of code – for instance, someone may have made some bad change to the code right before the snapshot was taken.