Installing and Customizing MediaWiki

I was first introduced to the idea of a wiki many years ago. A colleague at work told me about a Web site that invited readers to become writers and editors. Over time, he said, a wiki would grow to include a great deal of knowledge, drawing from the collective experience, without the need for any centrally coordinated assignment or editing. My gut reaction was one of great ambivalence. On the one hand, a community of well-meaning and well-disciplined users could indeed use a wiki in many useful ways. But at the same time, it seemed like an invitation for chaos. And, admittedly, chaos has sometimes been the result.

Over the years, wikis have become increasingly common. Dozens of different software packages are now available, in nearly every programming language and for nearly every Web/database framework. The question is no longer whether a wiki is available, or how easily one can be installed, but rather whether a wiki is an appropriate tool for your needs and which of the existing packages is the best fit for your organization.

And although the jury is still out, at least in part, regarding the long-term viability of public wikis, the amazing Wikipedia Project has demonstrated that it is possible to have surprisingly good results. A research study released several weeks before I wrote this article reported that when it comes to science-related articles, Wikipedia is only slightly less accurate than Encyclopaedia Britanica. Given that Britanica is written and edited by paid experts, while Wikipedia relies on volunteers (who may, of course, still be experts), it is clear that wikis do not necessarily lead to the chaos that I feared.

That said, I have a strong feeling Wikipedia's reputation was preserved not because of the public's inherent love for wikis, but because of a dedicated team of Wikipedians who operate behind the scenes to ensure that the content is viable.

As I wrote above, there are many options for creating a wiki on your own Web server. One of the best-known packages is the same one that powers Wikipedia, known as MediaWiki. In this article, we discuss how you can install MediaWiki on your own server, how you can create and edit static content and how you can even create dynamic special pages.

Although Wikipedia contains an enormous amount of text, the MediaWiki software on which it runs is surprisingly small, straightforward to understand and easy to install. The software itself is written in PHP, and it relies on a MySQL database for content and indexing. That is, none of the pages on a MediaWiki site exist as files on disk; instead, they are created on the fly by the PHP programs, bringing together a number of elements for each individual visitor.

To install the MediaWiki software, you thus need a server running both PHP and MySQL. PHP works on a number of platforms, but we will assume, for the purposes of this article, that you are using the Apache server with relatively recent versions of PHP (at least 4.1.2, although 4.3 is preferred) and MySQL (at least 3.2.x, but 4.0.x is preferred). Most modern Linux distributions either include PHP and MySQL or make them available from on-line repositories without too much trouble. You need administrative privileges for both Apache and MySQL in order to install MediaWiki. If you don't run your own server, you might need to ask the system administrator for some help in modifying the appropriate configuration files.

Although you can download the MediaWiki software directly from SourceForge, you should look for it on the main MediaWiki site, www.mediawiki.org. Once on that page, click on the versions and download link (on the right side of the page), and then on the appropriate link for the current stable release. Download an older or experimental release only if you understand the problems that might be associated with it.

The software comes as a .tar.gz file containing the version number. For example, the file that I downloaded is called mediawiki-1.5.3.tar.gz, indicating that I downloaded version 1.5.3, current as of December 21, 2005. Keep that file in a temporary location (I generally prefer to put such files in a directory named /downloads); we will return to it after taking care of our Apache configuration.

If your site will run only MediaWiki software, there is probably no reason for you to modify your Apache configuration file, traditionally named httpd.conf. In such cases, you can unpack the .tar.gz file in your site's htdocs directory, as described in the instructions on the MediaWiki site. If your distribution uses another directory as its document root, you'll obviously have to adapt to your distribution's preferences.

