Just a note about a day in the life of a geek. This all starts with the fact that I maintain two MediaWiki servers on my hosting plan. One is for my food-related experiments, recipes, and other household cooking and food info. The other is for game-playing.

For a look at the cooking and food wiki, and central to this narrative, have a look at the Local Eats page I’ve started writing up. This page is for my household to track local eateries and attractions, as well as to help out any house guests or house exchange folks who may stay with us or in our house.

I got an alert from my monitors that my MediaWiki was an older, unsupported version. It was 1.24.x. If you look at the MediaWiki Download page, you can confirm this issue with 1.24.x. Given it was the weekend, and my partner was busy with work-related stuff, I jumped into action.

A manual update of MediaWiki isn’t that hard, but you have to be careful in case something goes wrong.

Note also that whenever you update software, it’s best to read the README, or Upgrade guide or read up on the Upgrade process in existing help files, wiki articles, and so on. It’s true that I have a great deal of experience in geekland, but I’m not telepathic. Reading up gave me an opportunity to look for non-standard factors and things that the developers thought I should look out for. I recommend you do the same if you need to do any upgrades. The do-it-and-pray methodology where you just start an upgrade wizard and hope for the best is not the right approach for a professional Geek. Instead, do some research ahead of time, plan it out, prepare (with backups and so on), and then do it. This way you’ll usually only need to do it once.

So my order of approach was:

1. Back up the Wiki’s database to a local drive.
2. Back up the Wiki’s metadata to a local drive.
3. Back up the Wiki’s files to a local drive.
4. Back up the Wiki’s files to a remote file (same server the Wiki’s hosted on). (To a file clone in an entirely different subdirectory.)
5. Download the MediaWiki update.
6. Blank out the existing files in the existing, production site.
7. Extract the update to the existing Wiki file directory
8. Restore old settings files and supporting files to the updated Wiki file directory. (Copy from clone of the old site on the server.)
9. Update the old settings file with updated commands appropriate to new version of MediaWiki.
10. Do database schema upgrade.
11. Make sure updated Wiki is running, make sure version information is correct.
12. Review old versus new extensions and functionality and ensure updated Wiki has updated extensions.
13. Install any new extensions as needed.

Let’s drill down a little into each step. But before we start, let me reassure you: The first update took about 1 hour. The second, about 30 minutes. Because nothing really went wrong, and I have a lot of experience with the kinds of minor annoyances that CAN happen as part of any update process.

As a pre-step, load the Version Page on your pre-update Wiki and leave it open. After you update, you can compare version pages and it’ll help you with Step 12. If you’re worried you’ll close it by accident, take a screenshot and keep it where you can find it.

Anyhow, steps 1-3 were pretty easy.

For Step 1, I used phpMyAdmin to Export a full copy of the database.

For Step 2, I followed easy instructions to export the XML.

For Step 3, I created a compressed copy of the files and then downloaded them locally with an SFTP client.

Steps 4-8 required some UNIX shell commands. I logged into my host with SSH and did them!

Step 4 was mostly to do with the UNIX cp command.

Step 5 recommended the use of the wget command, though I think I must have downloaded the package with my web browser and transferred it with FileZilla.

Step 6: More UNIX (this time the UNIX rm command). (This is optional and paranoid, but before removing all the files, and after Step 4, I decided to use the UNIX diff command to double-check that the copying from Step 4 was complete.)

Step 7: Then I used the UNIX tar command (This is the same link as in step 5, but look for the tar command example.)

Step 8: More UNIX cp commands per the instructions here. This step restores the filesystem-based content and customizations from your old version to the new version.

