Technical Specifications

1. Preface

The following chapters illustrate the installation process of the Asio-Data Classroom Booking System on a Windows server. The installation process on a Linux platform is very similar, please refer to the Apache web server, MySQL database server and PHP general-purpose scripting language documentation for detailed Linux installation instructions.

The Classroom Booking System is entirely Web-based. Workstations accessing the server need only a web browser and a network connection.

2. System requirements

2.1 Server

The system requirements for a server running the Asio-Data Classroom Booking System are as follows. It should be noted that the processor and memory requirements are dependent on the number of concurrent users. The software will run fine on lower performance hardware with a reduced volume of users.

Recommendations for strenuous usage of the Classroom Booking System:

  • 2-3 GHz Intel Xeon or equivalent processor with at least 2 dedicated processor cores
  • 2 gigabytes of system memory
  • 200 megabytes of disk space for Apache, MySQL, PHP and the Classroom Booking System program files. Additional disk space is required for the program's database of bookings, facilities, companies and personnell. Typically the total required disk space is less than 1 gigabyte
  • Network connection with at least 2 mbits upstream capacity
  • Suitable operating systems:
    • Linux, 2.6 or later kernel is recommended
    • FreeBSD, 5.2 or later stable version is recommended
    • Microsoft Windows NT / 2000 / XP / 2003
    Asio-Data recommends Linux as the operating system.
  • Software requirements:
    • Apache HTTPD server, both versions 1 and 2 will be fine. Microsoft IIS is not supported.
    • MySQL 4.0 or later RDBMS.
    • PHP 4.3, 5.0 or later. Both PHP major versions (4 and 5 up to 5.3) are supported.
      PHP after minor version 5.3 is incompatible with AsioEduERP versions before v11.20. Please use the latest version 5.2 instead with older versions.
    • For Linux/Unix, sending email requires a properly configured and functional command-line "mail" utility

2.2 Workstations

All thats required to use the Asio Classroom Booking system on a work station is a web browser.

Asio Classroom Booking System is tested to work on Internet Explorer 6 browsers or above and Mozilla/Firefox browsers.

For administration and billing functions, Internet Explorer 6, 7 or later or Firefox 3.0 or later is recommended. There is a HTML rendering engine issue that affects some Firefox 2.0 branch browsers when printing multiple invoices.

3. Apache web server

Apache is a freely-available web server available for the majority of popular operating systems. The installation packages can be downloaded from http://httpd.apache.org/dist/httpd/binaries/

Please note that on some NT platforms the Apache installation program may require prior installation of 'Windows Installer'.

During installation of the Apache web server, set your organizations domain properly (e.g. www.myorganization.org) and set the computers name as asp.myorganization.org (replacing 'myorganization.org' with your appropriate domain dame)

On the next screen, select the installation mode as 'Complete'.

After Apache has been installed, you can begin installing the PHP module.

Additional configuration

It is recommended that you enable the AllowOverride -setting in Apache to allow configuration changes to be made using .htaccess files. This enables more convenient run-time changing of PHP configuration directives.

4. PHP support for Apache

PHP can be downloaded free-of-charge from http://www.php.net/downloads.php/. You should only use version PHP4 with the Asio-Data Classroom Booking System, PHP5 is not currently supported.

We recommend downloading the PHP Installer for Windows platfoms to ease the installation process.

You must set Apache's default document directory to C:\ASIO\HTTPD. To do this, select "Configure" from Apache's program group and search for 'DocumentRoot' in the opened file. Set this to C:\ASIO\HTTPD. In the same file, find the text Directory "C:\Program files\Apache Group......." and change it to C:\ASIO\HTTPD.

Ensure the server port in use is not the default one (80). The port parameter is located at the beginning of the configuration file.

  • Add the following line to the configuration file (at the same location where other "LoadModule" lines are located): 
'LoadModule php4_module c:\php\sapi\php4apache.dll'
  • Add the following two lines to the configuration file (at the same location where other "application\x-xxx" strings are located)
    AddType application\x-httpd-php .php .phtml
    AddType application\x-httpd-php .php3 .phtml

5. PHP module

Unpacking and installation for Windows NT and Apache

Start the PHP Installer and select "Standard" as the installation type. On the following screen you must provide a name for your SMTP mail server. You may write anything you want in the 'From' address. The e-mail settings are only important if you are going to run PHP scripts that send e-mail, (e.g. booking confirmations).

On the following screen, select Apache as the server type.

It's possible the installer may not have installed all the required files even though you have configured the module correctly. Unpack the PHP package to the directory C:\PHP but do not replace any existing files!

Copy the file PHP4TS.DLL from C:\PHP to your Windows SYSTEM subfolder (C:\WINNT\SYSTEM or similar). In order for all changes to take effect, restart Apache.

Additional configuration

When PHP has been installed, go to the root directory of your Windows system (usually C:\WINNT) and open the file php.ini with a text editor (notepad, for example). For Linux and Unix systems the php.ini is usually located in the /etc/ directory, but this can vary between distributions. Locate the row

error_reporting = E_ALL; display all errors, warnings and notices

and change it to the following:

error_reporting = E_COMPILE_ERROR|E_ERROR|E_CORE_ERROR

For PHP 5.3 please use the following error_reporting

error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT & ~E_NOTICE

Then locate the row "register_globals" and ensure the setting is enabled ("On") and not disabled ("Off")

Note! The register_globals -setting is no longer required in AsioEduERP v12.00 and later. You should keep this setting Off on PHP installations 5.3 and later to prevent deprecation errors being logged.

You may also want to change the setting "max_execution_time" to reflect the maximum time the program is allowed to run when undertaking long operations (e.g. importing large Untis-files). PHP's default is 60 seconds, however we recommend a value of 600 or more.

If you are using other default encoding than ISO-8859-1 in Apache, uncomment the following lines in php.ini to make sure that PHP content is treated as ISO-8859-1 encoded:

default_mimetype = "text/html"
default_charset = "iso-8859-1"

If you plan to use email file attachment sending functions in the application, you should make the following changes:

safe_mode = Off
file_uploads = On
upload_max_filesize = 16M (or other suitable maximum attachment file size)
post_max_size = 16M (should be at least equal to the maximum attachment file size)

Depending on server load, it might be a good idea to adjust the output_buffering directive. Instead of "On" you should use a numerical value, which represents the maximum size of the output buffer. Value "4096" is recommended.

The Magic Quotes setting should not be used. It can be turned off by using the following settings found in php.ini:

magic_quotes_gpc = Off
magic_quotes_runtime = Off
magic_quotes_sybase = Off

For production environments, you should turn the display_errors setting to Off. This prevents the error messages from being shown to the user. AsioEduERP v12.00 adds two new server_settings switches to control how database errors are shown to the user (is_hide_db_errors, is_show_db_errors_superuser). See the server_settings.php file for more info.

For PHP 5.3 please do the following additional configuration.

date.timezone = EET

Replace EET with the appropriate time zone setting (e.g. EET for Finland, GMT for United Kingdom...).

6. MySQL database

MySQL is an open-source SQL-database and it is available for Windows operating systems and most Unix/Linux platforms. We recommend MySQL version 4.0. It can be downloaded from http://dev.mysql.com/downloads/

Using MySQL with non-GPL software such as the Asio-Data Classroom Booking System requires the purchase of a commercial license, (e.g. MySQL's Classic license). For more information, see https://order.mysql.com/

Installation is easy: just unpack the installation package and install the software to its default directory: C:\MYSQL\

MySQL versions 4.1 and later default to INNODB storage engine and UTF-8 charachter encoding, both of which are not recommeded with Asio software. (You can use UTF-8 encoding if you need it, but it will negatively affect the performance of the database, and can cause minor incompatibility issues when importing non-UTF-8 database dump files.)

Turn off INNODB and UTF-8 by following the instructions below:

  1. Locate the MySQL configuration file (my.ini in Windows, my.cnf in Unix versions) and open it into a text editor
  2. Find the "default-character-set" directive from beneath the [mysqld] section and change it's value from "UTF8" to "latin1"
  3. Restart MySQL if it was already running to put the changes into effect. Please note that the changes take effect only in new databases created after the configuration change.

To ensure that MySQL was installed as an NT service, start the command prompt, navigate to C:\MYSQL\BIN and enter the commands mysqld-nt --remove mysqld-nt --install

Finally restart the MySQL service from the control panel.

If you are using MySQL in an open network and with Windows please note: MySQL has a default root account with no password. You should make sure that the database server cannot be accessed using this account from any non-trusted network host. We recommend that you only enable local connections to the MySQL server. This can be done by changing all values of the Host column in the mysql.user table to "localhost". The other alternative is to change the password for the root account.

If you use a MySQL version 4.1 or later, you'll need to run the following query in MySQL after installing the Asio software in order to make the database compatible with PHP: SET PASSWORD FOR 'database_user_name'@'localhost' = OLD_PASSWORD('database_password');

(Replace "database_user_name" and "database_password" with the values you used during the installation.)

Additional configuration tips for optimizing MySQL performance with Asio applications:

  • Please use the default MyISAM database engine for all tables. Despite having only table-level locks and no transaction support, this database engine does give a slight performance advantage in Asio applications.
  • If you have any spare memory on your server, you should enable MySQL query cache. The performance of the Asio application depends on execution of large numbers of very simple, well-indexed queries. Suitable query cache size for moderate use is 32 megabytes, but if you can spare it, you may increase the cache size up to 128 megabytes.
  • If you are using MySQL version 5.1 or later, check the value of the sql_mode option in the MySQL configuration file. In some versions, the default value is as follows:
    sql-mode="STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"
    This mode is incompatible with the Asio application. Change the line in the configuration file to the following and restart MySQL:
    sql-mode=""

7. Installing the Asio application

Instructions

Here are the step-by-step instructions for installing the Asio-Data Classroom Booking System. It is assumed that Apache, PHP and MySQL have been successfully installed, and the installion package containing the necessary files has been unpacked somewhere on the server.

  1. Extract the application's program files into the document root folder (/var/www will be used as an example in these instructions), or into a folder of your choice below the document root.
  2. Log on to MySQL as super-user and enter the following commands:
    create database asio;
    create database xxxxx; (The database name xxxxx will be given to you before the installation.)
  3. Check that there is an entry corresponding to your organization in the table yritys_p.
  4. Create a database user for the application, unless you already have a MySQL account in place for the Asio application. The syntax for creating a new user in MySQL is:

    grant all privileges on *.* to USERNAME@localhost identified by 'PASSWORD' with grant option;

    (substitute USERNAME and PASSWORD with appropriate values)

    After creating an account, make the corresponding changes at the end of the application's run-time configuration file which is located at /var/www/inc/server_settings.php. You will need to specify the database user name and password for the application. The configuration directive is found in the beginning of the file, within the first few lines.
  5. Import the databases into MySQL. There are a minimum of two databases, a default one called asio and the user organization's own database(s). The command-line syntax for import is as follows:
    "mysql database_name < dump_file_name.sql"
  6. If you intend to use an external authentication module, copy the correct implementation as file inc/ext_auth.php. The following modules are available:
    • Asio school administration software, file inc/ext_auth.php.asio
    • Microsoft Active Directory, file inc/ext_auth.php.ad
    • Shibboleth, file inc/ext_auth.php.shib
  7. The next phase is to set up the server-related configuration for the software. This configuration is read from the file inc/server_settings.php. You should check at least the following settings in the server settings file:
    • $db_user = Database user ID
    • $db_password = Database password
    • $ext_udb_config = Settings for the external authentication module.

      The contents and the data structure for these settings depends on the used external authentication method. The settings are documented below:
      • Asio school administration software:
        • "interface" = HTTP URL for the PL/SQL interface module of the Asio school administration software
      • Microsoft Active Directory.
        (A separate document detailing installation and configuration instructions)
      • Shibboleth.
        (A separate document detailing installation and configuration instructions)
  8. If the installation package came with a database synchronization script named "synchonize.php", you should run it according to these instructions:
    • If you changed the database connection parameters: modify the mysql_connect row in the beginning of synchronize.php as you did with the server_settings.php file
    • Copy the file synchronize.php to the www-server, then open it using a www-browser
    • Click the "perform operations" link at the bottom of the page
    • If the synchronization was successful, you'll see a notification page
    • You may delete the synchronize.php file from the server after the synchronization has been successfully completed.
  9. If you are planning to use the picture upload functionality of the facility administration programme, and if you installed the software on a Linux/Unix system, it is necessary to set proper access permissions for the picture upload subdirectory. This can be done via shell by giving the following command in the subdirectory that you extracted the program files into:

    chmod -R ugo+w kokvar/tilakuvat

Instructions for migrating the software onto a new server

Here are the step-by-step instructions on how to migrate the Asio Classroom Booking System onto a new server. It is assumed that you have the installation packages of the desired version of the software at hand. You will also need the database synchronization script, synchronize.php. If any of the aforementioned items are unavailable, please contact Asio-Data.

  1. Log into the old server and export the current production databases by entering the following commands. The database name xxxxx is the same you used during the first installation.

    mysqldump Asio -K --quote-names --compatible=mysql323 -uUSER_ID -pPASSWORD > Asio.sql

    mysqldump xxxxx -K --quote-names --compatible=mysql323 -uUSER_ID -pPASSWORD > xxxxx.sql

  2. Create the corresponding new databases to the new server by entering following commands in MySQL:

    CREATE DATABASE Asio;

    CREATE DATABASE xxxxx;

  3. Copy the database export files to the new server and import them into the new databases using the following commands:

    mysql Asio < Asio.sql

    mysql xxxxx < xxxxx.sql

  4. Install the program files of the Asio Software and synchronize the databases using the standard installation instructions above. Skip the database import phases 2 and 5 as they have already been done.