how to create the perfect MediaWiki wiki

2012-05-16T22:32:48Z

step ?: Set the main page.:

New page

''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 run alongside other wikis running on the same virtual and 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 <tt>sudo</tt>).
*You have already installed all of the software necessary to run MediaWiki.  If not, at least install packages <tt>mediawiki</tt> and <tt>imagemagick</tt>.

== step ?: 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.

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

:<nowiki>http://<hostname>/wiki/</nowiki>

Note 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. (This is necessary to enable clean URLs, which we'll address 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 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 <tt>/usr/share/mediawiki/</tt>, 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: 

*<tt>LocalSettings.php</tt> is a per-wiki configuration file.  You need a separate version of this file for each wiki instance.  We'll create this file later.
*<tt>AdminSettings.php</tt> is another configuration file. It was used by older MediaWiki installations but is now deprecated. Nuke it.
*<tt>images</tt> 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.
*<tt>config</tt> 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 <tt>ls -al</tt>) 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/

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

[[Image:MediaWiki before initialization.png|frame|center]]

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 separate wiki user for this wiki instance.  The folder 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.

Answer all the necessary questions and 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 <tt>/var/lib/mediawiki/config/LocalSettings.php</tt> to /etc/mediawiki, then follow this link to your wiki.
:You should change file permissions for <tt>LocalSettings.php</tt> 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, <tt>LocalSettings.php</tt>, 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 ?: Isolate database credentials. ==

touch DatabaseSettings.php
chmod 640 DatabaseSettings.php
sudo chgrp www-data DatabaseSettings.php

Copy stuff.

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 <tt>ls -l</tt> 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 <tt>LocalSettings.php</tt> file in your favorite text editor and append, to the bottom, the following lines:

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

The first variable, <tt>$wgUploadDirectory</tt>, 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, <tt>$wgUploadPath</tt>, 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 <tt>$wgEnableUploads</tt> variable -- it should already be defined in the file -- and set it to <tt>true</tt>.

$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 <tt>LocalSettings.php</tt>:

$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 <tt>/wiki</tt> as a request for <tt>/wiki-scripts/index.php</tt>. 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

{<nowiki/>{SITENAME}}

Delete Main page

== step ?: Fix the sidebar. ==

MediaWiki:Sidebar / create

== step ?: other configs ==

<pre>
# 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;
</pre>

== 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!

Sharkysoft Wiki - Recent changes [en]

how to create the perfect MediaWiki wiki