Upgrading Moodle on Ubuntu Server

May 3, 2024 by Jonathan Downey

If you're running Moodle live, it's important to keep up-to-date for security. In this tutorial, we cover upgrading your Moodle instance. We also discuss when to upgrade, as well as how to coordinate updates with your plugins and PHP and database versions.

Why Upgrade?

If your LMS is running live online, it's only a matter of time before you'll need to upgrade. While it's nice that new LMS releases usually contain new features and bug fixes, the main reason to update is to get security updates. Out-of-date versions can become susceptible to all sorts of nasty attacks from nefarious actors.

Perhaps counter-intuitively, updating Moodle can be more complicated than the initial installation. Mainly, this is because (especially by the time one needs to upgrade), Moodle instances are made to be quite unique.

"Automation of installation and upgrading is a long-standing discussion. Few people run "standard" versions of Moodle without any plugins and so on and it would be very tricky to create [an automated upgrade process]."
- Howard Miller (Moodle.org forum)

Also, while the official Moodle documentation can be very useful, it is definitely oriented towards those with significant web development experience. Moreover, there are many different articles covering upgrading! Also, it aims to be as general as possible (and rightfully so), but this can be overwhelming for beginner self-hosters who then need to translate general instructions to their specific context. This article is geared towards for beginners, there is a lot of documentation regarding upgrades (and rightfully so), but I think that it can be a bit overwhelming. This tutorial attempts to fill some of these gaps, introducing the overall logic behind the upgrade process, as well as providing relevant instructions for instructors who have installed and configured Moodle in a standard way according to the other tutorials on this site.

How Does Upgrading Work?

Moodle-related content lives in a few places on your server:

The Moodle code in your webroot (i.e., /var/www/html/moodle)
The user files in the "moodledata" folder (i.e., /var/moodledata)
Information in the Moodle database table (i.e., in a MySQL database)

Accordingly, Moodle upgrades involve modifying files/subdirectories in the "moodle" and "moodledata" directories and database tables in your database. User information and files should be unaffected by the upgrade, but you will want to back up these directories and databases just in case.

When do I need to upgrade?

You can check the release schedule on moodledev.io for the Moodle version schedule.

You can also look at the "notifications" tab in the site administration menu on your Moodle site:

Upgrade notification in the admin menu

Don't make "hyperjump" upgrades. If you need to upgrade several versions ahead, you will need to do the upgrade in steps. For example, according to the Moodle 4.4 release notes, you need to already be on Moodle 4.1.2 or later in order to upgrade to Moodle 4.4. Here is a chart that may help you find information about the "steps" necessary for large upgrades.

"Do I Even Need to Upgrade?"

If your Moodle instance is live online, the answer is yes, eventually you will need to upgrade. Again, security.

However, don't think because there is a new, "bleeding edge" version of Moodle that you need to (or necessarily should) upgrade. This is especially the case if your current version of Moodle is a long-term support (LTS) release. In fact, security updates will usually continue to be released for LTS versions that may not be applicable to "newer" versions. (e.g., Moodle 4.1 will be supported for longer than Moodle 4.2)

Other reasons to not upgrade might be that older plugins that you use frequently are not compatible with newer Moodle versions because they are no longer maintained by their developers, or if you like the default user interface on older versions of Moodle.

You should also not be overly hasty to upgrade to non-LTS releases because Moodle wasn't designed to be downgraded. There's good reason for this, as using outdated Moodle versions poses a potential security risk.

Downgrading Moodle

It's uncommon that you will find yourself in a situation where you will want to downgrade your Moodle version, but it is possible. For example, I was in a situation where I needed an older version of PHP for other software running on my server. Alternatively, perhaps you upgraded for new functionality, but realized afterward that the new version is not a long-term release, and you regret the upgrade to a newer version.

If you do find yourself in the position where you need to downgrade, you'll have to do a fresh install of an old version of Moodle and restore student data from a backup.

Note that won't be able to downgrade from git by simply checking out an earlier version branch:

Upgrade Instructions

There are two ways to upgrade depending on whether you installed Moodle from git. Regardless of the route you take, you should:

Test the upgrade on a development server before doing it on your production server. Better safe than sorry!
Make backups of the "moodle" directory, the full database and the "moodledata" directory. Check the backups carefully to make sure everything was copied fully.

Enable "maintenance mode:"

Depending on your situation, you may or may not want to put your site into maintenance mode for plugin upgrades.
sudo -u apache /usr/bin/php /var/www/html/moodle/admin/cli/maintenance.php --enable
For extra security, you can use an upgrade key to protect sensitive information during the upgrade process. Remember, maintenance mode is not designed to prevent user access during version upgrades.

