MediaWiki/Guide/Config Script mw-config

A Guide to using the MediaWiki configuration script mw-config

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.

mw-config.php is a configuration script supplied with MediaWiki which should be run when you install MediaWiki, and must be run when you upgrade MediaWiki.

• In a hosted environment the installation process for MediaWiki is generally managed by a script provided by the host provider. This script may be mw-config. If you choose to run mw-config after the installation is complete it won't do much but it will check that the database structure matches the current MediaWiki version.
• If you upgrade MediaWiki to a newer version you must run mw-config to ensure that the database is rebuilt, so that the database structure matches the new MediaWiki version.

Steps required before running mw-config

1. If your MediaWiki database is large, as can occur in a production environment, you may have a problem with using mw-config through a web browser because it may timeout. Before you start using mw-config through a web browser see the section below for Problems and Prevention.
2. Make a backup of your MediaWiki site. The backup must include the database. It is also a good practice to keep a copy of your LocalSettings.php file, any custom settings, and the .htaccess file in a separate location and create a new backup of each of these files before making any changes. mw-config can make changes to your LocalSettings.php file, for example.
3. mw-config requires an Upgrade Key. From your host interface locate the LocalSettings.php file in the /w directory and open it. Look for something like this:-

   # Site upgrade key. Must be set to a string (default provided) to turn on the
   # web installer while LocalSettings.php is in place
   $wgUpgradeKey = "5173453281a5dfcf";
   

   Copy the number between the " " characters.

4. Change the name of .htaccess which is usually located in the root directory of your website. This is temporary - you will need to change the name when you have finished - and prevents the web server from rewriting the page or file name URL so that you can execute the script from a web browser. This will be necessary if you have configured MediaWiki to use short URLs.

Manuals and Links

Manual:Config script

How to run mw-config from a web browser

In your web browser navigate to your own website to using a URL like this:

http://www.mywebsite.net/w/mw-config/

.

If successful, the first page of mw-config will have a request for the Upgrade Key.

Enter the key and select Continue.

mw-config will perform a number of checks and if you Continue, you will reach a screen with a heading Upgrade existing installation.

If you Continue then mw-config will upgrade the database structure so that it is compatible with the current version of MediaWiki. For a new installation this process will be almost instantaneous. However, for an upgrade it may take considerable time. On a hosted site the process may timeout - see the advice in Problems and Prevention, below.

Completion

When mw-config has completed checking the database return to your host interface and restore the .htaccess file to it's correct name.

Check that the MediaWiki site loads in a web browser and operates as intended.

Problems and Prevention

1. mw-config doesn't run: If you get an error message or an empty wiki page, or a page titled Mw-config (with upper-case M) it is likely that the web server is preventing you from running the script because it is executing the re-write rules in the web server configuration file .htaccess. To prevent this from occurring rename .htaccess bfore you start - but remember to change it back again when mw-config has completed.
2. Time-out: the following advice comes from the Manual:Upgrading
   

   If your database is already big and in high production usage, then you should not be using the Web updater, e.g. because the update process will time out when the maximum_execution_time is reached. In that case you should use update.php from the command-line interface (not from the web). What exactly is "too big" depends on your server (e.g. on its performance, the load and on how long the maximum execution time of PHP allows the script to run). If your wiki is too big for the web updater and your hosting provider does not allow command-line access, then you need to migrate your wiki to another hosting account, preferably to one that does have shell access.

3. Database Errors: before performing any maintenance you should ensure that you have a reliable backup. If the mw-config process has timed-out then you will likely need to restore MediaWiki to the previous working version.
4. Short URLs not working after completion: this will occur if the web server cannot acces the .htaccess file. If you renamed it, as suggested, you simply need to restore .htaccess to its original name and location.

Manual:Upgrading

---

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.

---

Open source wiki