System Administrator's Guide/Upgrading Mahara

The following document describes how you upgrade a Mahara installation. This process is largely the same regardless of whether you are doing a major version upgrade, for example from 17.10 to 18.04, or a minor version upgrade (e.g. 18.04.1 to 18.04.2).

The basic process is:

1. Close your site
2. Make a backup of your data and code changes
3. Replace the old code with the new code
4. Run the database upgrade
5. Open your site

1. Close your Mahara site

While you are running the upgrade, you will be copying, and perhaps even temporarily removing important files that Mahara requires to run. Also, there will be a time when you have put the new code in place but have not yet upgraded the database. During these times, Mahara will not work properly. So, it is recommended to put Mahara into "Maintenance mode" via the button the Administration homepage. This will force all current users to log out of your site, except for administrators.

Alternatively, adding the below to your Apache site config or .htaccess file will redirect traffic to your site to (e.g. a maintenance page):

• RewriteEngine on     (if it is not already on)
• redirectMatch 301 ^(.*)$ http://www.domain.com

2. Make a backup of your database and dataroot directory

The upgrade process can fail sometimes, so it is important to take a backup of your site beforehand. However, note that you should make your backup after you have closed your site, so you can ensure that none of your users lose any data.

Mahara stores all of your important user data in two places:

1. The database is where user profiles, artefact data, group information, Views and most other data is stored.
   • If you are using Postgres, you can back this up using pg_dump.
   • If you are using MySQL, you can back this up using mysqldump.
   • If you are on shared hosting, you may be able to back up your database using a web console tool such as phpMyAdmin or phpPgAdmin, provided by your host.
2. The dataroot directory is a directory on the server where files, including images, videos, profile icons and other such files are stored. Mahara also stores session files there.
   • You can back this up by simply copying the entire directory (and perhaps compressing the copy in a zip file).

Those two places are the only places that store your data. But, if you have made customizations to Mahara's files then you should also back those up so that you can re-apply them to the upgraded codebase. You should keep a record of your customisations so this process is easier - the best way to do this is by keeping your code in version control. This is beyond the scope of this document, but keeping your code in a Git repository with a branch for your changes is a smart and easy way to manage your changes, and allows you to track the stable branch of the Mahara Git repository as well, which will keep you up to date with the latest bug fixes.

3. Replace the old code with the new code

If you've made no changes to your copy of Mahara, the best way is to extract the new archive, move the old folder out of the way and move the new folder in to the place where the old folder was. This ensures that files that need to be deleted are removed.

Then copy your config.php file into the new folder. If you use non-core plugins or themes in your site, make sure to copy them into the new folder as well.

Extracting the new archive over the top of the old code is not recommended - this process does not remove files that should be removed, and of course will blow away any code changes you have made. Play it safe - move the old code to one side then put the new code in place. This also makes it easy for you to "roll back" to the old code if you find problems - or at least, gives you the ability to examine the old and new code side by side.

If you have made changes to Mahara's files, you might like to make a patch containing your changes and apply it to the new folder. This will ensure that upgrading will not break your changes, and will point out any conflicts between your patches and the new code. (Better still, look into using a version control system such as Git, Mercurial, Subversion, or CVS, to keep track of your code changes.)

4. Upgrade the database

Visit admin/upgrade.php in your browser. You should see a header at the top of your page telling you an upgrade is ready. Click the "Perform upgrade now" link to launch the upgrade script.

You should see the browser upgrade Mahara core and each of the plugins, in sequence. If you have your site set to $cfg->productionmode = false in your config.php file, you should also see regular status messages printed to the screen as the script progresses. If not, then these messages will be printed to your web server's error logs instead.

Database upgrades may take several minutes, particularly on a large site, and particularly for a "major release", going from one Mahara series to another (i.e. 15.04 to 15.10). However, if the upgrade script takes more than 5 minutes without showing any signs of progress, then it is possible that the script has crashed on the back end, even if the spinner icon is still spinning. If your site is not in production mode, check your web server's error logs to see whether the script is, in fact, still running and producing output. If it has crashed, it is recommended to restore your database from its backup, and try the upgrade again, perhaps using the command-line upgrade utility.

4a. Upgrading at the command-line

If your Mahara site is very large, then some major release upgrades may take upwards of half an hour. In this case, it is recommended that you instead use the command-line upgrade utility, available under your Mahara installation at htdocs/admin/cli/upgrade.php. This is a command-line PHP script. Depending on your system's file permissions, it may be necessary to run the script as the same user that Apache runs as, e.g.:

sudo -u www-data /usr/bin/php /PATH/TO/YOUR/MAHARA/htdocs/admin/cli/upgrade.php

4b. Upgrading a migrated database

Note: If you have cloned or migrated the database from elsewhere before running upgrade, make sure the database user which owns the new copy of the database also is the owner of the copied sequences and triggers as well.

4c. Upgrading from site older than one recommended in direct upgrade

The README.md file shows what the minimum version a direct upgrade should work from, for v17.10 one can upgrade directly from 15.04.0 and above. If you try upgrading from an older site and receive errors you can then try doing the upgrade in two or three steps. This is also useful if:

• the upgrade takes a very long time to run and/or times out during upgrade
• you need to upgrade PHP / SQL versions but older site is not compatible with the newer versions

Example: To upgrade from version 1.8.2 -> 17.04 you will need to do:

• Upgrade site from 1.8.2 -> latest version of 15.04 (eg 15.04.14) and check that the site is still function correctly.
• Do any upgrading of PHP / SQL that is needed, eg upgrade PHP from version 5.4 -> 7.0
• Upgrade version 15.04.14 -> 17.04.2

