System Administrator's Guide/Upgrading Mahara: Difference between revisions

Revision as of 11:58, 6 June 2012

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.1 to 1.2, or a minor version upgrade (e.g. 1.1.5 to 1.1.6).

The basic process is:

Close your site
Make a backup of your data and code changes
Put the new code in place
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. Put the new code in place

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.

The chances are that you will want the config.php from your previous site.

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, 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.

If you use non-core plugins in your site, make sure you remember to add them back to the new version of Mahara.

4. Upgrade the database

Visit admin/upgrade.php in your browser. Watch the database upgrade happen. Note that if your system is quite large, the upgrade could take a minute or longer to run. Unfortunately, there is no progress indicator at this time - the best way to watch progress is to tail the error log and watch for problems.

Note: When upgrading from Mahara 1.1 to 1.2, you might see the installation screen hang, with no spinners at all. This is most likely because of a javascript error caused by your browser having old javascript files cached. To solve this, hit Ctrl+F5/Apple+F5 or whatever keystroke you need to do a hard reload in your browser. This will force downloading the new javascript, and the upgrader should then run.

Note: When upgrading from Mahara 1.0 to 1.1, the "artefact.file" upgrade may take quite a long time, as it is scanning all of the files in your dataroot for their mime types. Don't panic if it takes a very long time to complete!

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).

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.

@@ Line 68: / Line 68: @@
 ==Troubleshooting==
-<div id="section_7">
 ===Q: The upgrade failed! :(===
@@ Line 76: / Line 74: @@
 If you find the problem yourself, please feel free to open a bug report with the relevant information, so we can fix it ASAP!
-</div><div id="section_8">
 ===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.
-</div><div id="section_9">
 ===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.
-</div><div id="section_10">
 ===Q: The theme looks broken?===
@@ Line 95: / Line 87: @@
 '''A:''' Do a hard reload in your browser (usually Ctrl+R/Apple+R).
-</div></div></div></div></div>
+===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.