System Administrator's Guide/Upgrading Mahara
From Mahara Wiki
< System Administrator's Guide
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 1.6 to 1.7, or a minor version upgrade (e.g. 1.7.2 to 1.7.3).
The basic process is:
- Close your site
- Make a backup of your data and code changes
- Replace the old code with the new code
- Run the database upgrade
- 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. From Mahara 1.1 onwards, this situation is detected and your site is closed automatically by Mahara itself. For 1.0 installations, you should close your site with a .htaccess * file, or if you know your site has a period of time where it won't be used, do your upgrade in that time.
* Alternatively, adding the below will redirect traffic to your site to (e.g. a maintenance page), if using Apache:
- RewriteEngine on (if it is not already on)
- redirectMatch 301 ^(.*)$ http://www.domain.com
2. Make a backup of your database and dataroot directory
Mahara stores all of your important user data in two places:
- The database is where user profiles, artefact data, group information, Views and most othe data is stored.
- 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.
Those two places are the only places that store your data - but you may have made customisations to the code, which you may need to re-apply 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.
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.
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.
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
4a. 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.
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! In Mahara 1.1, if the site was automatically closed it will be opened again once the database upgrade is finished.
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 version number is at the bottom of the screen in the administration section.
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.