how to configure a feature-rich MediaWiki instance

The standard MediaWiki installation on an Ubuntu 11.10 system is not terribly dazzling.  All of the basic features needed for a wiki are present, but there are several limitations:

• It is not designed to support virtual hosts or wikis.
  
• The article URLs are not friendly and contain geeky expressions, such as "index.php".
  
• The editor targets geeks, not ordinary people.
  

This article will guide you through the setup of a new MediaWiki instance that is free of these limitations.

prerequisites

Setting up Apache, PHP, virtual hosts, etc. is beyond the scope of this article.  This article assumes the following:

• You have configured a virtual host and it is working properly.
• You have root access (via sudo).
• You have already installed all of the software necessary to run MediaWiki.  If not, at least install the following packages:
  • mediawiki
  • imagemagick.

step 1: Build the wiki folder.

Your first task is to set up your virtual host's wiki folder.  This process requires you to create symlinks to some of MediaWiki's program files and to copy others.  You will also need to set up some file permissions. Root privileges will be required.

Begin by creating your new wiki's base folder at the desired location under your virtual host's document root. Make it your working folder, as follows:

cd <your site's document root>
mkdir wiki-scripts
cd wiki-scripts

Next, create symlinks to most of the MediaWiki files under /usr/share/mediawiki/, as follows:

