Upgrading
Moodle is designed to upgrade cleanly from one version to the next. Please refer to Upgrading to Moodle 1.6, Upgrading to Moodle 1.8 or Upgrading to Moodle 1.9 for particular considerations related to the upgraded version.
Changes that have been made to the original code, such as installing a contributed module (non-standard module) or a site edit of a php file, may not upgrade. This includes modifications to standard themes, that will be overwritten during an upgrade.
For those using cpanel, you can use this tutorial. It is a bit rough around the edges and is a little dated, but you should get the idea.
- For those who installed the package version of Moodle using an Ubuntu/Kubuntu/Debian package manager, upgrade instructions can be found here.
When upgrading a Moodle installation you should follow these steps:
Check the requirements
Spend some time re-reading the installation documentation and documentation for the new version. Check the system requirements for the target version you want to upgrade-to in Administration > Server > Environment.
Backup important data
There are three areas that need backing up:
- Moodle software directory/folder (For example, everything in server/htdocs/moodle)
- Moodle data (For example, server/moodledata)
- Moodle SQL database
Experienced site administrators know that it is a best practice (a very good idea) to make a backup of any production system before a major upgrade. In fact, it is a good idea to automate your server to backup your Moodle installation daily. Most upgrades on sites that have used the standard Moodle packages (no contributed code and no little tweaks to the php files), will not have any major issue.
- TIP: One more time, "do not risk what you can not afford to lose": do regular backups, make sure it backed up and know how to restore it!
Moodle software directory
Make a separate copy of these files before the upgrade, so that you can retrieve your config.php and any modules you have added like themes, and languages.
The best way is to rename the current Moodle directory to something else, then unpack the new Moodle archive into the old location.
Moodle data directory
The default name for this folder is moodledata. This is where uploaded content resides (such as course resources and student assignments). It is very important to have a backup of these files on a regular basis as a best practice. Sometimes upgrades may move or rename directories within your data directory.
In Linux you can use the cp (copy) command to make a temporary copy of the moodledata. example:
Linux
mkdir /var/www/moodledata_backup cp -r /var/www/moodledata/* /var/www/moodledata_backup
SQL database
Most Moodle upgrades will alter the SQL database tables, adding or changing fields. Each SQL server program (for example,MySQL, Postgresql, Oracle) has different ways to backup. In a MySQL server, one way of backing up is to 'dump' it to a single SQL file. The following example shows Unix commands to dump the database called "moodle":
mysqldump -u username -p -C -Q -e --create-options moodle > moodle-backup-2007-04-01.sql
Substitute your database user account for username. The -p flag will prompt you for the password for the username specified by -u.
If your database host is different from the host you want to execute the backup command (usually the web server), you have to specify it with the -h option to mysqldump:
mysqldump -u username -p -h databasehost -C -Q -e --create-options moodle > moodle-backup-2007-04-01.sql
You can also use the "Export" feature in Moodle's optional "MySQL Admin" web interface to do the same thing on all platforms. In Moodle v1.9 and greater, this is located in Site Administration -> Server -> Database. This interface can also be downloaded from http://download.moodle.org/modules/integrations.php. It is an integration of PHPMyAdmin for the Moodle administration interface.
SQL dump caveats
There are a MANY options possible for mysqldump.
- Please talk with your Systems Administrator (if you have one) or similar to see if there are site-specific flags you should use for your SQL dump.
- For example, if your local installation is running MySQL 5.2 and you are moving to a system running MySQL 5.0 or 4.1, you really ought to use the "--compat=mysql40" flag. (This is not too uncommon of a situation given the nature of ISP hosting as compared to local user Moodle setups)
- This seems obvious, but should be said outright: These instructions only work for dumping from MySQL! Postgresql, Oracle, and other database servers have different tools to dump databases.
- Given the example mysql import lines, above, you really should use the --no-create-db flag. If your database locally is named something differently from the migration site, not including this flag could cause problems.
Install the new Moodle software
Upgrading can be a simple process or a more complicated process. Sites that have not used contributed code and are migrating from say Moodle 1.x.1 to 1.x.3 should not have a problem. However, we still recommend that with any production server that you have made a successful backup of the MySQL database, the moodledata directory and the moodle program folders and files.
- Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new installations. Review the backup section above.
Standard install package
Having read the cautions about backups, download a copy of the standard install package. Here is a set of simple instructions for an average site.
- It is probably a good idea to use the site administration block>Server>Maintenance mode to prevent user activity as the site upgrades.
- Unzip or unpack the upgrade file so that all the Moodle software program files are overwritten on the server. Moodle will adjust SQL and moodledata if it needs to in the upgrade.
- Use the notification link in the site administration to start the upgrade process. You will see a series of lines indicating progress.
- After a successful upgrade, turn off the maintenance mode for your users.
Using a downloaded archive
- Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new installations. The best way is to rename the current Moodle directory to something else, then unpack the new Moodle archive into the old location.
Linux
mv moodle moodle.backup tar xvzf moodle-1.1.tgz
Next, copy across your config.php, any other plugins such as custom themes, and your .htaccess file if you created one:
cp moodle.backup/config.php moodle cp -pr moodle.backup/theme/mytheme moodle/theme/mytheme cp -pr moodle.backup/mod/mymod moodle/mod/mymod
Don't forget to
sudo chown www-data moodle/config.php
if necessary.
where www-data is whatever user the Apache user is on your system. This is often 'apache' or 'www'. You can find out by doing 'ls -l' in your /var/www/moodle folder (or wherever your moodle site is) and then looking at the owner and group.
so you may see something like
ls -l ...lots of lines... -rw-r--r-- 1 apache system 784 Jun 28 2007 config.php ...lots more lines...
so the owner is apache and the group is system.
To replicate this on your new system you can do 'chown apache:system config.php'
or to do a whole group do
chown apache:system ./*
and recursively
chown -R apache:system ./*
Using CVS
You can use CVS for updating or upgrading your Moodle. First you need to do a CVS checkout in your (empty) Moodle root directory.
You can use any of our CVS Mirror servers. Just replace SERVER.cvs.moodle.org in the instructions below with the name of the mirror server you chose!.
For Linux servers
To do a CVS checkout of Moodle, you first have to logon to the Moodle CVS server.
cvs -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle login No password for anonymous, so just hit the Enter button.
Go to the directory where you want the Moodle root to come and type
cvs -z3 -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle co -r MOODLE_18_STABLE moodle (where MOODLE_18_STABLE is the desired version)
To update, just go into the Moodle root directory and update to the new files:
cvs update -dP
To update to a new version type in the following and change 18 to whatever newest version upgrade number is
cvs -Q update -dP -r MOODLE_18_STABLE
Make sure you use the "d" parameter to create new directories if necessary, and the "P" parameter to prune empty directories.
For Windows servers
You can use Tortoise CVS to do the initial checkout and the updates.
If you have been editing Moodle files, watch the messages very closely for possible conflicts. All your customised themes and non-standard plugins will be untouched.
Do not forget to trigger the install process in the site administration block (see below).
Finishing the upgrade
The last step is to trigger the upgrade processes within Moodle.
To do this just visit the site administration block admin page (or http://example.com/moodle/admin) and the "Notifications" link.
Moodle will automatically detect the new version and perform all the SQL database or file system upgrades that are necessary. If there is anything it can't do itself (very rare) then you will see messages telling you what you need to do.
Assuming all goes well (no error messages) then you can start using your new version of Moodle and enjoy the new features!
- TIP: Use the site administration block>Server>Maintenance mode to prevent users from changing data during the upgrade.
- TIP: If you are running a large scale Moodle site (e.g. have more tha 10,000+ courses and 40,000+ users), make sure that you do your own performance profiling testing. Post a thread or check the Installation problems forum and check Tracker for potential issues.
Verify the upgrade (optional)
If you wish to confirm that the database definitions in the upgraded database match the definitions of a new, clean install (which they should) you might like to look at Verify Database Schema.
Upgrading more than one version
In general, it is recommended to upgrade via each version of Moodle, for example 1.7 -> 1.8 -> 1.9. An exception to this is when upgrading from 1.5 or 1.6, when it is recommended that 1.7 is skipped, in other words upgrade 1.5 -> 1.6 -> 1.8 -> 1.9. (The main reason for this recommendation is that the default roles settings obtained when upgrading to 1.7 are not ideal for 1.8 onwards.)
See also
- Installing Moodle
- Installation FAQ
- Upgrading to Moodle 1.6
- Upgrading to Moodle 1.8
- Upgrading to Moodle 1.9
- Upgrading to Moodle 2.0
- Environment
- Git Version control and upgrading
- Moodle.org Installation problems forum
- How to upgrade Moodle with cpanel tutorial - screencasts of older Moodle/Cpanel install but useful (also, a very large file that will take some time to load).
Using Moodle.org forum discussions:
