how to create the perfect MediaWiki wiki

Note: This is a work in progress.

This guide will show you how to create and configure a feature-rich MediaWiki installation. When you are finished following these instructions, you will have a MediaWiki installation that differs from standard installations in the following ways:

Your wiki will be able to run alongside other wikis on the same virtual or physical host (i.e., this wiki will play nice with other wikis on the same host).
Your wiki's URLs will be friendly.

prerequisites

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

Your virtual host has already been configured and 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 packages mediawiki and imagemagick.

step ?: Build the wiki folder.

Your first task is to set up your virtual host's wiki folder. This process requires you to create symbolic links to some of MediaWiki's program files and to actually copy others. You will also need to configure some file permissions. Root privileges are required for this step.

First, determine the folder name of your new wiki project. If your site is only going to have a single wiki, then "wiki" is probably a good choice. This will make the base URL of your new wiki look like this:

http://sharkysoft.com/wiki/

Be aware that while, in this example, "wiki" is the apparent folder name of the wiki (according to the URL), the actual folder name in your file system will be different. (They'll be different because of a configuration we'll use to enable clean URLs. More on this later.) After you have selected your wiki's folder name, create your new wiki's base folder at the desired location under your virtual host's document root, adding "-scripts" to the name. Then make this new folder your working folder. The commands you enter might look like this:

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/, by entering the following commands:

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 and say goodbye forever.
images is a per-wiki folder that will store your new wiki's media uploads. (It really ought to be called "media".) This folder should not be shared by other wikis, so we don't want to just 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 ?: Initialize the wiki.

Point your browser at the (temporary) 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. You're largely on your own here, but 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 separate wiki user for this wiki instance. The base name you selected previously (or the wiki name) might make a good DB username.
When asked for the superuser account, for some reason, accounts that merely have sudo privileges are insufficient. Choose an actual root user.

After you have answered all of the necessary questions, press Install MediaWiki. If MediaWiki finds your answers to be inadequate, it will let you know and ask again. 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, has actually been saved 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, rather shockingly called called "Main page," should be displayed. Congratulations! Your wiki is running, and basic configuration is complete! But let's not stop here. With just a little more effort, we can pimp this wiki and make it much better.

step ?: Isolate database credentials.

As you learn more about MediaWiki and the wide array of extensions and configuration options it supports, you are very likely to spend a lot of time customizing the contents of LocalSettings.php. This is certainly encouraged. However, if you edit this file in a public settings, you need to take some care that your database passwords, which are included by default in this file, are never visible on your screen. One way to do this is to remove the database credentials from this file altogheter, and place them in a separate file that the original file references.

Prepare to do this by entering the following commands:

cp LocalSettings.php DatabaseSettings.php
chmod 640 DatabaseSettings.php
sudo chgrp www-data DatabaseSettings.php

Now open DatabaseSettings.php and delete every line that doesn't begin with "$wgDB".

WORKING HERE

Don't forget <?php or you will expose your password.

step ?: 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 = "$wgScriptPath/images";

The first variable, $wgUploadDirectory, indicates, relative to the wiki software'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. If you plan to secure your wiki's images from non-authenticated users (i.e., users), then set it instead as follows:

$wgUploadPath = "$wgScriptPath/img_auth.php";

Finally, to turn on image uploads, locate 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 ?: Configure aliasing in Apache.

Finally, in order to make your wiki appear as if it is still installed in the "wiki" folder, we will command Apache to service any request for /wiki as a request for /wiki-scripts/index.php. Begin by opening the virtual host configuration file:

cd /etc/apache2/sites-available
sudo nano (the virtual host file name)

Add the following directive:

Alias /wiki <your site's document root>/wiki-scripts/index.php

Please note a few things about this directive:

The first parameter is the URL where you want your visitors to believe the wiki is at.
The second parameter is the local file system path to your wiki's main script.
Modify either of these parameters as required for your particular installation.

Save the configuration file, close your editor, and restart Apache:

sudo service apache2 restart

step ?: Update your wiki configuration file.

Since you moved your wiki installation, you'll need to update your wiki configuration file. Open the file in preparation for editing:

cd wiki-scripts
nano LocalSettings.php

Now find the following variables and set them to the values shown. If the variables don't exist, create them:

$wgArticlePath = "/wiki/$1";
$wgUsePathInfo = true;

step ?: Configure your wiki's logo.

If you have replaced the default MediaWiki logo that appears in the upper-left corner of your wiki's pages, and the replacement image is in your wiki's installation folder, you may also need to update the logo location as well:

$wgLogo = "$wgScriptPath/logo.png"

step ?: Disable forced capitalization.

# Do not require pages to begin with capital letters.
$wgCapitalLinks = false;

step ?: Set the main page.

http://localhost/wiki/MediaWiki:Mainpage

Create

Delete Main page

step ?: Fix the sidebar.

MediaWiki:Sidebar / create

step ?: other configs

# Do not require pages to begin with capital letters.
$wgCapitalLinks = false;

# Allow changing page title:
$wgAllowDisplayTitle = true;
$wgRestrictDisplayTitle = false;

# Enable the NoTitle extension:
require_once("$IP/extensions/NoTitle/NoTitle.php");

# Enable a rich editor.
require_once("$IP/extensions/FCKeditor/FCKeditor.php");

# Restrict editing to authenticated users:
$wgGroupPermissions['*']['edit'] = false;

$wgGroupPermissions['*']['read']    = false;
$wgGroupPermissions['*']['createaccount']    = false;
$wgGroupPermissions['user']['delete'] = true;

$wgWhitelistRead = array
( "$wgSitename", 
  "Special:Userlogin", 
//  "Special:Search", 
  "$wgSitename:About",
  "-", 
  "MediaWiki:Monobook.css" 
);

# Enable PDF uploads.
$wgFileExtensions[] = 'pdf';
require_once("$IP/extensions/PdfHandler/PdfHandler.php");

# Enable password reset extension.
$wgGroupPermissions['sysop']['passwordreset']   = true;
require_once( "$IP/extensions/PasswordReset/PasswordReset.php" );

# Enable merging and deleting users.
require_once( "$IP/extensions/UserMerge/UserMerge.php" );
$wgGroupPermissions['bureaucrat']['usermerge'] = true;

# Enable the Interwiki database editor:
require_once("$IP/extensions/Interwiki/SpecialInterwiki.php");
$wgGroupPermissions['sysop']['interwiki'] = true;

step ?: 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!

how to create the perfect MediaWiki wiki

Contents

prerequisites

step ?: Build the wiki folder.

Step ?: Initialize the wiki.

step ?: Isolate database credentials.

step ?: Enable image uploading.

step ?: Configure aliasing in Apache.

step ?: Update your wiki configuration file.

step ?: Configure your wiki's logo.

step ?: Disable forced capitalization.

step ?: Set the main page.

step ?: Fix the sidebar.

step ?: other configs

step ?: Test your installation.

other considerations

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Tools