MediaWiki/Guide/Upgrade
A Guide to Installing MediaWiki in a Hosted Environment
This article is part of a series compiled as a guide to encourage and assist those building a MediaWiki-based website in a hosted environment.
Each article links to relevant documentation from the MediaWiki.org website and the Wikimedia.org website. Where the official documentation does not adequately cover the issues for a hosted site, or is too 'advanced', additional information, explanation and advice is provided.
Challenges when updating a hosted MediaWiki site
Most web hosting service providers will offer a utility which will update your installation of MediaWiki. Even if that will work for you there are steps you should take before running it. And you really only have two options anyway, either:
- use the utility or script provided; or
- do the upgrade yourself, in manual steps.
You need to know what the utility should do, what to do before running it, and what to do if it doesn't work properly, so you may as well take charge and do the upgrade yourself anyway.
The first challenge encountered when doing the upgrade is that the Manual:Upgrading is not sufficiently relevant to guide you through an upgrade when you do not have access to the server, or the command-line, and consequently cannot perform a database backup, or run the update script as described. Nor is the section on using a web updater adequate when that seems to be your only option.
The following sections provide solutions to the various challenges and the method both is based on official documentation and used to upgrade my own MediaWiki sites.
1. Prepare for the upgrade
These are the minimum steps you should take when preparing to upgrade MediaWiki.
- Read the Manual
- Please read through this entire page, the guide to Using mw-config, and refer to the linked Manuals.
- Check the requirements for the new version
- The Compatibility resource from MediaWiki.org indicates the php version and the database, usually MySQL, version required for each release of MediaWiki. Check that your hosting provider actually has compatible versions of php and MySQL.
- Check the compatibility of each Extension and Skin currently installed
- If you depend on certain extensions, or are committed to a particular skin, and they have not yet been updated then consider the timing of your update. Perhaps it can be deferred. An installation will work indefinitely, but you should keep up with at least each Long Term Support version. See the Version Lifecycle for details.
- Make a Backup
- Most hosting providers will have a utility which will backup your entire website, or backup a selected directory or database. If you choose to backup the entire website that should include the database.
- Make a copy of all the files in the installation directory /w
- If you make your own copy of all your files it will be possible to restore any customized configuration; read the (old) LocalSettings.php file; and refer to any other custom settings.
- Find the Upgrade Key
- The Upgrade Key is in the LocalSettings.php file and will be required to run the configuration script mw-config.
- Download MediaWiki
- When you install MediaWiki in a hosted environment the service provider generally has the software available to install; and for an upgrade managed by a script the service provider will have a version of MediaWiki available. But for a manual upgrade you need to supply your own copy so you will need to Download from MediaWiki.org to a local computer.
- Extract the files
- MediaWiki is usually supplied in a compressed format .tar.gz. Windows probably can't extract the files so use a utility like 7-zip.
- Read the Release Notes
- Check for anything not covered here; each version of MediaWiki has introduced new ways of doing things; and confirm that you are ready to proceed.
- Go Offline
- If you deliberately choose to disable your website or go offline, via your host provider's interface, then anyone browsing to the site will get a proper message, like 'this site is currently undergoing maintenance' or similar. That is better than a 'not found' error message.
Manuals and Links
Manual:Upgrading
Compatibility
Version lifecycle
Download from MediaWiki.org
2. Replace the files in /w
This is a radical step so think about it first!
The steps below are provided as a guide only. Have a practice run with a test installation first so you can improve this list for your own situation. Despite the warnings however, this is the process used to upgrade the Mediawiki installation used for this Site. When upgrading from version 1.29 the hosting provider first moved my subscription to a different server just so that the PHP and MySQL requirements could be met; but the version of Plesk installed for customers using that server did not include a set of installable software. Consequently an automated upgrade path was not available. This manual process was refined when upgrading from version 1.29, first to 1.31 which is a Long Term Support version, and then to 1.34 which is a stable version. During on of those upgrades mw-config failed to finish and the complete site had to be restored from a backup. The advantage of this process though is that you, the administrator, are in full control.
- Check that you have 1) a site backup, and 2) a copy of all the website files - the entire contents of the /w directory.
- Download the new version of Mediawiki to your local computer and unpack the .tar.gz files so you have a set of files which can be uploaded to your remote site.
- Download compatible versions of extensions and skins used by your site, to your local computer, and unpack these files ready for upload via FTP.
- Use an FTP utility to upload the new Mediawiki files to a directory on the remote server. For example, you could transfer files by FTP to a folder named UploadedFiles outside of the website, from where they can be copied or moved to other folders such as /w or /w/extensions or /w/skins.
- Use FTP to also upload the extensions and skin(s) used by your site. Note that an increasing number of extensions are packaged with Mediawiki, so this step may not be necessary.
Delete the contents of your installation directory which should be /w
A safer option is to- rename /w to something meaningful, like /w_old, and then
- create a new directory /w which will hold the new version
- Copy the new MediaWiki files into the /w directory.
- Update or restore directories containing custom extensions and skins, using files which you uploaded, or from /w_old/extensions.
- Copy your original LocalSettings.php file from /w_old to /w.
A LocalSettings.php file is created when Mediawiki is installed, but when upgrading from an older version you need to have a LocalSettings file in the /w directory before running mw-config AND that file must already have your site settings, database settings etc. So use a copy of the previous version. - In LocalSettings.php update the syntax used for loading extensions, including those now packaged with Mediawiki. Since Mediawiki version 1.25 most extensions are loaded using the newer method eg. wfLoadExtension( 'WikiEditor' );
- If you have image files in /w_old/images then delete the new (almost empty) directory /w/images and copy the /w-old/images directory to /w.
You are now ready to run the MediaWiki configuration script mw-config. See the next section.
3. Run the MediaWiki configuration script mw-config
When upgrading MediaWiki it is likely that the database structure also needs to be updated. This task is performed by the supplied configuration script mw-config.
Although the Manual seems focused on a new installation it is completely relevant. Think of an upgrade of MediaWiki as a new installation which uses your old database - but the database structure has to be updated so it is compatible with the new MediaWiki version. So mw-config does that job for you.
There is a warning, however - if your database is very large do not use mw-config via a web browser because it may time-out. Refer to the Manual:Config script for details.
If your internet connection is good, and your database is not too large, then follow the instructions for using the Config Script mw-config through a web browser which forms part of this Guide. These instructions are based on the Manual:Config script. and tailored to a hosted environment.
4. Problems and Solutions
- mw-config starts but various error messages occur
- This can happen if there is a problem with extensions, either incompatible with the current version or called using outdated syntax.
Solution: Edit LocalSettings.php and (temporarily) disable various extensions until mw-config runs properly. - mw-config starts but never completes
- The upgrade to the database tables may have started but if the upgrade did not finish, timed-out or was interrupted, then it will be unstable and probably unusable.
Solution: abandon the upgrade and restore the site from the backup. Confirm that the site works as previous and start again, perhaps refining the process. Choose the time of day for an upgrade to ensure that your Internet speed is highest and the load on the host provider's server is lowest. - The upgrade was successful but the site looks different
- Did you customise the skin by editing a skin css file? The changes will not have been carried over to the new version.
Solution: On this occasion, refer to the skin css file in your backup /w_old/skins, find the changes you made (they were commented?) and repeat the process in the new version.
A longer term, and better solution is to use store the css in the relevant skin page in the Mediawiki Namespace. Initially it won't be visible but, for example, a page named Mediawiki:Vector.css may already exist. You just have to search for it and then edit it. - The upgrade was successful but when attempting to edit Mediawiki:Common.css there is no Edit tab
- If the WikiEditor has an Edit tab for other pages and other namespaces then the issue is User Rights which were changed in Mediawiki version 1.32.
Solution: Open Special pages and then the User Rights page for the affected user. If the interface administrator box is unchecked then select it and the user will be able to edit Common.css and also any skin css page on the site. Not that this may not be desirable, which is why the rights were separated in version 1.32. - The upgrade was successful and the site does not have a logo or other images are not displayed
- Images are stored in the /w/images directory. If a new version of Mediawiki is copied to the /w directory then the new /w/images directory will only contain a couple of files by default.
Solution: Copy images from your backup in /w_old/images, or copy the complete folder to the new /w. However, before the folder will copy successfully you may need to delete the new, almost empty, /images folder.
Hopefully the above information is helpful. How long does it take to upgrade a Mediawiki installation? In the worst case scenario up to three frustrating days. At best, after taking time to prepare, think it through, and have no problems - maybe 30 minutes. Good luck!
Grant
Disclaimer
The information or advice provided in this Guide is based on, or links to, official documentation for MediaWiki and was accurate when this article was created. However, some variation may occur between versions of MediaWiki; and the specifics of web hosting varies by service provider. Consequently, you should always create an effective backup before making any changes; ensure that you can restore your database and website; read the Release Notes before upgrading; and apply best practices to the management of your website. Any action that you take based on information provided here is at your own risk and the author accepts no liability for any loss or damage.