If you want to put the MediaWiki installation in a virtual server on an existing Apache installation, you need to modify the Apache configuration file to create a new virtual host on your system. Modern versions of HTTP require that a Web browser request a document from a specific hostname. The virtual host feature in Apache allows one Web server to serve documents for many different hostnames, even when all of the names resolve to a single IP address. If you just want to try MediaWiki without affecting the rest of your site, or if the majority of your site runs under a framework (such as Zope or Ruby on Rails) that is largely incompatible with MediaWiki, a virtual host might well be a wise move. I often use such virtual hosts to experiment with new software and configurations without potentially endangering existing, stable sites.

Apache's VirtualHost sections allow you to configure one or more such virtual servers, each with its own configuration. In configuring MediaWiki for my system, I needed the following VirtualHost section in httpd.conf:

<VirtualHost 69.55.225.93>

ServerName wiki.lerner.co.il
    ServerAlias mediawiki.lerner.co.il wikipedia.lerner.co.il
ServerAdmin reuven@lerner.co.il

DocumentRoot /usr/local/apache/v-sites/wiki.lerner.co.il/www/
DirectoryIndex index.php

CustomLog
/usr/local/apache/v-sites/wiki.lerner.co.il/logs/access-log combined
CustomLog
/usr/local/apache/v-sites/wiki.lerner.co.il/logs/referer-log referer
ErrorLog /usr/local/apache/v-sites/wiki.lerner.co.il/logs/error-log

</VirtualHost>

