Updating MediaWiki: Difference between revisions

From ULYSSIS documentation
 
(47 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The MediaWiki project provides an official [https://www.mediawiki.org/wiki/Manual:Upgrading wiki page] which explains the procedure to update a wiki. Unfortunately, their instructions are very dense, and the page contains a lot of information that is outdated or irrelevant for our users. To make it easier for our users to update, this documentation page aims to be more accessible and easier to understand. However, this page is not an authoritative source on the subject. If the instructions on this page are unclear at any point, you should always refer back to the official instructions.
The MediaWiki project provides an official [https://www.mediawiki.org/wiki/Manual:Upgrading wiki page] which explains the procedure to update a wiki. Unfortunately, their instructions are complex, and the page contains a lot of information that is outdated or irrelevant for our users. To make it easier for our users to update, this documentation page aims to be more accessible and easier to understand. However, this page is not an authoritative source on the subject. If the instructions on this page are unclear at any point, you should always refer back to the official instructions.


With this out of the way, you can start the MediaWiki update process.
{{info|In this guide, we assume you are familiar with the files on your ULYSSIS account. If you don't know how to access these files, please read [[Accessing your files]] first.}}


== Downloading the latest version ==
== Downloading the right version ==
Most likely, you arrived at this page after receiving an email from our [[Software Version Checker]]. This email might contain a line similar to:
To start updating MediaWiki, you will need to download the archive file of the version you want to update to. If you did not receive an email from our [[Software Version Checker]], follow the instructions in the next subsection. Otherwise, you can skip to the subsection [[#Downloading the right version using the Software Version Checker | Downloading the right version using the Software Version Checker]].
  - MediaWiki in <path>. Installed version: <version1>. Latest version: <version2>.
This line tells you where the MediaWiki installation is located, its current version, and the latest version. Of course, to update MediaWiki to this latest version, you will need to download the update. The MediaWiki downloads can be found [https://www.mediawiki.org/wiki/Download here]. Make sure to download the zip file for the latest version from the email and save it somewhere on your PC.


== Making a backup ==
=== Downloading the right version based on your wiki ===
An important step in the update process is to create a backup of your data on the ULYSSIS server, to prevent data loss if something goes wrong. If you don't know how to access your files on your ULYSSIS account, refer to [[Accessing your files]] for easy instructions. The backup step consists of roughly two parts:
You can find your current MediaWiki version by going to the <code>Special:Version</code> page on your wiki (simply paste this in the search box) and looking for the "MediaWiki" version under "Installed software". For example, for this wiki, you can find the current version at [[Special:Version]]. At the time of writing, it looks like this:


* Creating a backup of your wiki database. If you use MySQL or PostgreSQL, you can follow the instructions on [[Making Backups#A backup of your databases]]. If you use SQLite, please refer to [https://www.mediawiki.org/wiki/Manual:Upgrading#Back_up_existing_files_and_the_database the official instructions]. If you are not sure about your database type or the name of your wiki database, you can search the <code>LocalSettings.php</code> configuration file for the following lines:
[[File:Installed software.png|center|frame]]
## Database settings
$wgDBtype          = "<db_type>";
$wgDBserver        = "<db_server>";
$wgDBname          = "<db_name>";
$wgDBuser          = "<user>";
$wgDBpassword      = "<password>";


* Creating a backup of your wiki files. The easiest way to do this is to '''rename''' the directory containing your <code>LocalSettings.php</code> configuration file (your wiki location) to a new directory. For example, if <code>LocalSettings.php</code> is stored in <code><username>/www/wiki</code>, you should '''rename''' this directory to <code><username>/www/wiki_backup</code>, or something similar.
A table of all recent MediaWiki versions can be found on [https://en.wikipedia.org/wiki/MediaWiki_version_history wikipedia]. Currently supported versions are indicated by a green or yellow color in the first column. To determine which version you want to download, follow these steps:
* If the ''branch'' of your version ('''the first two numbers''', like <code>1.xx</code>) is currently supported (green or yellow), you should choose the latest version for this branch. For example, for version 1.35.3, the branch is 1.35.
* If this branch is not supported anymore, you should choose the most recent LTS branch. This is indicated by '''(LTS)''' in the second column. '''Make sure this LTS branch is not older than your current branch!'''
* If the most recent LTS branch is older than your current branch, you should choose the newest supported branch (green).


== Extracting the new files ==
Now, click on the link of the branch you want to download. This will redirect you to a page with information about this version. The first paragraph on this page contains a link to <code>mediawiki-1.xx.yy.tar.gz</code>. Download this archive and save it somewhere on your computer.
Now, you will need to extract the zip file you downloaded in step 1. This should result in a directory which looks something like:
mediawiki-xxx/
├── cache/
├── docs/
├── ...
├── api.php
├── autoload.php
└── ...


Rename this directory to the original name of your wiki directory on your ULYSSIS account. For example, if your wiki was located at <code><username>/www/wiki</code>, rename this directory from <code>mediawiki-xxx</code> to <code>wiki</code>.
=== Downloading the right version using the Software Version Checker ===
The email you received will contain a link to the correct MediaWiki version. This link looks something like:
https://releases.wikimedia.org/mediawiki/1.xx/mediawiki-core-1.xx.yy.tar.gz


Next, you should upload this directory to your ULYSSIS account, to the original location of your wiki. If you followed step 2 correctly, the old files should be moved to a backup directory. As a result, after uploading, your ULYSSIS acocunt should contain the new files in something like <code><username>/www/wiki</code>, and the old files in <code><username>/www/wiki_backup</code>. Please refer to [[Accessing your files]] if you don't know how to upload files. Because MediaWiki contains a lot of (small) files, this might take a long time, up to 30 minutes.
Simply click this link to download the archive and save it somewhere on your computer.


Finally, you need to copy the configuration files and other files or directories you modified from the '''old''' directory to the '''new''' directory. Although only you know exactly which files these are, here are some suggestions from the [https://www.mediawiki.org/wiki/Manual:Upgrading#Other_files official instructions]:
== Renaming the old installation ==
An important step in the update process is to rename the old installation directory. This way, you can simply copy your data from the old installation directory to the new installation directory during the update. Additionally, you can easily restore your old wiki if something goes wrong.
 
The easiest way to do this, is to '''rename''' your wiki location (the directory containing your <code>LocalSettings.php</code> configuration file) to a new directory. If you don't know how to access your files on your ULYSSIS account, refer to [[Accessing your files]] for easy instructions. For example, if <code>LocalSettings.php</code> is stored in <code>www/wiki</code>, you should '''rename''' the wiki folder to <code>wiki_old</code>.
 
== Installing the new files ==
Now, you will need to upload the <code>mediawiki-1.xx.yy.tar.gz</code> file you downloaded in step 1 next to the old installation directory. For example, if your old installation directory is located in <code>www/wiki_old</code>, upload <code>mediawiki-1.xx.yy.tar.gz</code> to <code>www/</code>.
 
After uploading, you can extract the archive file on the server by using the Cyberduck "Expand Archive" feature. Simply right click the archive and click "Expand Archive".
 
[[File:Cyberduck expand.png|thumb|center]]
This will create a directory named <code>mediawiki-1.xx.yy</code>. Rename this directory to the original name of your wiki directory on your ULYSSIS account. For example, if the original name was <code>wiki</code>, rename this directory from <code>mediawiki-1.xx.yy</code> to <code>wiki</code>. This can be done using Cyberduck by right clicking the directory and clicking "Rename".
 
[[File:Cyberduck rename.png|thumb|center]]
 
Finally, you need to move certain other other files and directories from the '''old''' directory to the '''new''' directory. The easiest way to do this using Cyberduck is by going up a directory (so if your wiki is in <code>www/wiki</code>, go to <code>www</code>), and drag-and-dropping the necessary files and directories. For example, moving <code>LocalSettings.php</code> by drag-and-dropping it from <code>wiki_old</code> into <code>wiki</code>:
 
[[File:Cyberduck wiki move 1.png|500px]]
 
[[File:Cyberduck wiki move 2.png|500px]]
 
Although the exact files you need to move are different depending on your wiki, here are some suggestions from the [https://www.mediawiki.org/wiki/Manual:Upgrading#Other_files official instructions]:
* <code>LocalSettings.php</code>, which contains your old configuration settings.
* <code>LocalSettings.php</code>, which contains your old configuration settings.
* The <code>images/</code> directory, which contains all the uploaded files to the wiki, unless you have chosen a different upload directory. In that case, you should copy the different upload directory.
* The <code>images/</code> directory, containing the uploaded files to the wiki. Because the new wiki directory already contains an (empty) <code>images</code> directory, you need to delete that one first by right-clicking on it and pressing "Delete". Make sure to only delete the <code>images</code> directory in the '''new''' wiki directory. Then you can move the old <code>images</code> directory into the new wiki directory.
* In case you use a custom logo, this file also needs to be restored from backup. This logo is stored in <code>resources/assets/</code> or <code>images/</code>, depending on what you chose to use.
* Custom extensions from within the <code>extensions/</code> directory. Be careful not to overwrite the default extensions that are bundled with the new MediaWiki version.
* Custom extensions from within the <code>extensions/</code> directory. Be careful not to overwrite the default extensions that are bundled with the new MediaWiki version.
* Custom skins from within the <code>skins/</code> directory. Be careful not to overwrite the default skins that are bundled with the new MediaWiki version.
* Custom skins from within the <code>skins/</code> directory. Be careful not to overwrite the default skins that are bundled with the new MediaWiki version.
* Any modifications made to the old installation files, extensions, or skins. For example, this includes miscellaneous modifications to the configuration of extensions or skins.
* Any <code>.htaccess</code> file, if present. '''Make sure you can view hidden files'''; to enable this for Cyberduck, you can look at [[Accessing_your_files#Viewing_hidden_files|Accessing your files]].
* Any <code>.htaccess</code> file, if present.


== Updating extensions ==
== Updating extensions ==
If you use any extensions that are not bundled with MediaWiki by default, you should update them too. As the installation instructions for each extension are different for each extension, this page can't help you with this process. However, most extensions follow the same template as the MediaWiki upgrade itself:
If you use any extensions that are not bundled with MediaWiki by default, you should update them too. A list of bundled extensions can be found at https://www.mediawiki.org/wiki/Bundled_extensions_and_skins, these extensions will be updated automatically. However, for example, you might have the ULYSSIS extensions [[Securing MediaWiki using Centrale KU Leuven Login|MediaWikiShibboleth]] or [https://github.com/ULYSSIS-KUL/CompressUploads CompressUploads] installed. As with MediaWiki itself, you can find the versions of your installed extensions on the <code>Special:Version</code> page, under "Installed extensions". Extensions will often link to a website where you can download the latest versions. For example, for this wiki, you can find the installed extensions at [[Special:Version]]. At the time of writing, it looks like this:
 
[[File:Installed extensions.png|center|frame]]
 
Because the update instructions are different for each extension, you will have to refer to the update instructions of the extension you want to update. However, most extensions follow the same template as the MediaWiki upgrade itself:
* Downloading the latest version: make sure to download the correct update for your new MediaWiki version.
* Downloading the latest version: make sure to download the correct update for your new MediaWiki version.
* Making a backup of the extension: you should already have a backup in the directory you created in step 2.
* Making a backup of the extension: you should already have a backup in the directory you created in step 2.
* Extracting the files: similar to the MediaWiki zip files, you might have to copy the new extension files to a directory in the new <code>extension/</code> directory.
* Extracting the archive files: similar to the MediaWiki tar.gz archive files, you might have to copy the new extension files to a directory in the new <code>extension/</code> directory.


== Finalizing the update ==
== Finalizing the update ==
The final step in the update process is to update the database structure of your wiki. The MediaWiki developers were kind enough to create a script, called <code>update.php</code>. Unfortunately, this script must be executed using the command line. If you are not familiar with the command line or SSH, please read [[Accessing shell servers over SSH]] first.
The final step in the update process is to update the database structure of your wiki. Your MediaWiki installation contains a script, called <code>update.php</code>, to perform the necessary database upgrades. This script can be executed using the Cyberduck "Send Command" feature.
 
[[File:Cyberduck send command.png|thumb|center]]
 
Enter the following command in the pop-up box (of course, replace <code><wiki installation location></code> with the location of your new installation):
 
php <wiki installation location>/maintenance/update.php
 
For example, if your wiki is located at <code>www/wiki</code>, the command should be as follows:
 
[[File:Cyberduck update.png|center|750px]]


After connecting to your account using SSH, navigate to the directory containing your new wiki installation. For example, if your wiki is located at <code><username>/www/wiki</code>, execute:
After pressing "Send", the command will be executed on the server. If everything went well, you should see a lot of output, ending with something like:
cd ~/www/wiki
 
This directory should contain all your wiki files, such as <code>LocalSettings.php</code>. Now, navigate to the <code>maintenance/</code> directory:
[[File:Cyberduck update output.png|center|750px]]
cd maintenance
 
This directory contains the <code>update.php</code> file. To run this script, execute:
If you get the error <code>Could not open input file</code>, you might have misspelled the installation location. Double check the path to make sure everything is correct.
php update.php
 
The script will first display a 5 second countdown to execution, just in case you want to abort. After the countdown, you should not interrupt the execution of the script. If everything went well, you should see a lot of text, ending with:
If you encounter any other errors while executing the script, you could try taking a look at the [https://www.mediawiki.org/wiki/Manual:Upgrading#Command_line_2 official instructions]. If this does not resolve your problems, feel free to send us an email. We will try to assist you in completing the update.
Done in x s.


Congratulations! You successfully updated MediaWiki. Still, there are two more important steps you must perform:
Congratulations! You successfully updated MediaWiki. Still, there are two more important steps you must perform:
* Test your new MediaWiki installation: make sure all basic functionality (viewing, editing pages, file upload) works and all your extensions function properly.
* Test your new MediaWiki installation: make sure all basic functionality (viewing, editing pages, file upload) works and all your extensions function properly.
* Delete the backup installation: for example, if your backup is stored in <code><username>/www/wiki_backup</code>, you can remove it using the command line or through a GUI. A simple GUI explanation can be found on [[Accessing your files]].
* Delete the old installation: you should remove the previously created <code>www/wiki_old</code> directory, using the command line or through a GUI. A simple GUI explanation can be found on [[Accessing_your_files#Creating_and_Deleting_files_and_folders|Accessing your files]].
 
== If something goes wrong ==


However, if you did encounter any errors while executing the script, you could try taking a look at the [https://www.mediawiki.org/wiki/Manual:Upgrading#Command_line_2 official instructions]. If this does not resolve your problems, feel free to send us an email. We will try to assist you in completing the update.
If something goes wrong during the update so your wiki doesn't work anymore, you can revert the process to go back to your old wiki. If you already moved files or directories such as <code>LocalSettings.php</code> or <code>images</code> from <code>wiki_old</code> to <code>wiki</code>, move them back into <code>wiki_old</code>. Then delete <code>wiki</code> and rename <code>wiki_old</code> back to <code>wiki</code>. Your old wiki is then restored so you can retry the update process. If you still run into any trouble, feel free to email us at [mailto:ulyssis@ulyssis.org ulyssis@ulyssis.org].

Latest revision as of 22:09, 7 September 2021

The MediaWiki project provides an official wiki page which explains the procedure to update a wiki. Unfortunately, their instructions are complex, and the page contains a lot of information that is outdated or irrelevant for our users. To make it easier for our users to update, this documentation page aims to be more accessible and easier to understand. However, this page is not an authoritative source on the subject. If the instructions on this page are unclear at any point, you should always refer back to the official instructions.

In this guide, we assume you are familiar with the files on your ULYSSIS account. If you don't know how to access these files, please read Accessing your files first.


Downloading the right version

To start updating MediaWiki, you will need to download the archive file of the version you want to update to. If you did not receive an email from our Software Version Checker, follow the instructions in the next subsection. Otherwise, you can skip to the subsection Downloading the right version using the Software Version Checker.

Downloading the right version based on your wiki

You can find your current MediaWiki version by going to the Special:Version page on your wiki (simply paste this in the search box) and looking for the "MediaWiki" version under "Installed software". For example, for this wiki, you can find the current version at Special:Version. At the time of writing, it looks like this:

Installed software.png

A table of all recent MediaWiki versions can be found on wikipedia. Currently supported versions are indicated by a green or yellow color in the first column. To determine which version you want to download, follow these steps:

  • If the branch of your version (the first two numbers, like 1.xx) is currently supported (green or yellow), you should choose the latest version for this branch. For example, for version 1.35.3, the branch is 1.35.
  • If this branch is not supported anymore, you should choose the most recent LTS branch. This is indicated by (LTS) in the second column. Make sure this LTS branch is not older than your current branch!
  • If the most recent LTS branch is older than your current branch, you should choose the newest supported branch (green).

Now, click on the link of the branch you want to download. This will redirect you to a page with information about this version. The first paragraph on this page contains a link to mediawiki-1.xx.yy.tar.gz. Download this archive and save it somewhere on your computer.

Downloading the right version using the Software Version Checker

The email you received will contain a link to the correct MediaWiki version. This link looks something like: 

https://releases.wikimedia.org/mediawiki/1.xx/mediawiki-core-1.xx.yy.tar.gz

Simply click this link to download the archive and save it somewhere on your computer.

Renaming the old installation

An important step in the update process is to rename the old installation directory. This way, you can simply copy your data from the old installation directory to the new installation directory during the update. Additionally, you can easily restore your old wiki if something goes wrong.

The easiest way to do this, is to rename your wiki location (the directory containing your LocalSettings.php configuration file) to a new directory. If you don't know how to access your files on your ULYSSIS account, refer to Accessing your files for easy instructions. For example, if LocalSettings.php is stored in www/wiki, you should rename the wiki folder to wiki_old.

Installing the new files

Now, you will need to upload the mediawiki-1.xx.yy.tar.gz file you downloaded in step 1 next to the old installation directory. For example, if your old installation directory is located in www/wiki_old, upload mediawiki-1.xx.yy.tar.gz to www/.

After uploading, you can extract the archive file on the server by using the Cyberduck "Expand Archive" feature. Simply right click the archive and click "Expand Archive".

Cyberduck expand.png

This will create a directory named mediawiki-1.xx.yy. Rename this directory to the original name of your wiki directory on your ULYSSIS account. For example, if the original name was wiki, rename this directory from mediawiki-1.xx.yy to wiki. This can be done using Cyberduck by right clicking the directory and clicking "Rename".

Cyberduck rename.png

Finally, you need to move certain other other files and directories from the old directory to the new directory. The easiest way to do this using Cyberduck is by going up a directory (so if your wiki is in www/wiki, go to www), and drag-and-dropping the necessary files and directories. For example, moving LocalSettings.php by drag-and-dropping it from wiki_old into wiki:

Cyberduck wiki move 1.png

Cyberduck wiki move 2.png

Although the exact files you need to move are different depending on your wiki, here are some suggestions from the official instructions:

  • LocalSettings.php, which contains your old configuration settings.
  • The images/ directory, containing the uploaded files to the wiki. Because the new wiki directory already contains an (empty) images directory, you need to delete that one first by right-clicking on it and pressing "Delete". Make sure to only delete the images directory in the new wiki directory. Then you can move the old images directory into the new wiki directory.
  • Custom extensions from within the extensions/ directory. Be careful not to overwrite the default extensions that are bundled with the new MediaWiki version.
  • Custom skins from within the skins/ directory. Be careful not to overwrite the default skins that are bundled with the new MediaWiki version.
  • Any .htaccess file, if present. Make sure you can view hidden files; to enable this for Cyberduck, you can look at Accessing your files.

Updating extensions

If you use any extensions that are not bundled with MediaWiki by default, you should update them too. A list of bundled extensions can be found at https://www.mediawiki.org/wiki/Bundled_extensions_and_skins, these extensions will be updated automatically. However, for example, you might have the ULYSSIS extensions MediaWikiShibboleth or CompressUploads installed. As with MediaWiki itself, you can find the versions of your installed extensions on the Special:Version page, under "Installed extensions". Extensions will often link to a website where you can download the latest versions. For example, for this wiki, you can find the installed extensions at Special:Version. At the time of writing, it looks like this:

Installed extensions.png

Because the update instructions are different for each extension, you will have to refer to the update instructions of the extension you want to update. However, most extensions follow the same template as the MediaWiki upgrade itself:

  • Downloading the latest version: make sure to download the correct update for your new MediaWiki version.
  • Making a backup of the extension: you should already have a backup in the directory you created in step 2.
  • Extracting the archive files: similar to the MediaWiki tar.gz archive files, you might have to copy the new extension files to a directory in the new extension/ directory.

Finalizing the update

The final step in the update process is to update the database structure of your wiki. Your MediaWiki installation contains a script, called update.php, to perform the necessary database upgrades. This script can be executed using the Cyberduck "Send Command" feature.

Cyberduck send command.png

Enter the following command in the pop-up box (of course, replace <wiki installation location> with the location of your new installation): 

php <wiki installation location>/maintenance/update.php

For example, if your wiki is located at www/wiki, the command should be as follows:

Cyberduck update.png

After pressing "Send", the command will be executed on the server. If everything went well, you should see a lot of output, ending with something like:

Cyberduck update output.png

If you get the error Could not open input file, you might have misspelled the installation location. Double check the path to make sure everything is correct.

If you encounter any other errors while executing the script, you could try taking a look at the official instructions. If this does not resolve your problems, feel free to send us an email. We will try to assist you in completing the update.

Congratulations! You successfully updated MediaWiki. Still, there are two more important steps you must perform:

  • Test your new MediaWiki installation: make sure all basic functionality (viewing, editing pages, file upload) works and all your extensions function properly.
  • Delete the old installation: you should remove the previously created www/wiki_old directory, using the command line or through a GUI. A simple GUI explanation can be found on Accessing your files.

If something goes wrong

If something goes wrong during the update so your wiki doesn't work anymore, you can revert the process to go back to your old wiki. If you already moved files or directories such as LocalSettings.php or images from wiki_old to wiki, move them back into wiki_old. Then delete wiki and rename wiki_old back to wiki. Your old wiki is then restored so you can retry the update process. If you still run into any trouble, feel free to email us at ulyssis@ulyssis.org.

Retrieved from "https://docs.ulyssis.org/index.php?title=Updating_MediaWiki&oldid=1561"