Manual:Running MediaWiki on Debian or Ubuntu

This guide is to help other users manually install MediaWiki on an Ubuntu server installation using primarily Terminal commands.

Manual setup can be difficult and time consuming for some users. Users that want to get MediaWiki running on Ubuntu and prefer to skip manual installation may consider using TurnKey MediaWiki, a third party software appliance based on Ubuntu 8.04.1 (Hardy).

For manual installation, some PC knowledge is required (ie: installing applications), a bit about Operating Systems, and use of a text editor (like gedit, nano, emacs, or vi (see vi in 10 minutes to get started)).

To install MediaWiki on an Ubuntu Desktop Edition primarily via the Gnome Desktop and Synaptic Package Manager, see this page. For Ubuntu 10.04 and later, see this page.

Step-By-Step
Ubuntu server edition comes with Apache, PHP, and MySQL installed and configured. During the installation step, make sure you choose to install a LAMP server. Alternately, you can install all four of these packages from a normal Ubuntu installation using these commands:

sudo aptitude install apache2 mysql-server php5 php5-mysql mediawiki

Also double check that Ubuntu is up-to-date by running:

sudo aptitude update && sudo aptitude safe-upgrade && sudo aptitude dist-upgrade

'' warning: the 'dist-upgrade' will upgrade your entire distribution to the next number (9.04->9.10), replacing hundreds of packages. is not strictly necessary and may cause problems with your system. google for dist-upgrade disaster or dist-upgrade fail for examples ''

If you want to run PHP commands from the command line which is useful for debugging and running maintenance scripts, install PHP-cli like this:

sudo aptitude install php5-cli

If you want to use the GD library (instead of ImageMagick for image resizing)

sudo aptitude install libgd2-xpm libgd2-xpm-dev php5-gd

Configure MySQL
This step is not necessary if you were prompted to create a mysql root password during MySQL installation.

First, set up a mysql root password. Remember not to use same password for system root and mysql root. This will also clear your command history so that other users cannot get to your password...

mysqladmin -u root password "" history -c

Note: Remember this user (root) and password because you will need them when you configure MediaWiki.

Configure PHP
''These steps are optional. You can skip them entirely (or do them later) and MediaWiki should still work.''

Edit your php configuration file. It will be located somewhere like  or   or maybe

sudo gedit /etc/php5/apache2/php.ini

Maximum Upload Filesize
Assuming that various files are going to be uploaded to the Wiki as content, the limit on the maximum size of an upload has to be adjusted. About one-half way down is the File Uploads section. Change: upload_max_filesize = 2M to at least 8M. You may have to adjust this again in the future. upload_max_filesize = 8M

Memory Limit
Some PHP scripts require a lot of memory to run. To increase the maximum amount of memory a script can use, page down to about 21%, and change the following entry, if found, from memory_limit = 8M to memory_limit = 32M If it is already 32M or more, leave it as is.

Extensions
Under Ubuntu 9.04 and 9.10 this section is unnecessary.

PHP MySQL support has to be enabled. Page down a bit further (about 48%) and make sure the following line is uncommented: extension=mysql.so

If you use the GD graphics library to do image resizing (instead of ImageMagick), also uncomment: extension=gd.so

Save and exit out of the editor and restart Apache: sudo apache2ctl restart

Configure MediaWiki
Edit apache.conf file at /etc/mediawiki/apache.conf sudo gedit /etc/mediawiki/apache.conf and uncomment this line: Alias /mediawiki /var/lib/mediawiki

Save and exit out of the editor and restart Apache: sudo apache2ctl restart

Navigate your browser to http://localhost/mediawiki, to http://localhost/mediawiki/config or to http://wiki.hostname.com/config and continue with the installation.

Pay close attention for "Checking environment..." in MediaWiki installation script. This can solve a lot of problems for your MediaWiki successful installation by specifically identifying the source of any errors. Fill out the configuration form and continue.

Under Database Config, you may change the database name and DB username to new values, but you must turn on "Use superuser account", name root, giving the mysql root password you configured earlier Configure MySQL, above.

Once configuration is done you'll need to move the created LocalSettings.php to the parent directory. The configuration page will have the exact directory/filename that must be moved: sudo chmod a+rwx /var/lib/mediawiki/config sudo mv /var/lib/mediawiki/config/LocalSettings.php /etc/mediawiki For added safety you can then remove the config subdirectory entirely: sudo mv config/LocalSettings.php. sudo rm -rf config

And navigate your browser to http://server_ip_address/wiki or to http://server_ip_address/wiki/index.php to see your new wiki. Possibly server_ip_address = localhost, so http://localhost/wiki may work.

Done! You now have a working Wiki

General Information
Under Ubuntu 9.04 and 9.10, MediaWiki is installed at /usr/share/mediawiki. However, configuration/customizations are actually installed in /var/lib/mediawiki.

Confusingly, links are created in both locations so all files appear to be in both places.

Additional Wiki Configuration
The Wiki is configured by the LocalSettings.php file, usually found in /var/www/wiki. Manual:LocalSettings.php has detailed information that may be useful. The following are changes that appear to be universally helpful

To edit LocalSettings.php use sudo gedit /etc/mediawiki/LocalSettings.php

Enable Uploads
By default, the Wiki will not permit images to be uploaded. To change this find $wgEnableUploads and change it from false to true.