The first two lines of this VirtualHost section define the name and aliases for this new virtual server. By adding aliases, I ensure that even if people enter a different name, they will get to the right place. (Because I have asked my hosting company to alias all hostnames in the lerner.co.il domain to my server's IP address, I can add and remove new virtual hosts whenever I want, without having to modify the DNS configuration.) I then set ServerAdmin to be my own e-mail address, ensuring that error messages will direct people to me.

Next, I indicate that the root directory for the wiki—that is, where Apache should look for the PHP programs that define it—is under /usr/local/apache/v-sites, where I put all of the virtual servers on my machine. Each site then gets a subdirectory according to its name, with two directories (www and logs) under that. So in the above configuration, I have defined the DocumentRoot to be under v-sites/wiki.lerner.co.il/www, and I have put the access, referer and error logs under v-sites/wiki.lerner.co.il/logs.

Once I have added the above configuration to httpd.conf, I restart Apache. At this point, I'll get an error if I go to http://wiki.lerner.co.il, as I haven't yet installed the software.

To install the MediaWiki software, I download the latest .tar.gz file, and open it in the v-sites/wiki.lerner.co.il:

cd /usr/local/apache/v-sites/wiki.lerner.co.il/
tar -zxvf /downloads/mediawiki-1.5.3.tar.gz
mv mediawiki-1.5.3 www

After doing that, I pointed my Web browser to http://wiki.lerner.co.il, and got a message saying that I still needed to configure the software. But the permissions weren't set quite right, meaning that MediaWiki was unable to write to its configuration directory. Rather than aborting with a hard-to-understand error message, MediaWiki kindly told me that there was a problem with the filesystem permissions, and it even reminded me how to use chmod to fix the problem.

After having changed the permissions, MediaWiki then showed me the initial configuration screen. To be honest, I didn't have to do very much; I entered the name of my wiki (ReuvenWiki), and I kept the defaults for nearly everything else. I entered a password for the WikiSysop user within the wiki system itself. And, I entered a password for the database user and also entered the password for the MySQL administrative user.

Remember, you're keeping track of three types of user names here, which can be a bit tricky. Your Linux system has one set of users and permissions, MySQL has its own set of users and permissions, and the MediaWiki software also has its own set of users and permissions. Although this might seem like overkill, it provides a great deal of flexibility, allowing you to run MediaWiki in a safe, secure environment.

Once I filled out all of the above information, I clicked on the Install! button. Unlike many Web applications, which produce output only when they have finished with their work, the MediaWiki installer kindly provides updates as the installer is running, giving you a sense of what it is doing and how much longer you might have to wait. In the end, you should (hopefully) see a note indicating that the installation was successful, and that you should move config/LocalSettings.php into the parent directory (the www directory):

mv -v config/LocalSettings.php .

Having done that, I can re-enter the URL (http://wiki.lerner.co.il) into my Web browser. And, sure enough, I'm greeted by MediaWiki's initial page, which tells me that the software has been installed successfully and points me to two pages, one for customizing the interface and another describing usage and configuration.

If you have ever used Wikipedia, navigating through a MediaWiki site will be extremely familiar to you. If not, the basic rules are as follows: clicking on a link within a page brings you to another page within the MediaWiki site. The exception is when the link is followed by an arrow icon, which indicates that the link will open a site on another server. All pages on the site are not only viewable by the general public, but they also are editable. If you want to change the contents of a page, click on the Edit link (at the top of each MediaWiki screen), modify the contents as you see fit, and then click on the Save button when you are done.

MediaWiki tries to make it as easy as possible for users to participate without having to understand the technical side of things. It's thus unnecessary for end users to know HTML; they instead can click on a variety of buttons (and use a simplified formatting system) to format postings they make to the system. For example, entering [[Foo]] creates a link to the page Foo, regardless of whether it already exists. And, entering a link of the form [[Foo | This leads to Foo]] inserts a link to the Foo page, but with the text “This leads to Foo”.

More important than MediaWiki's simple markup language is the fact that every change made to the system is kept in an easy-to-use version-control system. By clicking on the History link on a given page, even a nontechnical user can view previous versions of a page, see who has made a given change or compare two versions of a particular document. In addition, users can set up watch lists, such that the user receives an e-mail message every time a page is modified. This allows users with particular interests and expertise to keep up with the latest updates to a given page and to monitor the content for potential damage.

By default, the left side of every page contains a short menu of commonly accessed links, including the main page (home page) of the wiki, a list of recent changes, a random existing page and the documentation. There is also a search box on the left side. Entering a text string and clicking on the Search button brings up a list of documents whose titles and/or contents match the target string. Because MediaWiki contents are all in the MySQL database, and because modern versions of MySQL have built-in text-indexing routines, such searches are relatively speedy.

Each page in a MediaWiki site has a URL that begins with the overall site URL (in my case, that would be http://wiki.lerner.co.il), followed by index.php/, and then the title of the page. Page titles may contain spaces, in which case the URL replaces each space with an underscore character. The page named Reuven Lerner on my server would thus have a complete URL of http://wiki.lerner.co.il/index.php/Reuven_Lerner. Somewhat frustratingly, MediaWiki URLs are case-sensitive, which means that entering an incorrectly capitalized word can result in the creation of a new page. Remember, a wiki never produces a true “not found” error, because you (the visitor) might well be interested in starting that very page.

There is no hierarchy to pages in a MediaWiki site. There is a single namespace, which can potentially lead to confusion. To reduce ambiguity, pages may contain additional information in parentheses (which are then part of the URL). Or, users can create a disambiguation page, which contains links to a number of pages with similar or identical names.

If you want to allow users to upload images, you need to modify the LocalSettings.php file that should now exist in your server's DocumentRoot directory. In the version I installed, line 73 of LocalSettings.php (just beneath a relevant comment in the PHP code) contains a commented-out definition of $wgEnableUploads, setting it to true. By uncommenting this line, you allow users to upload images to the server. These uploads will be, by default, in the images subdirectory (www/images), whose permissions must be writable by the Apache process.

Once you have turned on the uploading of images, logged-in users will be able to upload them with a two-step process. First, they click on the insert image button when editing a wiki page, or manually insert tags of the form [[Image:Example.gif]]. (Images all have the Image: prefix in MediaWiki, but there is a single, flat namespace for images, as is the case for textual content pages.) Once users have finished editing the page, they can then click on the missing image link. This will bring them to an HTML form allowing the missing image to be uploaded via the user's browser. Other types of documents can be uploaded in a similar way.

Wikis are a specialized form of content-management system (CMS). As such, they are programs whose goal is to display the most recent version of a generally static document. This contrasts with many other server-side programs, whose content changes for each user and invocation. Of course, MediaWiki must scan each document as it is published, in order to generate the different URLs needed for the existing and new links mentioned within the body of the text. But for the most part, MediaWiki specializes in the easy creation and distribution of static content, rather than programmatic pages.

However, MediaWiki's authors recognized that they and others probably will want to create dynamically generated pages, and thus was born the Special: designation. Any page whose name begins with Special: is treated—well, it's treated differently, populating the document body with the output of a PHP function. In order to create our own special page, we need to write a PHP function and then register that function with MediaWiki.

The first step is to create a new MediaWiki extension, putting it in the extensions directory just under the MediaWiki DocumentRoot. (The basic MediaWiki distribution includes this directory, but it is normally empty after a fresh install.) We will create the file extensions/SpecialHello.php, which looks like this:

<?php
$wgExtensionFunctions[] = "wfExtensionSpecialHello";

function wfExtensionSpecialHello()
{
    global $wgMessageCache;
    $wgMessageCache->addMessages(array('hello' => 'Hello page'));

    require_once('includes/SpecialPage.php');
    SpecialPage::addPage(new SpecialPage('Hello'));
}

?>

The first line appends our function's name (“wfExtensionSpecialHello”) to the global array $wgExtensionFunctions, putting this function in the directory of extensions. Many MediaWiki extensions change the output from certain tags; in this case, we are looking to create an entire page, rather than modify the behavior of a tag. Nevertheless, we are creating an extension.

Next, we define our function. The first thing that we do is modify $wgMessageCache, such that our extension will look like a special page rather than a tag-modifying extension. The special page will continue to work if we fail to include these initial two lines, but its listing on Special:Specialpages will look odd, with the title coming between < and > brackets as if it were a tag. Note that the page name must begin with a lowercase letter in the call to addMessages, even when it is capitalized in the call to SpecialPage::addPage. Failing to note this quirk of capitalization will result in strange page titles.

The final two lines import the code specific for special pages, and then create an instance of such a special page, adding it to the directory.

Just what our special page does depends on another file of the same name (that is, SpecialHello.php), located in the includes directory that is parallel to extensions, just under the MediaWiki DocumentRoot. This directory contains a large number of standard special pages that come with MediaWiki, including SpecialNewpages.php, SpecialUserrights.php and SpecialImagelist.php. These functions can access the back-end MySQL database, perform calculations and access external sites—and then pipe the results back into a standard MediaWiki output page.

Here is a simple version of what we might put into our includes/SpecialHello.php file:

<?php
function wfSpecialHello() {
global $wgOut;
$wgOut->addHTML('Hello, world');
}
?>

The above function, which is invoked whenever we go to the Special:Hello page, adds the HTML “Hello, world” to the output. Notice that we don't have to begin, end or otherwise modify the HTML file that is sent to the user. Nor do we need to worry about choosing a skin, setting up menus or other details. However, we do need to be careful about whitespace, as is often the case with PHP programs—failing to trim whitespace before the initial <?php tag might well produce odd error messages from PHP about modified headers.

Finally, we register our extension and special page in the LocalSettings.php file, adding the following line:

require_once("extensions/SpecialHello.php");

Once you have put the above in place, your site should now have a Special:Hello page, listed as Hello when you visit Special::Specialpages.

Wikipedia has generated a number of headlines over the last few months, and its future as a reliable, neutral, volunteer effort remains to be determined. But Wikipedia has demonstrated the power that a wiki can bring to an organization looking to collect information from a wide variety of participants. If your organization would benefit from a centralized repository created in a decentralized manner, a wiki might just fit the bill.

And, although MediaWiki is far from the only available package, it is highly polished, reliable and easy for both administrators and users. Producing new dynamic pages, known as special pages in the MediaWiki world, requires a fair amount of knowledge of the underlying system. But, getting started is not that difficult, and it is possible (and desirable) to take advantage of the tremendous infrastructure that MediaWiki brings to the table.