Open main menu

Overview

I just upgraded my wiki site, and thought I would write down the steps for further reference. Even though the README, UPGRADE and online help are very detailed, I find it helpful to note my personal preferences, observations, and clarifications where I might not understand the instructions.

The process obviously started with downloading the source from the web. However, since the wikipedia project uses the continuous integration method of development (meaning they always run their own latest code), I decided to join that practice and run off SVN trunk. So, I simply did a svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3 to get the code.

I performed a diff of the entire tree v. my installed copy using the venerable KDiff3 to get an idea of the magnitude of the code changes; to learn by reading some code changes and get a feel for the 'current best practices'. It also helped me to see what old stuff was deprecated, or that I had lying around as cruft on my filesystem. Since it had been a long time since my last upgrade, there was a large delta. I didn't want to or have time to look at all the code improvements so I moved on to the next step.

Consult the release notes

Before doing anything, stop and consult the release notes supplied with the new version of the software. This detail bug fixes, new features and functionality, and any particular points that may need to be noted during the upgrade procedure. There was a lot here, although nothing that impacted the function of my installation.

Backup first

I copied my filesystem as a backup.

I copied my database as a backup. I noticed that phpMyAdmin failed silently to create a backup because it exhausted the PHP memory limit. When I say 'failed silently' I mean that it saved the export as a compressed file on my system without complaining, but the contents of that file were the plain-text error message from PHP. I could have increased the script memory limit, but instead I found that an uncompressed version of the export would work. I also could have used mysqldump or the Mysql Administrator client.

Perform the file upgrade

Having downloaded the desired new version of the software, either as a package from SourceForge, or via an export from Subversion, decompress the files as needed, and replace the existing MediaWiki files with the new.

You should preserve:

  • The LocalSettings.php file
  • The AdminSettings.php file, where it exists
  • The extensions directory
  • The images directory

If using an alternative uploads directory, preserve this; and if using custom skins, preserve these too. The core code is now updated.

I did all of those because I do have an 'accessible' skin. The easy way to do the filesystem upgrade is with the rsync command. Besides the filesystem update, you also need to create a AdminSettings.php file with credentials to access your database.

user@host:/path/to/docroot$ rsync -vrc --delete --stats --progress --exclude images/ --exclude extensions/ --exclude LocalSettings.php --exclude skins/disabled/ mediawiki-1.6.1/ wiki


Perform the database upgrade

You will need an AdminSettings.php file set up in the correct format; see AdminSettings.sample in the wiki root for more information and examples.

From the command line, browse to the maintenance directory and run the update.php script to check and update the schema. This will insert missing tables, update existing tables, and move data around as needed. In most cases, this is successful and nothing further needs to be done.

cd wiki/maintenance/
ls
php -q ./update.php

Check configuration settings

The names of configuration variables, and their default values and purposes, can change between release branches, e.g. $wgDisableUploads in 1.4 is replaced with $wgEnableUploads in later versions. When upgrading, consult the release notes to check for configuration changes which would alter the expected behaviour of MediaWiki.

Change the wiki pointer

In order to quickly upgrade, revert or take the site offline, I simply use a symbolic link and point that to the folder that I want. In order to complete the upgrade, all that was left was to change the target of my wiki symbolic link from phase3_1_7_1 to phase3_1_11

Test

It makes sense to test your wiki immediately following any kind of maintenance procedure, and especially after upgrading; check that page views and edits work normally and that special pages continue to function, etc. and correct errors and quirks which reveal themselves.