This work, "Totara Social; User guide for Site Administrators and Trainers", is a derivative of “Mahara Wiki” by Catalyst IT Ltd, used under CC BY-SA 3.0.
"Totara Social; User guide for Site Administrators and Trainers " is licensed under CC BY-SA 3.0 by Totara Learning Solutions Ltd
The following document describes how you upgrade a Totara Social installation. 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.
Close your Totara Social site
While you are running the upgrade, you will be copying, and perhaps even temporarily removing important files that Totara Social requires to run. Totara Social closes the site automatically when new code is added and the database hasn't been upgraded.
To manually close the site select Administration > Admin Home > Close.
Make a backup of your database and dataroot directory
Totara Social stores all of your important user data in two places:
- The database is where user profiles, content, group information, pages and most other 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. Totara Social also stores session files and chat logs 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 Totara Social git repository as well, which will keep you up to date with the latest bug fixes.
Put the new code in place
If you've made no changes to your copy of Totara Social, 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 Totara Social.
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.
If you have a large site it is recommended that the upgrade is run from the Command Line Interface (CLI) rather than from the web browser interface as the CLI Admin can immediately see the progress of the upgrade and the page will never time out. You can do this by running the command:
php [code directory]/admin/cli/upgrade.php
If you have cloned or migrated the database from elsewhere before running upgrade, make sure the owner of the new copy of the database also is the owner of the sequences and triggers as well.
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! If you didn't close the site manually then the Totara Social site will be opened again once the database upgrade is finished. If you closed the site manually then you will need to open the site manually as well.
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
If you find the problem yourself, please feel free to create a support ticket 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 Totara Social?
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 Totara Social 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 Totara Social'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 Totara Social will have changed elements, ids and classes since the previous version.
