The ClaSS Installation FAQ

Stuart T. Johnson



  

Revision History
Revision 0.1.32005-11-22

ClaSS (ClaSS Student System) is a complete student tracking, reporting and information management system for schools. This document is intended to compliment the README to be found in the install directory of the ClaSS application package. This FAQ will be of use to any person attempting to install or upgrade the ClaSS application on a web-server (if you already have a working installation you should refer to The ClaSS Administrator's Guide).


Table of Contents
1. Pre-Installation Preparations?
1.1. How do I install ClaSS?
1.2. What server is needed to run ClaSS?
1.3. What versions of PHP, MySQL etc. is ClaSS compatible with?
1.4. How do I get the PEAR libraries for PHP?
2. Solving Error Messages
2.1. Warning: mysql_query(): Access denied for user 'stj'@'localhost' to database 'classtest' in /home/stj/public_html/classtest/class/install/install.php on line 44 Failed to create database classstest!
2.2. Warning: fopen(../../dbh_connect.php): failed to open stream: Permission denied in /home/stj/public_html/classtest/class/install/install.php on line 82 Unable to open remote file for writing.
2.3. Warning: db_connect(DB.php): failed to open stream: No such file or directory in /srv/www/htdocs/class/dbh_connect.php on line 3
3. Post-Installation Problems
3.1. The Installation script seems to have worked but why can't I login?
4. Tips for Configuring the Web-Server

1. Pre-Installation Preparations?

1.1. How do I install ClaSS?

This is answered in the README file found in the install directory of the ClaSS package application. Much of the information in this FAQ is also covered in that README.

You need the README that accompanies your version of ClaSS. For convenience only a link to the install/README for latest stable version of ClaSS is provided here:


1.2. What server is needed to run ClaSS?

You need a web-server with MySQL and PHP installed and configured. It is assumed the server is Apache running on Linux and all the documentation for ClaSS will assume that. There is no reason why ClaSS could not be made to work with some other server stack, if you do manage it then please consider adding some documentation to help others.

In addition, the PEAR libraries for PHP are used. The PEAR:DB package is essential. The PEAR:XML_Serializer package is also needed if you intend to use any of the ClaSS features that use XML such as printing reports. See Question Section 1.4 if your unsure about installing PEAR.


1.3. What versions of PHP, MySQL etc. is ClaSS compatible with?

ClaSS has been primarily developed using PHP-4.3, MySQL-4.0 and Apache-1.3. Any versions more recent than the following will probably run ClaSS without problems:

  • PHP 4.3.10-13

  • Apache 1.3.33

  • MySQL 4.1.14

  • PEAR::DB 1.6.2

It has also been found to run happily on MySQL 4.0.x and PHP 4.4.x.

ClaSS is yet to be tested with PHP5 or Apache2. Any reports of successes or failures would be gratefully accepted.

There is a reported problem with just the installation script failing invisibly on MySQL 4.0.20 (and presumably earlier versions). This is due to the MySQL timestamp format having changed. This can be fixed by editing the create_users.php script in the install directory. The format of the timestamp fields in the 'history' table and the 'user' table should be changed to read simply timestamp(14). You need to delete all of the not null, default, current_timestamp and on update attributes.


1.4. How do I get the PEAR libraries for PHP?

Normally this is not an issue as PEAR comes installed as standard with PHP (and some of its libraries) on most Linux distros. First check that they are not already installed. Try the following at the command-line:

  • pear list

If you are using a version of PHP which is 4.3 and above then the PEAR package manager should be installed and the above line will have reported back successfully with a list of packages.

If somewhere in the list of PEAR packages you see DB then ClaSS should install and run without a problem.

Otherwise you need to use the PEAR package manager from the command line. Install DB (and if they are not in the list already) the XML libraries using the following at the command-line:

  • pear install DB

  • pear install XML_Util

  • pear install XML_Parser

  • pear install XML_Serializer

If you don't have PEAR installed at all, you will not be able to run ClaSS. If you are running from a hosted server you could try sending a request to your support explaining why PHP really needs to have its PEAR libraries. I suggest you take a look at one of the following excellent articles on installing and using PEAR, its relatively straightforward: Getting Started with PEAR, Using PEAR


2. Solving Error Messages

2.1. Warning: mysql_query(): Access denied for user 'stj'@'localhost' to database 'classtest' in /home/stj/public_html/classtest/class/install/install.php on line 44 Failed to create database classstest!

The install script has failed because MySQL has refused to allow it to create the ClaSS database. this needs to be fixed before re-running the install script.

First check that the MySQL Username and Password entered on the form where correct. The MySQL account must already have been setup on the MySQL server. Note this is not the same as your login details to the machine hosting the MySQL server.

It could be that the MySQL user account you are using does not have the necessary permissions to create a new database. Or to drop an old one if it already exists. If you have the root login for the MySQL server then you could just use this. Or you can make a request to your system admin to give you these permissions.

If you are trying to install ClaSS to a hosted server then it is common for the hosting company to only provide one pre-configured database per customer. Unfortunately it is not possible (without major hacking of the code) for ClaSS to be installed to such an account. You might need to upgrade your hosting account or make a special request to your service provider explaining what you need to do.


2.2. Warning: fopen(../../dbh_connect.php): failed to open stream: Permission denied in /home/stj/public_html/classtest/class/install/install.php on line 82 Unable to open remote file for writing.

As part of the install process the script creates the file dbh_connect.php containing the MySQL connection details. The problem is the script will fail if the web-server does not have the permissions set correctly on the directory it is writing to.

Optimum solutions will be specific to each server as different web directories may be setup with various owner and group permissions. For instance, on a Debian GNU-Linux server it is sufficient to change the group of the directory to wwww-data. The following solution is not optimum and it is not at all secure. But it is simple and should work on any unix server:

  • From the command-line get into the top-level web-directory which contains the class-site directory you unpacked class.tar into. (You probably called it something other than class-site... whatever.)

  • chmod 777 class-site

  • Run the install.php script from your browser again and hopefully it works this time.

  • chmod 755 /var/www/class-site


2.3. Warning: db_connect(DB.php): failed to open stream: No such file or directory in /srv/www/htdocs/class/dbh_connect.php on line 3

The db_connect script which the install created is looking for the DB.php library and can't find it. Either PEAR is not installed at all or PEAR is installed and the path is set wrong, or your install of PEAR is missing the PEAR::DB package which you can grab separately. See Question Section 1.4 for a solution.


3. Post-Installation Problems

3.1. The Installation script seems to have worked but why can't I login?

The installation script created two default users (administrator and office). The password for these is the same as the one you supplied during the installation (you can change this later). Make sure you are using this password.

If you have phpmyadmin available on your server try connecting to the database using that. There should be the number (50) next to the database name indicating all fifty tables were correctly created. If you have less then fifty then its probably an incompatibility between your version of MySQL and the installation script. Please send a bug report to class-bug@laex.org giving the details and quote the output of the mysql -V command. See Question Section 1.3 for a possible solution.


4. Tips for Configuring the Web-Server