Specifying Uploadable Filetypes
You may want to modify the list of accepted extensions, which is stored within the $wgFileExtensions array. By default you will not be able to upload PDF files, for example, without making this change.

If $wgFileExtensions is not already in LocalSettings.php add it at the end (before the ?> line, if one exists in your LocalSettings.php file):

Images Uploads
The images directory must be writeable: sudo chmod a+w /var/www/wiki/images

Note: for Ubuntu 9.04 the command is: sudo chmod a+w /var/lib/mediawiki/images


 * I just did a clean install into Ubuntu 8.04 LTS, and making the images directory writable was not required in order for image uploading to work. Seems like this step is superfluous and a little dangerous. --Mark 16:59, 22 September 2009 (UTC)


 * I just did a clean install into Ubuntu 8.04.3 LTS, and making the images directory writeable was required to get SVG graphics to work. I don't see how it is dangerous to allow the WWW user to write to the images folder (?).


 * WWW user, maybe not. Making the entire thing writeable by all, as shown here, is a different matter..


 * if the WWW user could write the image folder, a bug could allow to a malicious user to upload an exploit into the server and execute it trough the web. Always is a good idea restrict the WWW user permissions's at the minimum necessary.

Enable Thumbnails
The |thumb option added to an image: tag will automatically generate a thumbnail version of a picture - if support has been enabled, as follows:

sudo aptitude install imagemagick
 * The ImageMagick package must be installed:


 * In LocalSettings.php, make sure the following settings are in place and not commented out. They are normally about 80 lines down in the file marked "To enable image uploads":

Changing The Logo
The $wgLogo variable specifies the the graphical logo that gets displayed on the top left corner by default. The variable $wgScriptPath contains the top directory of the wiki - in this case /var/www/wiki. The logo image is supposed to be 135x135 pixels; if it is oversized it will show the top left corner that fits. (This variable is not present in LocalSettings.php by default, you need to add in manually to the bottom.)

Caution: Do not simply overwrite the default logo installed with MediaWiki (/skins/common/images/wiki.png); this file will be overwritten when you upgrade.

Mediawiki Extensions
There are several standard Mediawiki extensions available from the ubuntu 9.04 package system (namely, the package named 'mediawiki-extensions').

Let's take the ParserFunctions extension for an example. To install ParserFunctions follow this:

sudo apt-get install mediawiki-extensions sudo mwenext ParserFunctions.php

Once you enable it, it should be listed as a symbolic link in /etc/mediawiki-extensions/extensions-enabled. You should now be able to go to http://localhost/mediawiki/index.php/Special:Version and see ParserFunctions listed there as an installed extension to your mediawiki.

A list of the other 'standard' extensions ubuntu comes with can be found by just running this command:

ls /etc/mediawiki-extensions/extensions-available

Also you might have to do a 'null edit' of a page if you first visisted it when your extension wasn't enabled. Otherwise it might load from the cache and not get parsed properly. (Please see http://en.wikipedia.org/wiki/Null_edit for more info)

Extensions from Tarballs
this section tested with ubuntu 9.04 and 10.04, but should proably work similarly on other versions 

Some mediawiki extensions that are not available in the ubuntu package system can instead be gotten in tarball (tar.gz) format and installed 'manually'. Basically, you download the tarball, unpack it to the 'extensions' directory (on ubuntu: '/var/lib/mediawiki/extensions'), edit your 'LocalSettings.php' (ubuntu: /etc/mediawiki/LocalSettings.php), and then go to http://localhost/mediawiki/index.php/Special:Version to verify that it worked.

A good list of extensions is available here:  Category:Extensions in Wikimedia version control 

For an example, let's take the relatively simple extension called MiniDonation. This extension lets you put a &lt;donationform&gt; tag in your wiki code, and it will display a link to paypal on the page. The site for MiniDonation is here: http://www.mediawiki.org/wiki/Extension:MiniDonation

Just follow the instructions on the page: download the tarball (in firefox it will probably end up in ~/Desktop), then do a cd /var/lib/mediawiki/extensions sudo tar -zxvf ~/Desktop/MiniDonation sudo gedit /etc/mediawiki/LocalSettings.php

Then check http://localhost/mediawiki/index.php/Special:Version, it should list MiniDonation there. Now edit a wikipage and add a &lt;donationform&gt; tag to it... save the page and you should have a nice little paypal button on the screen.

 Replacing extensions that are in ubuntu's mediawiki-extensions package with newer versions 

You can also 'upgrade' one of the 'standard' ubuntu mediawiki extensions (such as Cite.php) to a newer version if you need to. The important part is to remember to run 'mwdisext ExtensionName.php' to disabled it before you install the new version into /var/lib/mediawiki/extensions.

The pitfall is that some versions of extension will not work with certain other versions of Mediawiki (or with other versions of other extensions that they depend on). In this case you can get a 'fatal error' when you try to pull up certain mediawiki pages (including even when pulling the 'Special:Version' page). Or it might just give you a blank page, in which case you can look at /var/log/apache2/errors.log for a hint as to what is wrong.

Shorter url
If you want /wiki/* instead of /wiki/index.php/* on Ubuntu, follow the recommended short URL guide, with these addenda not found anywhere else:

Use $wgScriptPath = '/mediawiki';

Instead of '/w' in LocalSettings.php.

Then use these aliases in /etc/apache2/conf.d/mediawiki.conf: Alias /wiki /var/lib/mediawiki/index.php Alias /mediawiki /var/lib/mediawiki