MediaWiki Maintenance

Upgrading MediaWiki, as it is in general installing it and using it (eg their APIs), is quite annoying. It definitely could be simplified in the process by writing like a Python script (well commented), but so far as I'd used not to upgrade this software so often, it's all manual labour.

The process can be divided in three steps:

backup the MySQL db and other parts of the system (extensions, images, etc)
download the newest version of the software, unpacking it, and prepare it
replace current MediaWiki version with newly prepared version

General, official, reference document for upgrading the wiki software.

Backup

Before starting the backup process (SQL dump), clear any "pending jobs" from the db:

Use runJobs.php to run all pending jobs and clear the queue before performing the upgrade.

Then backup the MySQL database:

mysqldump --user=<wikidb_user> --password=<wikidb_userpassword> <wiki_db_name> > mw-backup-<yyyy-mm-dd>.sql

You can find the database's user, password and name under the Database settings in the LocalSettings.php file part of the MediaWiki folder. The official guide suggests to make also a backup of the image folder, the plugins, the skins, LocalSettings.php etc, go ahead and do that. In this regard, it could be easier to make a backup copy of the entire MediaWiki directory under /var/www/:

sudo cp -r /var/wwww/mediawiki /var/www/mediawiki-bk-<yyyy-mm-dd>

<yyyy-mm-dd> stands for current date in the form of, for instance, 2023-03-02. See ISO 8601.

More info on how to back up a MediaWiki installation. As well as how to restore a MediaWiki from a backup.

Download newest MediaWiki

I tend to keep zip / tarballs / installation files in my home folder, and then move to /var/www/ accordingly. Therefore:

cd ~
fetch newest MediaWiki version, eg: wget https://releases.wikimedia.org/mediawiki/1.39/mediawiki-1.39.2.tar.gz (refer to the official docs for the correct URL)
unpack compressed file to a folder of the same name (eg mediawiki-1.39.2) : tar -xvzf mediawiki-1.39.2.tar.gz
delete compress file: rm mediawiki-1.39.2.tar.gz

Upgrade Mediawiki

Now we have:

a backup copy of the current MediaWiki at /var/www/mediawiki-<yyyy-mm-dd>
the newer MediaWiki version at ~/mediawiki-<version.number>, for example ~/mediawiki-1.39.2

Let's first move mediawiki-1.39.2 to /var/www:

sudo cp -r mediawiki-1.39.2 /var/www/.

(This operation could be replaced by sudo mv instead, up to you and to your level of comfort in dealing with unix and MediaWiki)

Then we want to copy some of the files in /var/www/mediawiki-<yyyy-mm-dd> to /var/www/mediawiki-1.39.2:

let's move to /var/www/: cd /var/www

let's copy the image folder: sudo cp -r mediawiki-<yyyy-mm-dd>/images mediawiki-1.39.2/.
- file and folder settings must be re-set afterwards, run:
  - find ./mediawiki-1.39.2/images -type d -exec chmod 755 {} \;
  - chgrp -R www-data mediawiki-1.39.2/images
let's copy the extensions folder: sudo cp -r mediawiki-<yyyy-mm-dd>/extensions mediawiki-1.39.2/.
- To be fair: while this should work, it might break things.Generally speaking, extensions should be kept up-to-date or they might not work with a newer version of MediaWiki. You can see a list of installed extensions by visiting this page under the section Installed extensions and manually download each extension to the extensions folder
- I would like to tell you you can simply run a command with PHP's Composer, but it breaks each time I use it (maybe in combination with how MediaWiki works), and it seems a better choice not to fix it... but you can if you want!
let's copy the settings file: sudo cp mediawiki-<yyyy-mm-dd>/LocalSettings.php mediawiki-1.39.2/.
let's copy the custom image logo (inside the assets folder): sudo cp -r mediawiki-<yyyy-mm-dd>/resources/assets mediawiki-1.39.2/resources/.
let's copy the skins folder: sudo cp -r mediawiki-<yyyy-mm-dd>/skins mediawiki-1.39.2/.

Refer to this official doc page for more.

After this, we can run the upgrade command:

cd mediawiki-1.39.2
php maintenance/update.php

Refer to the official docs section for any eventual problem. Usually this has been working flawlessly.

Replace current MediaWiki with newer MediaWiki

We have an upgraded version of the MediaWiki software at /var/www/mediawiki-1.39.2, and we want to use it instead of the current one at /var/www/mediawiki:

move the current version elsewhere: sudo mv mediawiki ~/.
rename newest version to default name: sudo mv mediawiki-1.39.2 mediawiki

After this, visit wiki.hackersanddesigners.nl and check if things are working!

Clean up

When all it's good, remove the following directories:

sudo rm -rf /var/www/mediawiki-<yyyy-mm-dd>
sudo rm -rf ~/mediawiki-1.39.2 (only if you made a copy (cp -r) of the directory from ~/. to /var/www/, instead of moving it (mv))

Debugging

No specific techniques, besides:

reading the printed error messages on the wiki website
check the Nginx logs by checking:
- access log: /var/log/nginx/mediawiki.access.log
- error log: /var/log/nginx/mediawiki.error.log