ln -s /usr/share/mediawiki/* .
rm LocalSettings.php AdminSettings.php images config

The files removed by the second command are removed for the following reasons:

• LocalSettings.php is a per-wiki configuration file.  You need a separate version of this file for each wiki instance.  We'll create this file later.
• AdminSettings.php is another configuration file. It was used by older MediaWiki installations but is now deprecated. Nuke it.
• images is a per-wiki folder that will store your new wiki's media uploads. It should not be shared by other wikis, so we don't want to use the "common" one pointed to by the symlink.  We'll create this folder later.
• config contains the program necessary to initialize your new wiki.  If you symlink to the master copy instead of making your own, isolated copy, your new wiki's config file will be saved inside the master copy's folder. Obviously, you don't want this.

Make a local copy of the initialization program:

sudo cp -a /var/lib/mediawiki/config .

You should now be ready to initialize your wiki. If all has gone well, a listing of your wiki's folder (generated with ls -al) will resemble the following:

total 15
drwxr-xr-x  4 sharky   sharky   4096 2010-09-04 22:40 .
drwxr-xr-x 19 sharky   sharky   4096 2010-09-04 22:16 ..
lrwxrwxrwx  1 sharky   sharky     28 2010-09-04 22:37 api.php -> /usr/share/mediawiki/api.php
drwx------  2 www-data www-data 4096 2010-09-04 16:12 config
lrwxrwxrwx  1 sharky   sharky     31 2010-09-04 22:37 extensions -> /usr/share/mediawiki/extensions
lrwxrwxrwx  1 sharky   sharky     33 2010-09-04 22:37 img_auth.php -> /usr/share/mediawiki/img_auth.php
lrwxrwxrwx  1 sharky   sharky     29 2010-09-04 22:37 includes -> /usr/share/mediawiki/includes
lrwxrwxrwx  1 sharky   sharky     30 2010-09-04 22:37 index.php -> /usr/share/mediawiki/index.php
lrwxrwxrwx  1 sharky   sharky     38 2010-09-04 22:37 install-utils.inc -> /usr/share/mediawiki/install-utils.inc
lrwxrwxrwx  1 sharky   sharky     30 2010-09-04 22:37 languages -> /usr/share/mediawiki/languages
lrwxrwxrwx  1 sharky   sharky     32 2010-09-04 22:37 maintenance -> /usr/share/mediawiki/maintenance
lrwxrwxrwx  1 sharky   sharky     40 2010-09-04 22:37 opensearch_desc.php -> /usr/share/mediawiki/opensearch_desc.php
lrwxrwxrwx  1 sharky   sharky     36 2010-09-04 22:37 profileinfo.php -> /usr/share/mediawiki/profileinfo.php
lrwxrwxrwx  1 sharky   sharky     33 2010-09-04 22:37 redirect.php -> /usr/share/mediawiki/redirect.php
lrwxrwxrwx  1 sharky   sharky     35 2010-09-04 22:37 redirect.phtml -> /usr/share/mediawiki/redirect.phtml
lrwxrwxrwx  1 sharky   sharky     26 2010-09-04 22:37 skins -> /usr/share/mediawiki/skins
lrwxrwxrwx  1 sharky   sharky     38 2010-09-04 22:37 StartProfiler.php -> /usr/share/mediawiki/StartProfiler.php
lrwxrwxrwx  1 sharky   sharky     30 2010-09-04 22:37 thumb.php -> /usr/share/mediawiki/thumb.php
lrwxrwxrwx  1 sharky   sharky     34 2010-09-04 22:37 trackback.php -> /usr/share/mediawiki/trackback.php
lrwxrwxrwx  1 sharky   sharky     31 2010-09-04 22:37 wiki.phtml -> /usr/share/mediawiki/wiki.phtml

You are now ready to initialize your wiki.

step 2: Initialize the wiki.

Point your browser at the URL of new wiki folder you created:

http://sharkysoft.com/wiki-scripts/

Since the wiki has not been initialized yet, you'll be greeted with the following screen:

Select the link to move forward to the setup screen. This is the place where you define all of the parameters for your new wiki. Hopefully, the fields and their instructions are clear enough for you to follow.

Here are some tips:

• As you enter the name of your wiki, be aware that MediaWiki will automatically capitalize the first character of your wiki's name.
• Choose a database name that resembles the name of your wiki. 
  
• Create a new wiki user for this wiki instance.  The name of the wiki might make a good DB username.
  
• When asked for the superuser account, provide credentials for a MySQL user that has database/user create privileges, such as the MySQL superuser.
  

Answer all the necessary questions and press Install MediaWiki.  If MediaWiki finds your answers to be inadequate, it will let you know and return the form for correction.  If MediaWiki installation is successful, you will see a message, similar to the following, at the bottom of the results page:

Installation successful! Move /var/lib/mediawiki/config/LocalSettings.php to /etc/mediawiki, then follow this link to your wiki.

You should change file permissions for LocalSettings.php as required to prevent other users on the server reading passwords and altering configuration data.

This message is partly a lie. The new config file for your wiki, LocalSettings.php, is actually under the new config folder you created earlier. Move this file up one folder, into your new wiki's root folder, set appropriate access rights, and delete the now-useless config folder, as follows:

sudo mv config/LocalSettings.php .
sudo chown sharky.www-data LocalSettings.php 
chmod 640 LocalSettings.php
sudo rm -r config

At this point, your wiki should be partly useable. Test it out by pointing your browser to the wiki. The main page should be displayed. Congratulations! Your wiki configuration is almost complete!

step 3: Enable image uploading.

The designers of MediaWiki felt that images are more efficiently stored as ordinary files in the file system, rather than as BLOBs in the wiki's MySql database. Thus, to enable image uploading, you'll need to configure both the folder where the images are stored, and a URI for accessing them from that folder.

First, let's create the folder where your new wiki's images will be stored. Using a console, from the wiki's base folder, enter the following commands:

mkdir images
chmod 755 images
sudo chown www-data.www-data images

It is important to ensure the images permissions are configured correctly so that Apache can store new images uploaded through the wiki. Double-check your work by typing ls -l and verifying that the entry for images has the following appearance.

drwxr-xr-x  2 www-data www-data 4096 2010-09-04 22:39 images

Next, open your LocalSettings.php file in your favorite text editor and append, to the bottom, the following lines:

$wgUploadDirectory = "images";
$wgUploadPath = "/wiki/images";

The first variable, $wgUploadDirectory, indicates, relative to the wiki's base folder, the Apache-writable folder where MediaWiki will store uploaded media files (which are generally images).

The second variable, $wgUploadPath, indicates the URI path, relative to the wiki's domain, where the uploaded media files can be found.

Finally, to turn on image uploads, find the $wgEnableUploads variable -- it should already be defined in the file -- and set it to true.

$wgEnableUploads = true;

You may also want to allow linking to external images. Various schools of thought exist as to whether you should do this, but if you want to, add the following line to LocalSettings.php:

$wgAllowExternalImages = true;

And that's it! If everything went well, you should be ready to enjoy a rich, image-filled MediaWiki experience.

step 4: Test your installation.

Now that your wiki is installed, it's time for that all-important step of testing. At the very least, be sure to test the following features:

• page editing
• page creation
• user creation
• image uploading
• image viewing

other considerations

At this point, probably no one knows your wiki exists. Unless you want to fly under the radar, you will probably want to remedy this by creating links to your wiki from other pages on your web site, such as your site's root page.

There are myriad extensions and configuration options you can play with to customize your wiki. Don't be afraid to experiment. My favorite is FCKEditor, which allows your wiki's editors to enjoy the comfort of a graphical "word processing" interface for editing pages. I've found that without this extension, it's very difficult to entice non-geeks to edit pages.

You may also decide it's a good idea to lock down your wiki, so that only authorized users can create user accounts, and so that only valid users can edit content. This is left as an exercise for you to work out -- at least until I create the lock down tutorial. :-) Happy wiki-ing!