ATutor Installation

The installation and upgrade processes are made up of seven steps each. Each step must be completed successfully without any errors to be able to advance to the next step. You will not be able to use ATutor if the last step is not reached successfully. Note that the terms directory on Unix, and folder on Windows, are used interchangeably.

Looking for ATutor pre-1.3.1 or ATutor 1.4.2+ installation instructions?

• Before You Begin
• System Check
• Fresh Installation
• Upgrading an Existing Installation

Before You Begin

Please review the requirements section before attempting to install ATutor.

Installing on a Unix machine requires some knowledge of file and directory permissions. You will be asked to create a content directory and set permissions for the directory, and for the include/config.inc.php file, so the web server can write to them. If the permissions are not already set to allow writing to the content/ directory, and to the include/config.inc.php file, the install process will produce errors. At this point set the permissions on the listed files/directories as described below, then resubmit the step until the error messages go away.

• Changing Unix file permissions from shell prompt: chmod a+rwx filename or chmod a+rwx directoryname. Administrator may alternately use octal numbers to set permissions (i.e. chmod -R 777 directoryname).
• Changing Unix file permissions from an FTP client: Many FTP clients allow you to change a file's permissions. The option may be labled as "Unix Permissions", "CHMOD", or simply as "Properties" or "Attributes" and will display a window with Read, Write, and Execute checkboxes for Owner, Group, and World; checking the appropriate boxes will change that file's permissions.
• Changing Windows file permissions: Right click on a file or folder, select Properties, then check or uncheck the Read-only box.

System Check

On the introduction screen the installer checks that your system has all the requirements needed to run ATutor. Review the feedback, and make adjustments to your system if necessary, and when all requirements are met, start the Install or Upgrade process. Don't be concerned if the MySQL version is listed as Unknown.

Fresh Installation

Download the latest version of ATutor and extract it into a web-enabled directory. On Windows you may use WinZip or WinRar, while on Unix you will have to use the command tar -zxvf ATutor-version_number.tar.gz. Once extracted, an ATutor directory will be created. Open a web browser and enter the address to your installation, http://your_server.com/path_to_atutor/ATutor/, then follow the step-by-step instructions.

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

1. Terms of Use
   The usage of ATutor is restricted by the GNU General Public License (GPL). Your agreement with the GPL is required if you wish to use ATutor. See the Licensing section for more details.
2. Database
   ATutor requires a MySQL database to function. Enter the required details needed to connect to your database in Step 2 of the installation process. The optional Table Prefix (e.g. "AT_") option allows ATutor to share an existing database with other applications and tables. The ATutor installation script will attempt to create the database that is defined in Step 2, if it does not already exist. This requires that your MySQL user account has permission to create databases, and permission to create tables. If this step fails, contact your system administrator to have your MySQL account upgraded to allow creation of new databases, or ask your administrator to create the database for you. Return to the installation after the database has been created, or your MySQL account upgraded, enter the database name into the approriate field in Step 2, then the installation script will insert the ATutor tables.
3. Administrator Account & System Preferences
   The Administrator account is used for managing ATutor user accounts and courses. The System preferences affect hosted courses and the general operation of ATutor.
4. Personal Account & Defaults
   The personal account can be used to enroll into or create courses, it does not have any special privileges. At this step you may also choose to create a personal instructor account along with the basic Welcome course.
5. Directories
   Create a content directory, preferably outside your web server's document directory for added security, and set permissions as described above. On a Unix machine you will need to manually change the permissions on the listed files and directories in this step. 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) contained in the path.
6. Save configuration
   Before reaching the final step the include/config.inc.php file needs to be writable, otherwise an error will appear. Follow the instructions on the screen if the file permissions need to be changed
7. Submit Usage Information
   To assist the development team in serving the ATutor community, submit some basic information 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 during this step.
8. Done!
   ATutor installation has been successful and you may now log-in with your personal account created in Step 4, or the administrator account created in Step 3.

Upgrading an Existing Installation

Please note that Release Candidates (RC) and ATutor 1.0 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).

Important considerations before upgrading

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 the updated language pack is not available, you might volunteer to help finish any remaining language that needs to be translated. See the Translator Documentation for more details. If you have made custom changes to 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.

It is highly recommended that you backup your old ATutor database. Although it is unlikely anything will go wrong, there is always a chance.

Before starting the upgrade, rename or move your old ATutor directory. This creates a backup of the current ATutor installation, which you can revert to if something goes wrong during the upgrade. 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 moved 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, http://your_server.com/path_to_atutor/ATutor/, then follow the step-by-step instructions after pressing the Upgrade button.

Upgrade Steps

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. 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.
3. 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.
4. Directories
   Create a content directory , preferably outside your web server's document directory for added security, and set permissions as described above. On a Unix machine you will need to manually change the permissions on the listed files and directories in 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) 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.
5. Save configuration
   Before reaching the final step the include/config.inc.php file needs to be writable, otherwise an error will appear. Follow the instructions on the screen if the file permissions need to be changed
6. 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.
7. Submit Usage Information
   To assist the development team in serving the ATutor community, submit some basic information 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 during this step.
8. Done!
   ATutor upgrade has been successful and you may now log-in with your personal account or your administrator account.