Step 9 required a UNIX editor (I use vi, but there are other choices that are easier for the inexperienced – vi is kind of baroque – like pico or nano). On the remote host, I went through the old LocalSettings.php file for old commands and converted them to newer commands per these instructions. Be sure, here, not to outright delete old entries, but just comment them out (by inserting a “# ” in front of the lines you want to comment out). You may need them later (see Step 11 for details).

Step 10, as part of many modern architectures, MediaWiki stores most of its data and content in a database, and most of the constant features and navigational elements and look and feel in the file system. So when you update the application, MediaWiki, you have to update both the files and the database. Fortunately, application developers plan for this and provide an automated script to do the database upgrade work, but you still have to run it.

Step 11 is always fraught. Usually you get an error the first time you think you’re ready to go. just be prepared for this. Mostly this is because of third party elements, like extensions and skins, not working as expected. Remember that in Step 9, you revised the settings file with updated commands, primarily to support these third party things. The bad news is that some of these haven’t caught up and don’t work with the new commands as expected. So look carefully at the error messages you get instead of your nice, pretty Wiki interface. They’ll tell you what line in the settings file is failing and what add-on is causing the problem. Most of the time, if you go back into the settings file and use the old method of integrating the add-on, the Wiki will work again. To do that, just move the “# ” commenting string in front of the new command line and remove it from being in front of the old command. After making these changes, save the settings file and try loading the Wiki again. Eventually you’ll get the right settings and be good.

NOTE: Be aware that if you have a lot of older add-ons, they’re less and less likely to work properly with newer versions of MediaWiki. If you have some that simply refuse to work no matter what you do after an upgrade, you may have to say goodbye to them and find alternatives in the more current available set. This can cause plenty of complications, depending on how widespread your use of them is in your Wiki’s content and how many Wiki articles you have to edit to use new, replacement add-ons. In some cases it will be easiest (but admittedly more scary too), after converting to new add-ons, to do a system-wide operation through the database to make these changes (with some functionality rather like search-and-replace) than to manually edit each affected article. This is one of the kinds of major complications I alluded to earlier in this post. Luckily I didn’t run into this, mostly because I wasn’t using any add-ons in the food Wiki. But now that I’m using the Maps extension, I have to be much more careful with future upgrades.

In Step 12, now that your upgraded Wiki is displaying properly, go to its Version Page and compare the readout to the page you loaded at the start of this, before the upgrade. Note that the new Version Page will be different, but focus on sections like “Installed Software” and “Installed Skins”. Note any differences and see if you can get any missing add-ons reinstalled and reactivated in the upgraded Wiki.

You would think that Step 13 would be easy, and the final step to a relatively easy process. But I added a complication that made everything sort of surreally difficult. I wanted to add the MediaWiki’s Extension:Maps to my MediaWiki install. Look again at the Local Eats page and see the maps and how I used them. So let me digress and talk about versions, support, and configuration management.

Configuration management is a sort of a big thing in computing and engineering lately. To most users it’s pretty invisible. Computers are lately “just working” more and more often, and this isn’t just Apple computers any more, but mobile phones, tablets, Windows and UNIX laptops, set-top boxes (for TVs), and so on. A lot of these devices need to “Just Work” because most people in the world don’t know how to and don’t care to learn how to hardwire into the command shell and flash the RAM and rebuild the device from bare metal. These devices come with basic operating systems that must survive basically anything we users throw at them. Part of these modern operating systems’ survival is due to working with some form of configuration management. And this is necessary because with constant automated and semi automated updates for each component of the system, version control becomes nightmarish.

Version control? How’s that? Modern software works with prebuilt libraries. These exist so that modern programmers don’t have to reinvent the programming wheel each time they write something new. Libraries provide basic functions like web operations, math, taking input, displaying output, and so on, and make these functions easy to use. But there isn’t one single library for each function. There are different libraries built by different authors and each library has many versions. So when any software developer builds a new program, they choose one library for each set of functions the application uses and then incorporate these libraries into their programs and applications.

Each computing device, then, has a branching and spreading tree of libraries (also called dependencies) that serve as the basis for how each application functions.

Sounds terrible, doesn’t it? And in the 20th century, it was. One example of these many problems was called “DLL Hell” (in Windows). And there were similar problems with other contemporary operating systems back then.

These days, though, configuration management helps a lot. Because each programmer (including those who program libraries and other add-ons) can now build and maintain automatable lists of dependencies for their product, which can in turn get swept up into higher order packages that use those products.

And that rolls up, eventually, into whatever application you are currently poking at, which is managed in whole or in part by configuration management functions in the operating system. And additionally, configuration management can allow for different versions of the dependencies to run in the same device, with each application pointing to the right ones.

Cool, right? Yes. But not if your MediaWiki and web server and supporting UNIX account are all too far behind, version-wise, to use configuration management tools.

Rewinding to the original story, MediaWiki’s Extension:Maps add-on strongly recommends installing with the Composer tool, which is designed for configuration management for MediaWiki (via PHP). And I was running with PHP versions 5.4 and 5.5 (the underpinning language for MediaWiki) that were not configured to properly on my server to support Composer or Composer’s PHAR files.

As a first approach, I attempted a manual install, bypassing configuration management and Composer, but the dependencies ran out of control. I finally gave up after drilling down to the 3rd level and not being able to make heads or tails out of very sparse documentation on how to install those lower level dependencies.

After I gave up on that, I decided to get Composer to work. It wasn’t too hard, just took a concerted effort and a little more research.

Here’s the outline I came up with:

1. Switch the MediaWiki’s PHP version to 5.6.
2. Switch the shell’s PHP version to 5.6.
3. Install Composer.
4. Use Composer to install the MediaWiki Extension:Maps.

To switch the MediaWiki app server’s PHP version to 5.6, Dreamhost publishes easy instructions and provides a wizard. No big deal.

Here are the instructions for updating the shell (or CLI) to PHP 5.6. The key here is that the right version is already installed. You just have to change your shell account to use that correct version.

After updating PHP, installing Composer is trivial. And so is installing the extension.

Finally done, Local Eats finally worked the way I wanted it to and I got the MediaWikis upgraded to the latest stable version. I think steps 1-12 took about an hour for the first install (on my gaming Wiki)  and 30 minutes for the second (the food Wiki, where Local Eats lives). Messing around with the Maps extension install and Composer probably took another hour or two, because I had to do a fair bit of research to identify the right path and how to carry it out.

After that, I worked on the Local Eats page itself, which you can see is coming along nicely.