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:

  • 2GHz Intel Pentium 4, Intel Xeon, AMD Athlon or equivalent processor
  • 512 megabytes 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 500 megabytes
  • Network connection with at least 512kb upstream capacity
  • Suitable operating systems:
    • Microsoft Windows NT / 2000 / XP / 2003
    • Linux, 2.4 or later kernel is recommended
    • FreeBSD, 5.2 or later stable version is recommended
  • 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 or later. PHP 5 is not currently supported.
    • 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.

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.

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

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

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.

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.)

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. Modify the grant.sql file if you do not wish to use the default MySQL user and password. This is recommended if the server is not situated on a secure network. If you do modify the defaults, ensure you 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.
  5. Run the grant.sql file in MySQL with root privileges. This script creates the necessary grants and the required privileges for the application's database user.
  6. 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"
  7. 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
  8. 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)
  9. 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.
  10. 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.