Upgrading from Totara Learn 12 or below to Totara Talent Experience Platform
The following steps provide a summary of the changes required to migrate a Totara Learn 12 site to Totara 13.
If possible we recommend completing the full process on a staging site with a recent version of your site data before proceeding with the production upgrade. This will ensure that you catch any problems without impacting your production site.
Ensure your site is running on a recent release of the current major version you are running on
In order to upgrade to a new major version you need to be on a recent release of your current major version. Also note that upgrades are only supported from Totara Learn 9 and above, so if you are running an older version of Totara than that you will need to upgrade to Totara Learn 9 first.
Ensure your environment supports the minimum software versions required for Totara 13
This information can be found in the readme.md file for version 13, or by switching to version 13 from the Environment page (Quick-access menu > Server > Environment) of an existing Totara site:
Schedule an outage window long enough to complete and test a major version upgrade
The required outage window will depend on the size of your site. We recommend allowing several hours to ensure you have sufficient time to back up, run the upgrade and test before re-enabling access.
Run the cron
Complete a full cron run just prior to enabling maintenance mode to ensure all recent data has been processed.
Put the site in maintenance mode
This can be done via the web (under Site administration > Server > Maintenance mode), and you can optionally add a message that will be displayed to non-admin users during maintenance.
Back up your site
You should complete a full backup of your code, sitedata and database prior to starting the upgrade.
Replace your site code
Remove the old source folder and replace with the new source folder. Alternatively you can update your site code using version control software. Ensure you don't copy the new copy on top of the old directory as this will leave old files in place.
If you have any custom plugins on your existing site, ensure they are moved into the same subfolder within the server directory of the new codebase. So for example if you had a custom plugin at blocks/myblock/ in Totara Learn 12, you need to move it to server/blocks/myblock/ in 13.
Make changes to your config.php file
You need to update your existing config.php file with the following changes:
- Remove the following line if it exists near the top of the config.php file:
global $CFG;
- Add a flavour declaration specifying which flavour the site should be using:
$CFG→forceflavour = 'flavourname';
The following options are available for flavourname depending on which combination of products the upgraded site will be using:- learn
- engage
- perform
- learn_perform
- learn_engage
- perform_engage
- learn_perform_engage
- Remove this line (or any similar one) from the bottom of config.php:
require_once(dirname(__FILE__) . '/lib/setup.php');
Your config.php should remain in the top-level folder (do not move it to server/config.php).
Modify web server configuration to point to server directory
You need to adjust the document root for your web server to point to the server directory, not the top-level directory.
Instructions for this will depend on your web server software and version but here are some instructions for Apache and Nginx:
Run CLI upgrade script
From the top-level directory you can run the upgrade as follows:
php server/admin/cli/upgrade.php
Ensure you are logged in as a user who has the same permissions as your web server (e.g. write access to dataroot).
Please ensure you've added the flavour to your config.php before running the upgrade script.
Purge caches
This can also be done from the command line as follows:
php server/admin/cli/purge_caches.php
Review defaults for new settings
Log in as an admin and visit the Notifications page (Quick-access menu > Notifications). You should be redirected to review all new settings added in version 13. Review and ensure you are happy with the defaults.
Review your theme
If your site used Basis or Roots as the default theme you should have automatically been switched to our new default theme Ventura. Otherwise your site will continue to use the current theme. If you have a custom theme that inherits from Basis or Roots, and you need to theme Totara Flavours which include either Totara Engage or Totara Perform, you will need to update your custom theme to override new, default colour variables.
Test your site
At this stage we recommend asking some of your key stakeholders to test your site and make sure everything is working as expected. This includes testing any customisations you may have made.
Backup your site again (optional)
While not strictly necessary it can be useful to take another full backup of your site following the upgrade, so you can review if necessary to see exactly what was changed during upgrade.
Disable maintenance mode
As a Site Administrator disable maintenance mode to give users access to your site again.