In maintenance mode, you may not be able to log back in in the usual way if you are logged out. Here is how to log back in if that happens.

When you're finished upgrading you can disable maintenance mode:
sudo -u apache /usr/bin/php /var/www/html/moodle/admin/cli/maintenance.php --disable
Upgrade PHP (if necessary)

If your current version of PHP is not compatible with the new Moodle version, you will need to download the version of PHP that corresponds to the new Moodle version.

You can find the current version you are using with:
php -i | grep php.ini

My current PHP version is 8.1

If you have more than one version of PHP installed, you can choose the appropriate one with:
sudo update-alternatives --config php
You'll also need to make sure your Apache PHP module is current, as well. You can check the version of the Apache PHP module (which is not that same as the PHP command line interface program) by adding a "test.php" file to your moodle folder in your webroot, then accessing it in your browser:

You can see which Apache modules are loaded:
apachectl -M
You can see the PHP Apache modules available in the Apache modules directory:
/etc/apache2/mods-available/

You will also need the Apache PHP module that corresponds to the PHP version that your new Moodle version needs. The versions officially supported by Ubuntu should work if you're trying to upgrade Moodle to a recent release. You can do so with:


                  sudo apt install libapache2-mod-php

Once you've downloaded the new Apache PHP module, you can enable it after disabling the old version:


                  sudo a2dismod php7.9
  sudo a2enmod php8.1
  sudo service apache2 restart

You want to make sure that you have the PHP package modules that are required per Moodle specifications (e.g., php8.X-xlm, etc.). Instructions for installation can be found here.

Upgrade Database (if necessary):

You can update the MySQL database in Ubuntu with the APT package manager:
sudo apt-get upgrade sudo apt-get install mysql-server

Note, you shouldn't have to upgrade Apache unless you are otherwise instructed to.

If Upgrading from Git:

If you initially installed Moodle via Git, and are looking to upgrade to a major release, you can simply switch to and checkout the branch of the Moodle git repository that corresponds to the version to which you want to update:


              cd /path/to/your/moodle/folder

  git branch -a

  git branch --track MOODLE_404_STABLE origin/MOODLE_404_STABLE

  git checkout MOODLE_404_STABLE

You can find a short guide to git commands for Moodle on Andrew Robert Nicols' blog.

If you've made any changes at all to the "moodle" directory on your current git branch, you may get a message aborting the upgrade. This is just git trying to keep you from overwriting and losing any important changes that you have made. For example, I got this message when changing permissions for subdirectories in the "moodle" directory. If the your edits are not important and can be overwritten, you can force the checkout, overwriting the original "moodle" branch with your changes:


              git  checkout .

If you are only doing a minor version upgrade (e.g., to take advantage of bug fixes): you can do so easily with:


              git pull

If Upgrading Manually:

If you didn't install Moodle from git, we can follow the standard upgrade instructions:

First, you'll need to download the new Moodle files and unzip them.
Then, copy the old config.php file from your backup into the new moodle directory.

Upgrading Plugins

It may not be strictly necessary to upgrade your plugins but be aware of potential security vulnerabilities. When the core Moodle upgrades are in place, you can you can just copy the plugin files into the moodle directory. If it's not necessary update your plugins (or if you are on the most recent version of the plugin already), you can just copy them from your backup of the "moodle" directory. If there are new versions of the plugins you would like to use, you can download them and add them in, just like you would do for the original plugin installation.

Usually, you can get away with upgrading plugins only once, even if you haven't upgraded Moodle in a long time. This is opposed to upgrading core Moodle code, where large version jumps, or "hyperjumps," are not recommended.

Final Steps

You're almost there...

Purging Caches

After the upgrade is complete, you should purge all caches, either via the web interface, or manually:


                  php admin/cli/purge_caches.php

Updating the Moodle Database

Once the Moodle files have been updated, you can launch the database upgrade by logging on to your Moodle site. You will either immediately see a prompt to upgrade Moodle database or you can start the update process at: Settings > Site Adminstration > Notifications.

Troubleshooting

I kept getting an "fatal PHP error" in the Apache error log, "Call to undefined function get_local_referer()," even after I had set the correct Apache PHP module for the Moodle version that I was upgrading to (usually you might see something like this if your PHP version is not appropriate). Manually deleting the "cache" and "localcache" directories in the "moodledata" directory fixed this.
If you get an error regarding max_input_vars needing " to be at least 5000"", you can set in it php.ini. (Also, MoodleDoc explanation)

Of course, don't forget to uncomment the line you are editing (it may be commented with a semi-colon)
If you receive a vague "500" internal error page in your browser, you can get more detail by going into the error log of your web server, e.g.:
cat /var/log/apache2/error.log