Updating MediaWiki

The MediaWiki project provides an official wiki page which explains the procedure to update a wiki. Unfortunately, their instructions are complex, and the page contains a lot of information that is outdated or irrelevant for our users. To make it easier for our users to update, this documentation page aims to be more accessible and easier to understand. However, this page is not an authoritative source on the subject. If the instructions on this page are unclear at any point, you should always refer back to the official instructions.

Downloading the latest version

To start updating MediaWiki, you will need to download the version you want to update to. A table of all recent MediaWiki versions can be found on the the official page. In this table, currently supported versions are in bold.

If you arrived at this page after receiving an email from our Software Version Checker. This email might contain a line similar to:

- MediaWiki in <path>. Installed version: <version1>. Latest version: <version2>.

This line tells you where the MediaWiki installation is located, its current version, and the version you need to download.

If you don't have an email from our Software Version Checker, you can simply choose any supported (bold) version you want to update to.

Click on the link of the newer version. This will redirect you to a page with information about this version. The first paragraph on this page contains a link to mediawiki-xxx.tar.gz. Download this file and save it somewhere on your PC.

Making a backup

An important step in the update process is to create a backup of your data on the ULYSSIS server, to prevent data loss if something goes wrong. The backup step consists of roughly two parts:

• Creating a backup of your wiki database. If you use MySQL or PostgreSQL, you can follow the instructions on Making Backups#A backup of your databases. If you use SQLite, please refer to the official instructions. If you are not sure about your database type or the name of your wiki database, you can search the LocalSettings.php configuration file for the following lines:

## Database settings
$wgDBtype           = "<db_type>";
$wgDBserver         = "<db_server>";
$wgDBname           = "<db_name>";
$wgDBuser           = "<user>";
$wgDBpassword       = "<password>";

• Creating a backup of your wiki files. The easiest way to do this is to rename the directory containing your LocalSettings.php configuration file (your wiki location) to a new directory. If you don't know how to access your files on your ULYSSIS account, refer to Accessing your files for easy instructions. For example, if LocalSettings.php is stored in www/wiki, you should rename this directory to www/wiki_backup, or something similar.

Installing the new files

Now, you will need to extract the zip file you downloaded in step 1. This should result in a directory which looks something like:

mediawiki-xxx/
├── cache/
├── docs/
├── ...
├── api.php
├── autoload.php
└── ...

Rename this directory to the original name of your wiki directory on your ULYSSIS account. For example, if your wiki was located at www/wiki, rename this directory from mediawiki-xxx to wiki.

Next, you should upload this directory to your ULYSSIS account, to the original location of your wiki. If you followed step 2 correctly, the old files should be moved to a backup directory. As a result, after uploading, your ULYSSIS acocunt should contain the new files in something like www/wiki, and the old files in www/wiki_backup. Please refer to Accessing your files if you don't know how to upload files. Because MediaWiki contains a lot of (small) files, this might take a long time, up to 15 minutes.

Finally, you need to copy the configuration files and other files or directories you modified from the old directory to the new directory. Although only you know exactly which files these are, here are some suggestions from the official instructions:

• LocalSettings.php, which contains your old configuration settings.
• The directory containing the uploaded files to the wiki. Most likely, this is images/, unless you set the value $wgUploadDirectory in LocalSettings.php
• In case you use a custom logo or favicon, this file also needs to be restored from backup. You can find the locations of these files by checking the $wgLogo and $wgFavicon values in LocalSettings.php.
• Custom extensions from within the extensions/ directory. Be careful not to overwrite the default extensions that are bundled with the new MediaWiki version.
• Custom skins from within the skins/ directory. Be careful not to overwrite the default skins that are bundled with the new MediaWiki version.
• Any modifications made to the old installation files, extensions, or skins. For example, this includes miscellaneous modifications to the configuration of extensions or skins.
• Any .htaccess file, if present.

Updating extensions

If you use any extensions that are not bundled with MediaWiki by default, you should update them too. As the installation instructions for each extension are different for each extension, this page can't help you with this process. However, most extensions follow the same template as the MediaWiki upgrade itself:

• Downloading the latest version: make sure to download the correct update for your new MediaWiki version.
• Making a backup of the extension: you should already have a backup in the directory you created in step 2.
• Extracting the files: similar to the MediaWiki zip files, you might have to copy the new extension files to a directory in the new extension/ directory.

Finalizing the update

The final step in the update process is to update the database structure of your wiki. The MediaWiki developers were kind enough to create a script, called update.php. Unfortunately, this script must be executed using the command line. If you are not familiar with the command line or SSH, please read Accessing shell servers over SSH first.

After connecting to your account using SSH, navigate to the directory containing your new wiki installation. For example, if your wiki is located at www/wiki, execute:

cd ~/www/wiki

This directory should contain all your wiki files, such as LocalSettings.php. Now, navigate to the maintenance/ directory:

cd maintenance

This directory contains the update.php file. To run this script, execute:

php update.php

The script will first display a 5 second countdown to execution, just in case you want to abort. After the countdown, you should not interrupt the execution of the script. If everything went well, you should see a lot of text, ending with:

Done in x s.

Congratulations! You successfully updated MediaWiki. Still, there are two more important steps you must perform:

• Test your new MediaWiki installation: make sure all basic functionality (viewing, editing pages, file upload) works and all your extensions function properly.
• Delete the backup installation: for example, if your backup is stored in www/wiki_backup, you can remove it using the command line or through a GUI. A simple GUI explanation can be found on Accessing your files.

However, if you did encounter any errors while executing the script, you could try taking a look at the official instructions. If this does not resolve your problems, feel free to send us an email. We will try to assist you in completing the update.