My method for upgrading usually goes like this (for major version upgrades, e.g. 1.20 to 1.21):
- Upload the new version files into /public_html/w2/ (this assumes that your wiki is in /public_html/w/ or similar; if not, it gets a bit tricky. If the wiki is in /public_html/, you should move it to /public_html/w/ (see below)).
- If you have shell access (via an SSH client such as PuTTY), you can probably use Git to download the files directly to the server, cutting out downloading the files to your computer, and uploading them manually. In the SSH client, enter these commands:
- Set the current wiki to read-only mode.
- Enter the following in LocalSettings.php:
- $wgReadOnly = "Upgrading MediaWiki";
- Backup the database.
- If you have cPanel, go to phpMyAdmin, and login using the database username and password (can be found in LocalSettings.php. If your MediaWiki version is older than 1.16, they're in AdminSettings.php, which will become redundant after upgrading)
- In the left-hand sidebar, go to:
- your wiki's database -> Export -> select the Quick method, and SQL format -> Go
- This will download the database to your computer.
- Go to /w2/ (or /core/ if you used Git), and delete the /extensions/ and /images/ directories.
- Copy LocalSettings.php and the /extensions/ directory to /w2/ (or /core/ if you used Git).
- Log in to your SSH client, and run the update script (it's also possible to do this through your browser, though it's not recommended unless you have absolutely no way of getting shell access)
- cd ~/public_html/w2/maintenance
- php update.php
- Move the /images/ directory to /w2/ (copying will probably take too long).
- If you have a custom skin installed, move the files for that to the /skins/ directory of /w2/. This includes the directory containing the skin files, and the <skin>.php file. <skin>.deps.php files are no longer needed as of MediaWiki 1.18.
- Rename /w/ to /w.old/
- Rename /w2/ (or /core/, if you used Git) to /w/
- Check the wiki to make sure it's working. If not, the most common problems are:
- An extension (or extensions) are incompatible with the new version of MediaWiki. If the error message gives any details, you should be able to use that to find the broken extension, and disable it (just comment out the require_once line that calls it). If not, you'll need to disable all extensions, and re-enable them one-by-one until you find the culprit. Update the broken extension(s) to the newest version available.
- Some extensions will still complain about calling the wfLoadExtensionMessages function, even after updating them - just delete any lines containing this from the given file.
- A custom skin is incompatible. If upgrading from a pre-1.19 version, this is especially likely, due to multiple changes in how MediaWiki handles skins.
- Configuration changes have rendered certain lines in your LocalSettings.php file obsolete/broken. The older your previous version was, the more likely this is. Check the release notes for more details. If upgrading from a pre-1.16 version, copy the $wgDBadminuser and $wgDBadminpassword lines from AdminSettings.php to LocalSettings.php.
- Downloading from Git sometimes causes file permissions errors. Use the following commands in SSH to rectify this:
- cd ~/public_html/w
- chmod 644 index.php
- chmod 644 load.php
- chmod 644 api.php
- chmod 644 opensearch_desc.php
- Check the list of extensions on Special:Version for updates. If there are any updated versions available, or the extension is listed as having "continuous updates", you should update the extension straight away.
- Unset read-only mode (comment out $wgReadOnly = "Upgrading MediaWiki";)
- Perform some basic tests to ensure everything works as it should (editing, uploading images, etc.)
For minor upgrades (e.g. 1.21.1 to 1.21.2), just upload the new files to the server, overwriting the current files. It's a good idea to set the wiki to read-only first. Database backups and running update.php are not necessary, as minor upgrades don't include database schema changes (though it's a good idea to make database backups regularly in some form, even just saving them to the server). You should ideally also check for extension updates, though they're less likely to break between minor versions.
If you
really need to run the update script through the web browser, go to the /mw-config/ directory (e.g.
http://example.org/w/mw-config/) and follow the instructions. If asked for the upgrade key, this is the contents of
$wgUpgradeKey, found in LocalSettings.php.
If the wiki is located in /public_html/ instead of /public_html/w/, you should move it to /w/ first (and leave it there, it makes the upgrading process easier in future):
- Create the /w/ directory under /public_html/
- Move the wiki files into /w/
- In LocalSettings.php, set:
- $wgScriptPath = "/w";
- $wgArticlePath = "/wiki/$1";
- In .htaccess:
RewriteEngine on
RewriteRule ^/?wiki(/.*)?$ %{DOCUMENT_ROOT}/w/index.php [L]
RewriteRule ^/*$ %{DOCUMENT_ROOT}/w/index.php [L]
Then you can follow the upgrading process as normal.