Previous Chapter: New Installation
Next Chapter: Administrator Home

Upgrading an Existing ATutor Installation

Considerations Before Upgrading

Note that Release Candidates (RC) and nightly build upgrades are not supported using this method and that depending on the size of the old courses, some steps of the upgrade may require considerable time to complete (in particular steps 2 and 6).

Be sure that Language Packs you have installed on your old version of ATutor are available for the new version, or be prepared to translate the missing language. The old language will be removed during upgrade. If they are not available, you might volunteer to help finish any remaining language that needs to be translated for these languages. See the Translator Documentation for more details. If you have made custom changes the the language, you may wish to export the customized language using the language manager.

If you have Custom Themes created, export those before upgrading, then import them back into the new version of ATutor after the upgrade is complete (you may need to make a few adjustment after reimporting the custom themes if there have been changes in the ATutor)

If you have Extra Modules installed, be sure the modules are either compatible, or are available for the new version. Modules must be reinstalled after an upgrade.

Also be sure the System Requirements are still met.

Before upgrading, rename your old ATutor directory. Download the latest version of ATutor and extract the new version into the same directory that the old one was in. Example: If the old ATutor installation was in /htdocs/ATutor and renamed to /htdocs/ATutor_old, then the new ATutor installation should be in /htdocs/ATutor, such that both the old and new installations are at the same directory level. On Windows you may use WinZip or WinRar, while on Unix use the command tar -zxvf ATutor-version_number.tar.gz. Once extracted, an ATutor directory will be created alongside your old ATutor directory. Open a web browser and enter the address to your new installation,, then follow the step-by-step instructions.

Steps for Upgrading ATutor

Important: It is highly recommended that you backup your old ATutor database before attempting an upgrade.

The following eight steps describe the upgrade process as they are presented by the ATutor installer:

  1. Locate Old Version
    Specify the directory name of the old ATutor installation you wish to upgrade (e.g. ATutor_old). The new and old ATutor directories must be at the same directory level.
  2. UTF-8 Conversion (1.6+)
    If you have not already, you are strongly advised to backup you database before completing this step. If ATutor is being upgraded from a previous version that was not using UTF-8 language packs, options will be provided to convert the database to UTF-8 all-at-once, used for single language ATutor installations, or to convert on a course-by-course basis, used if courses in different languages are present on the system. If the system is already setup with UTF-8, you'll skip this step. NOTE: This step can take a very long time for installations with many courses
  3. Database
    The upgrade will use the old version's settings to connect to the database and then update the old database tables with any changes to bring them up to date with the new version.
  4. Preferences
    In some cases, the newer version will introduce new configuration options and preferences that have to be set or confirmed. Review the Preferences and modify them if necessary.
  5. Directories
    Create a content directory , preferably outside your web server's document directory for added security, and set permissions to make the content directory writable (chmod a+rwx content). On a Unix machine you will need to manually change the permissions on the content directory during this step, if you are using a directory other than the one used in the version of ATutor being upgraded. No action is usually required on a Windows server, though in some circumstances Windows users may need to adjust the properties of the specified files and directories to make them writable. Copy the path of the directory into the text box provided. Ensure there are no shortcuts (Windows), or symbolic links (Unix) are contained in the path. The path can be the same as that to the content directory use in the version being upgraded from if the directory is outside the old ATutor installation.
  6. Save configuration
    Before reaching the final step the include/ file needs to be writable, otherwise an error will appear. Follow the instructions on the screen if the file permissions need to be changed (chmod a+rwx include/ Once your upgrade is complete and you have confirmed it was successfuly, you should set the configuration file back to read only to secure it (chmod a-w include/
  7. Content Files
    All the old course content files and chat messages will be copied over to the new installation. Depending on the size of your old installation, this process may take a few seconds to several minutes or more to complete.
  8. Submit Usage Information
    To assist the development team in serving the ATutor community, submit some basic information collected about the system you are running. All information is private. Though you are encouraged to list the location of your ATutor installation, you may remain anonymous by choosing not to submit the URL to your ATutor server along with the system information during this step.
  9. Done!
    ATutor upgrade has been successful and you may now log-in with your personal account or your administrator account.
Previous Chapter: New Installation
Next Chapter: Administrator Home
$LastChangedDate: 2008-01-31 15:24:18 -0500 (Thu, 31 Jan 2008) $
All text is available under the terms of the GNU Free Documentation License.