Example: To upgrade from version 1.8.2 -> 18.10 you will need to do:

• Upgrade site from 1.8.2 -> latest version of 15.04 (eg 15.04.14) and check that the site is still function correctly.
• Do any upgrading of PHP / SQL that is needed, eg upgrade PHP from version 5.4 -> 7.0
• Upgrade version 15.04.14 -> latest version of 17.04 (eg 17.04.9) and check that the site is still function correctly.
• Upgrade version 17.04.9 -> latest version of 18.10

5. Make your site available to your users again

Now that your site has been upgraded successfully, don't forget to open it for business again!

Troubleshooting

Q: The upgrade failed! :(

A: The upgrade process is always well tested, so should not have. But if it does, please get in contact with us on the forums or in the #mahara IRC channel - and be prepared to potentially be asked for a dump of your database and copy of the error messages ready.

If you find the problem yourself, please feel free to open a bug report with the relevant information, so we can fix it ASAP!

Q: The upgrade hung, none of the upgrades seemed to run when I visited admin/upgrade.php

A: Try a hard reload in your browser (usually Ctrl+R/Apple+R). This will force downloading the new javascript, which might be all that's necessary to get the upgrader rolling again.

Q: How do I know the upgrade worked/How do I know my site is now the new version of Mahara?

A: The full version number is shown at the bottom of the screen in the administration section. It will look something like this.

Mahara version 15.10.1 (2015092911)

You can also see the major release of your Mahara site in a meta tag in the page's rendered HTML (by doing "View Source" in your web browser).

<meta name="generator" content="Mahara 15.10 (https://mahara.org)" />

Note that we do not display the full minor version number of a Mahara site publicly, for security reasons.

Q: The theme looks broken?

A: Do a hard reload in your browser (usually Ctrl+R/Apple+R).

If this doesn't fix it, check to make sure you upgraded by replacing the old code with the new code, rather than copying over the old code. If you copied over the old code, then you may still have old CSS files in your site which should be removed, and these may be interfering with the display of your theme. See step 3 of this page for more details.

Q: My custom theme looks broken?

A: Every major new version of Mahara will change the templates and stylesheets, so your custom theme will usually require some work after an upgrade. If your theme overrides any templates, look at each of those templates in Mahara's raw theme to see if there have been any changes since the last version, and if so, make sure those changes are reflected in your theme. You may also need to change your stylesheets, because Mahara will have changed elements, ids and classes since the previous version.

Q: PHP Fatal error: Cannot redeclare get_message_thread_mr()

A: See Bug 1519516. You were upgrading to Mahara 15.10 or later and you copied the new code on top of the old code. Follow the instructions on Step 3 of this page to replace the old code with the new code instead.

Q: I'm getting an error about a "urlsecret"

A: Mahara 16.04 added a security feature to prevent unauthorized users from running a Mahara site's installer, upgrade, or cron scripts by accessing them via a browser URL. This is a secret string called the "urlsecret", that you can add to your config.php file. If it's not set, and you try to run the installer, upgrader, or cron, you might see this message:

The 'urlsecret' parameter contains invalid characters

... or this message:

You do not have access to this functionality. Please provide the value for "urlsecret" from your config.php file as part of the URL

To fix this, you'll need to add a $cfg->urlsecret value to your config.php file. You will then need to append it to the end of the URL when you access lib/cron.php or admin/upgrade.php through the browser rather, e.g.: http://example.com/lib/cron.php?urlsecret=mysupersecret.

The entry in your config.php file should look something like this (except with your own secret string rather than the default "mysupersecret".

$cfg->urlsecret = 'mysupersecret';

If you wish to disable this feature, set $cfg->urlsecret to null instead.

Q: "Mahara: Site unavailable, CSS files are not present..."

A: If you're installing Mahara 15.10 or later via a git checkout, you may see this message:

CSS files are not present in your htdocs/theme/raw/style directory. If you are running Mahara from a git checkout, run "make css" to build the CSS files. If you are running Mahara from a ZIP download, try downloading and unzipping again.

That's because Mahara 15.10 and later don't ship with CSS files. Instead, it ships with SCSS files that must be compiled into CSS files. As the error message says, you have two options:

Option 1. Download Mahara from Launchpad. The ZIP files there are packaged with built CSS files.

Option 2. Build the CSS files. Mahara's git branch contains a build script, written using the node.js "gulp" framework. If you're on Ubuntu 14.04, you can set this up like so:

sudo apt-get install nodejs-legacy npm
cd /path/to/your/mahara
npm install
sudo npm install -g gulp

Once you've done that, you can build the CSS by doing "make css" from within your mahara code directory. (This will run some instructions encoded in the file there called "Makefile".

cd /path/to/your/mahara
make css

Q: Unable to login after upgrade

A: This can happen when upgrading the underlying PHP that Mahara uses when Mahara is using file based sessions.

The problem here is due to how older PHP 5x saved session files versus newer 7x version (older sessions began with a char 0-9 or a-f, newer versions use 0-9 or a-v).

To fix this up you will need to go into your dataroot directory (path is defined in your config.php file) and delete the 'sessions' sub-directory as well. The sessions directory and correct sub-directories will then be automatically generated again on next page load of Mahara.

Q: Emojis and other utf8 characters are showing as '?'

A: If your database is MySQL and has been around for a long time this issue may come up. The specific issue is with the default character set and collation that used to be the default. Upgrading the database is documented on Bug 1912492.