Upgrading MediaWiki version

[FlyingRagnar]

Just did a quick check and I'm pleasantly surprised to see that at least half of the NIWA wikis are using the most recent version of MediaWiki (1.21.2).  The other half range from being a minor version behind to several version behind (WarsWiki is 1.16.0). 

Upgrading is something I have come to dread, especially when there are database schema updates.  Everything is fine if there are no errors, but there always seem to be some errors and fixing them always seems painful to me.  Another annoyance is that due to being on cheaper webhosting, the Dragon Quest Wiki host kills any process that runs on the shared server for a lengthy amount of time.  This can kill the upgrade process, or at least make it fairly difficult.

I would love to see info like this posted on this forum.  There have been hardly any posts in here.  Sharing details of how an upgrade went, what went wrong, etc. would be really useful to compare with others.  Also, sharing information on new extensions you install and why, extensions you've removed and why, etc would be really useful.  Across NIWA, we are using a whole lot of variety when it comes to how each wiki is installed and configured.  I know I could benefit a lot from seeing what others are doing.

[Moydow]

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:
• cd ~/public_html
• git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git
• cd core
• git checkout <current version number, e.g. 1.21.2>
• 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:

Code Select Expand

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.

[FlyingRagnar]

Thanks for the full list Moydow.  I didn't see this post until now, but earlier tonight I upgraded the Dragon Quest wiki to 1.21.2 from 1.18.0.  It went easier than I thought it might be.  Looking at your install process, I was did pretty much the same steps.  Good to know I am on the right track!

A couple notes I had:
1. This was the first time I unpacked the new version to a new directory instead of on top of the old.  It went really well. 
2. I had to update the path to my image temp directory in LocalSettings.  Thumbnails weren't being generated correctly at first.
3. I tried using the web installer, but it didn't go well, which wasn't unexpected.  Using SSH, I found that the default php version was non-compatible with Mediawiki 1.21.2.  Fortunately, hostgator has other versions installed on the server, just not as the default.  So I was able to run the upgrade manually by specifying the run location for php.
4. I took the opportunity to weed out some old extensions we don't need and to make sure I had the current versions for the ones we are using.  Looks like the EmbedVideo extension doesn't work with 1.21.2, so I'll have to find something else to embed videos with.  I got that one originally from seeing it used on Metroid Wiki...which is still using it with 1.21.2.  I'll have to go see if it still works there or not.  The extension page says it is only compatible up to 1.20.something.
5. My .htaccess is fairly complex because the Dragon Quest Wiki is the combination of several previous forms which had different URLs.  I have rewrite rules for them all to make sure legacy links still work.  Eventually I'll probably take those rules out. 

[Greenpickle]

Following that, wouldn't you end up with .git/ in your w/ (and possible .gitignore or .gitattributes in places)?

[Justin]

@Greenpickle: Yes, that will leave the .git files. Which isn't really that much of a pain.

But I've found that the best way to upgrade is with the shell. It can be done completely painlessly, and the switch can take only seconds.

For starters, upload the new wiki files and put them in a directory named something like new_wiki. Next, create an exact copy of your LocalSettings.php, and add this at the bottom:
$wgReadOnly= "We are currently updating our MediaWiki version and have therefore disabled editing. Please check back in a few minutes!";

Then, make a shell script! It'll look something like this:

Code Select Expand

#!/bin/bash
#MediaWiki upgrade script

#Start by copying the images from the old version to the new
cp -r /var/www/wiki/images/ /var/www/new_wiki/

#Next, backup LocalSettings.php
cp /var/www/wiki/LocalSettings.php /var/www/wiki/LocalSettings.bak

#Then put the new file over the current LocalSettings
mv -f /var/www/wiki/NewLocalSettings.php /var/www/wiki/LocalSettings.php

#We'll also give the new wiki directory a copy of our LocalSettings and .htaccess (if applicable)
cp /var/www/wiki/LocalSettings.php /var/www/new_wiki/LocalSettings.php
cp /var/www/wiki/.htaccess /path/to/new_wiki/.htaccess

#Now, we're going to rename the wiki directory (to save the old files in case something goes horribly wrong)
mv /var/www/wiki/ /var/www/old_wiki/

#And then put the new files in place.
mv /var/www/new_wiki/ /var/www/wiki/

#Run the database update
php /var/www/wiki/maintenance/update.php

#Unlock the database
mv -f /var/www/old_wiki/LocalSettings.bak /var/www/wiki/LocalSettings.php

This is for a Linux server, of course. And the paths may differ. I just used /var/www/ as an example. If your server has multiple sites, your wiki is probably stored in a home directory of a user, like /home/xwiki/public_html/wiki/

Anyways, the script looks like it does a lot (and it does), but there is literally no quicker way to do something than with a shell script. It enters commands to the machine immediately, so when it finishes one operation, it quickly moves on to the next. Without a doubt the best way to minimize downtime. Hope this helps!

[FlyingRagnar]

I didn't use git to retrieve the new version of Mediawiki.  I downloaded the zip and then uploaded it to the server.  I know using git could make it one step simpler, but either way works.

Also, I assume you are then manuallying updating your extensions in the newly installed version?  Your script could obviously just copy the extensions directory over, but that's probably not a best practice since some of the extensions may not be compatible with the new Mediawiki version. 

I was able to get the EmbedVideo extension working with 1.21.2, even though it doesn't state on the extension page that it is fully supported in this version.  Seems to be working ok.  I also installed the Mobile Frontend extension, which is what Wikipedia uses for a mobile browser skin.  It sounds like Mediawiki will eventually integrate a mobile skin directly, but for now the extension works pretty well.  I'll have check out the other NIWA wikis to see how folks are handling mobile visitors.

[FlyingRagnar]

Anyone have any tips for configuring the WikiEditor extension?  It was working pre-upgrade to 1.21.2, but is not now.  I seem to remember in the past that it has been very flaky.  The extension talk page seems to confirm that, as it is full of hacks and work arounds to get it working.