                       ==================================
                        ILIAS open source - Installation
                       ==================================

          Author: Boris H. Schuermann 

          $Id: INSTALL,v 1.73.2.4 2006/10/26 17:29:15 akill Exp $



Table of Contents

1. Introduction

2. First time installation

   2.1 Where to install ILIAS

   2.2 First steps

   2.3 Installing required third-party software

       2.3.1 Libraries & utilities

       2.3.2 MySQL / PHP / Apache

   2.4 Installing ILIAS 3

3. Updating ILIAS 3

   3.1. Instructions for updating from ILIAS 3.4.0 or 3.4.1 if MySQL 4.1.x has
        been used.

4. Migrating from MySQL 4.0.x to MySQL 4.1.x

Appendix A: Note on using Apache 2


1. I N T R O D U C T I O N

ILIAS is a web-based Learning Content Managament System (LCMS) developed with
the server-side scripting language PHP and distributed as Open Source software
under the GNU General Public License (GPL). It uses the MySQL database and the
Apache web server. The main target operating system is Linux, but ILIAS may also
be run on other Unix systems and even Windows.

This document describes the installation of ILIAS 3 with the all
software required for running an ILIAS system. The procedure has been tested
under RedHat and Debian. With minor modifications it should also apply to
other Linux distributions, Solaris and other Unix systems.

The following third-party software is necessary for running ILIAS. Release
numbers refer to the version tested and recommended for use with ILIAS. Like
ILIAS itself, all these programs are available as Open Source software.

    - Apache 1.3.29            http://www.apache.org
    - MySQL 4.0.18             http://www.mysql.com
    - PHP 4.3.6                http://www.php.net
    - GD (libgd) 2.0.15        http://www.boutell.com/gd/
    - Zlib (libz) 1.1.4        http://www.gzip.org/zlib/
    - libpng 1.2.5             http://www.libpng.org
    - IJG JPEG (libjpeg) 6b    ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
    - ImageMagick 6.0.1        http://www.imagemagick.org
    - Info-ZIP (Zip/UnZip)     http://www.info-zip.org
    - libxml2 2.6.9            http://www.xmlsoft.org
    - libxslt 1.1.6            http://www.xmlsoft.org
    - libexpat 1.95.7          http://www.libexpat.org (not needed for PHP5)
    - Sablotron 1.1            http://www.gingerall.com (not needed for PHP5)

The recommended releases can also be downloaded from the ILIAS open source web
site: http://www.ilias.uni-koeln.de/ios/source.html

ILIAS should also run with PHP 5.x.x. If you are using PHP 5 libexpat and
Sablotron are not needed. Some problems were found using PHP 4 and the Sablotron 
library, so it is highly recommended to use PHP 5 if possible.

Please read the MySQL chapter if you plan to migrate from an existing 
MySQL 4.0.x to MySQL 4.1.x.

Please see chapter 2.5 for information about optional software.

In this guide it is assumed that none of the programs above are installed on
your system. However, many Linux distributions install libraries and programs
such as libz, libgd, libjpeg, libgd, ImageMagick and Zip/Unzip by default. If
installed properly it might not be necessary to install these packages along
with ILIAS again.

If your installation of PHP, Apache or MySQL must meet additional requirements
or if you prefer different versions of these components, you may of course
configure the software yourself. Just make sure that your own configuration
supports all components used by ILIAS.

Prior to compilation your system should at least include the following programs:
gcc,, g++, GNU make, autoconf (>=2.13), automake (>= 1.4), libtool (>=1.4.3),
perl(>=5.0), gdbm, bison,(>=1.25), flex, GNU tar, libncurses.

Some functions in ILIAS require outgoing Internet mail. Therefore a sendmail
daemon should run on your system and outgoing connections should be allowed
on port 25.

General advices on compiling the software packages:

    - For better readability, long command lines are broken down to multiple
      lines. In this case, a backslash at the end of a line indicates that the
      next line is to be considered a continuation.
    - Please follow the installation steps in the given order. Some steps rely
      on previously issued commands.
    - If the configure/make process fails or gets interrupted, it is a good idea
      to remove the complete source directory of the program to be built and
      start a new attempt with a source directory freshly extracted from the
      corresponding tarball. In any case you should at least delete the file
      'config.cache' if it exists.
    - To facilitate installation you may use the Cut & Paste functions of your
      system to enter the commands in this document into your console. If you
      load this document into an editor capable of selecting colums such as
      'nedit' this may even work for entire command sequences with multiple
      lines separated by a backslash.



2  F I R S T   T I M E   I N S T A L L A T I O N


2.1 Where to install ILIAS

ILIAS will often be installed within an existing server environment. In this
case the administrator of such a system will have to make sure, that the web
server supports the PHP scripting language with all libraries required and that
it can interact with a MySQL database server.

The instructions herein assume that you do not have any of the software
packages required for running ILIAS installed on your server. Following them
all these programs will be built from their source code and then be installed
under /opt/ilias/. This way the programs will normally not interfere with
packages already installed on your system and can easily be removed.

Beside the third-party software also ILIAS itself and all data directories
(including the ILIAS web space, the MySQL databases, places for file uploads,
logfiles etc.) will be located under /opt/ilias/. For just trying out ILIAS
this solution is fine but if you intend to use ILIAS in a production environment
we recommend to seperate the program binaries from the user data, e.g. to
facilitate backup and administration tasks.

You could for instance install all third-party software under /opt/ilias/ and
create a directory /srv/ilias/ for the ILIAS web space and all other ILIAS
related data (except for logfiles which should ideally go to /var/log/ilias/).
The subdirectories under /srv/ilias/ could be the same as the ones which are
created under /opt/ilias/ during the installation process described in this
document. The /srv directory (which should be a mounted partition, as it could
swallow up your disk space and thus cause problems when being part of your
root partition) is not yet part of the Filesystem Hierarchy Standard (FHS) in
its current version 2.2. But there have been proposals to add it to the FHS and
some Linux distributions already use /srv/www as the default location for their
web space. Since standardization efforts are still going on, our recommendation
might be a temporary one.

When compiling the components necessary to run ILIAS from source you may easily
specify their installation location using an appropriate '--prefix' directive.
Library locations that you specify must also reflect your system environment. It
would be fine (and also in compliance with the FHS) to install everything
including the data directories under /usr/local. That is also the default
location where most source distributions will install themself in the build
process. Of course you may also use symbolic links to change the location of
the directories involved.

In many cases you may want to use binary packages like RPMs instead of compiling
the software yourself.  If these packages meet the requirements resulting from
the configure options in this document, this should normally work fine. You
would just have to put the ILIAS scripts into your web space and do some
adjustments to the Apache, PHP and MySQL configuration files as well as some of
the pathes in the ILIAS system settings.



2.2 First steps

If you choose to install ILIAS according to our recommendation, the directories
below need to be created manually:

Directories where third-party components will be located:

    mkdir /opt/ilias
    mkdir /opt/ilias/bin
    mkdir /opt/ilias/config
    mkdir /opt/ilias/include
    mkdir /opt/ilias/lib
    mkdir /opt/ilias/libexec
    mkdir /opt/ilias/man
    mkdir /opt/ilias/man/man1
    mkdir /opt/ilias/man/man5
    mkdir /opt/ilias/src
    mkdir /opt/ilias/src/tarballs

Directories for the ILIAS web space and all ILIAS related data:

    mkdir /opt/ilias/data
    mkdir /opt/ilias/log
    mkdir /opt/ilias/log/ilias
    mkdir /opt/ilias/mysqldata
    mkdir /opt/ilias/www

Copy all source tar files to /opt/ilias/src/tarballs. GNU-Tar will extract the
source files into separate directories in /opt/ilias/src:

    cd /opt/ilias/src
    tar -xzf tarballs/zlib-1.1.4.tar.gz
    tar -xzf tarballs/jpegsrc.v6b.tar.gz
    tar -xzf tarballs/libpng-1.2.5.tar.gz
    tar -xzf tarballs/gd-2.0.15.tar.gz
    tar -xzf tarballs/ImageMagick-6.0.1-2.tar.gz
    tar -xzf tarballs/zip23.tar.gz
    tar -xzf tarballs/unzip550.tar.gz
    tar -xzf tarballs/mysql-4.0.18.tar.gz
    tar -xzf tarballs/apache_1.3.29.tar.gz
    tar -xzf tarballs/php-4.3.6.tar.gz
    tar -xzf tarballs/libxml2-2.6.9.tar.gz
    tar -xzf tarballs/libxslt-1.1.6.tar.gz
    tar -xzf tarballs/expat-1.95.7.tar.gz (PHP4 only)
    tar -xzf tarballs/Sablot-1.1.tar.gz (PHP4 only)

The ILIAS software, its documentation and the web space directory structure is
stored in:

    ilias-3.7.3.tar.gz

The ILIAS tarball may also reside in /opt/ilias/src/tarballs/. After all third-
party software has been installed it can directly be extracted into the web
space.



2.3 Installing required third-party software


2.3.1 Libraries & utilities

If not already available on your system, the following libraries and utilities
must be installed:

    - ZLib (libz, compression library required by various other programs)
    - GD-Library (libgd, graphics library used by PHP)
    - IJG JPEG-Library (libjpeg, graphics library used by ImageMagick)
    - libpng (PNG graphics library used by libgd and Imagemagick)
    - ImageMagick (graphics tool used by ILIAS for Image format conversion)
    - Info-ZIP (Zip/UnZip tools used for compressing offline courses)
    - libxml (GNOME XML library, required by PHP for XML DOM parsing. At least a
      version >= 2.4.14 is required)
    - libxslt (GNOME XSLT library, required by PHP for using DOM XSLT features)
    - Expat (XML parser used by the Sablotron XSLT processor) (PHP4 only)
    - Sablotron (XSLT processor) (PHP4 only)

The programs can be compiled and installed using the command sequences shown
below. However, you may decide to install them in different locations such
as /usr/lib or /usr/local/lib for the libaries by changing the configure option
--prefix.


(a) Zlib

        cd /opt/ilias/src/zlib-1.1.4
        ./configure --prefix=/opt/ilias
        make
        make install


(b) IJG JPEG-library

        cd /opt/ilias/src/jpeg-6b
        ./configure \
        --prefix=/opt/ilias \
        --enable-shared \
        --enable-static
        make
        make test
        make install


(c) libpng

    libpng does not come with a configure script. You have to pick a Makefile
    suitable for your system in the ./scripts subdirectory. In the following it
    is assumed that the target system is Linux.

    To install libpng under /opt/ilias the 'prefix' (default: /usr/local) in the
    Makefile must be changed. In addition the location of libz should be properly
    specified: 'ZLIBLIB=/opt/ilias/lib' and 'ZLIBINC=/opt/ilias/include'. Both
    settings can be changed manually with a text editor such as 'vi' or by using
    the 'sed' commands shown below.

        cd /opt/ilias/src/libpng-1.2.5

    Now you can either edit Makefile to adjust the prefix:

        cp scripts/makefile.linux Makefile
        vi Makefile

    or you can use 'sed' to directly create a modified Makefile:

        sed \
        -e 's/\/usr\/local/\/opt\/ilias/g' \
        -e 's/ZLIBLIB=..\/zlib/ZLIBLIB=\/opt\/ilias\/lib/g' \
        -e 's/ZLIBINC=..\/zlib/ZLIBINC=\/opt\/ilias\/include/g' \
        scripts/makefile.linux > Makefile

        make
        make install


(d) GD-Library

    From release 4.3.0 PHP comes with a bundled libgd. Like all standard libgd
    versions >= 1.6.x the bundled version does not allow the creation and
    manipulation of GIF images due to the patent problem concerning the use of
    the LZW algorithm.

    For most purposes the bundled libgd is sufficient since ILIAS does rely on
    GIF support by libgd anymore. A libgd supporting the GIF format would only
    be necessary if you intend to create clickable maps based on GIF files with
    the Imagemap editor being part of the ILIAS authoring tool.

    The patent on the LZW algorithm held by Unisys Corporation has already
    expired in the United States as well as in some other countries.(see
    http://www.unisys.com/about__unisys/lzw/ for details). So depending on where
    you live you may legally use a patched libgd with GIF support. Patched libgd
    are available from an Australian website: http://www.rime.com.au/gd/

    In case you want to build and use an external libgd please follow the steps
    below which also apply to patched versions:

        cd /opt/ilias/src/gd-2.0.15
        ./configure \
        --prefix=/opt/ilias \
        --with-jpeg=/opt/ilias \
        --with-png=/opt/ilias
        make
        make install

    Please note that opposed to current PHP versions some older PHP 4 releases
    cannot properly be compiled with newer libgd. A patch that solves the problem
    is available for PHP 4.2.3 and libgd >= 2.0.8 is available here:
    http://www.boutell.com/gd/phppatch.html

    You may also use an older libgd, for example version 1.8.4. The latter does
    not come with a configure script. To adapt it to your system you would have
    to modify its Makefile manually. In particular the INSTALL_ pathes may have
    to be adjusted.  Since libgd requires libz, libpng and libjpeg you may also
    have to specify the exact locations of these libraries in the LIBS= section
    of the Makefile (e.g. by entering '/opt/ilias/lib/libz.a' instead of '-lz').


(e) ImageMagick

        cd /opt/ilias/src/ImageMagick-6.0.1
        ./configure \
        --prefix=/opt/ilias \
        --without-perl \
        --enable-lzw \
        --enable-shared
        make
        make install

    If you do not have X installed on your system you must use the configure
    option '--without-x' in addition.

    At the end of the configure process a configuration summary is displayed.
    Please check if 'yes' is shown as the configured value for JPEG and PNG. If
    not, ImageMagick could probably not find the previously installed libjpeg
    and libpng and you may experience problems when doing image manipulations
    in ILIAS such as editing a clickable imagemap or when thumbnail pictures
    are being created. This can be solved by setting the variables LDFLAGS and
    CFLAGS to include /opt/ilias/lib and /opt/ilias/include before you execute
    the 'configure' script.

    Note on building ImageMagick under SuSE Linux: The build process might
    fail with an error message claiming that the file 'byteorder.h' cannot be
    found in /usr/include/sys/. Under SuSE it is located in /usr/include/asm/.
    Creating a symbolic link will solve the problem:

        cd /usr/include/sys
        ln -s ../asm/byteorder.h byteorder.h


(f) Info-ZIP

        cd /opt/ilias/src/zip-2.3
        make -f unix/Makefile generic
        make -f unix/Makefile install
        cd /opt/ilias/src/unzip-5.50
        make -f unix/Makefile generic
        make -f unix/Makefile install

    By default Zip and Unzip will be installed in /usr/local/bin. As the zip and
    unzip tools are generelly helpful, you may put them there. Otherwise you may
    install them under /opt/ilias by modifying the Makefile.


The following steps are only necessary for running ILIAS 3:

(g) libxml

        cd /opt/ilias/src/libxml2-2.6.9
        ./configure \
        --prefix=/opt/ilias \
        --without-python
        make
        make install


(h) libxslt

        cd /opt/ilias/src/libxslt-1.1.6
        ./configure \
        --prefix=/opt/ilias \
        --with-libxml-prefix=/opt/ilias \
        --without-python
        make
        make install


(i) Expat (PHP4 only)

        cd /opt/ilias/src/expat-1.95.7
        ./configure --prefix=/opt/ilias
        make
        make install


(j) Sablotron (PHP4 only)

        cd /opt/ilias/src/Sablot-1.1
        ./configure \
        --prefix=/opt/ilias \
        --with-expat-prefix=/opt/ilias
        make
        make install

Note: If you found that compiling PHP 4 with Sablotron dumps some 'invalid 
references' errors, please try to compile Sablotron and PHP 4 typing the string 
LDFLAGS=-lstdc++ just before the 'make' command in both cases.


2.3.2 MySQL / PHP / Apache

After the libraries and tools are set up you may install the main third-party
components:


(a) MySQL database

    IMPORTANT NOTE: ILIAS has been tested on several 4.0.x and 4.1.x. versions.
	MySQL 5.x.x are not yet supported.

    Configure & make:

        cd /opt/ilias/src/mysql-4.0.18
        ./configure \
        --prefix=/opt/ilias \
        --localstatedir=/opt/ilias/mysqldata \
        --sysconfdir=/opt/ilias/config
        make
        make install

    Now install MySQL's default databases:

        scripts/mysql_install_db

    Create link to init script:

        cd /opt/ilias/share/mysql
        chmod 744 mysql.server
        cp mysql.server /etc/rc.d/init.d/
        cd /etc/rc.d/rc3.d
        ln -s ../init.d/mysql.server S72mysql.server
        ln -s ../init.d/mysql.server K72mysql.server

    The directories containing the init script and the links to it may vary.
    Please check the default runlevel for your system in /etc/inittab. On
    Solaris systems the init scripts can usually be found in /etc/init.d, the
    links in the runlevel specific directories like /etc/rc3.d.

    It is recommended not to run the mysql daemon as root. The daemon user can
    be set in /etc/rc.d/init.d/mysql.server. On many Linux/Unix system you may
    create a daemon user account and group by entering:

        groupadd mysql
        useradd -g mysql mysql

    File ownership for /opt/ilias/mysqldata needs to be set accordingly:

        chown -R mysql /opt/ilias/mysqldata
        chgrp -R mysql /opt/ilias/mysqldata

    Create a MySQL configuration file and link to it:

        cd /opt/ilias/share/mysql
        cp my-small|medium|large|huge.cnf /opt/ilias/config/my.cnf
        cd /opt/ilias/mysqldata
        ln -s /opt/ilias/config/my.cnf

    MySQL version 4.0.x comes with sample configuration files for different
    memory sizes (small, medium, large, huge). Please select the appropriate
    file and apply further changes to /opt/ilias/config/my.cnf according to your
    specific needs. Since ILIAS currently does not rely on InnoDB support in
    MySQL you may disable it by adding the 'skip-innodb' option to the mysqld
    section of the my.cnf file.

    Create link to error log file:

        cd /opt/ilias/log
        ln -s /opt/ilias/mysqldata/$HOSTNAME.err

    If desired you may also redirect database logging from /opt/ilias/mysqldata
    (default) to /opt/ilias/log by modifying the log-bin (or log-update) option
    in my.cnf.

    Check if MySQL daemon can be started/stopped:

        /etc/rc.d/init.d/mysql.server start
        /etc/rc.d/init.d/mysql.server stop

    Please note that unless a password has been set for the MySQL root account,
    any user can start the MySQL client with all privileges. It is advisable to
    change the password for the root account using the follwing command:

        /opt/ilias/bin/mysqladmin -u root password <password>

    If you set a password for the MySQL root account you will have to modify the
    database settings for ILIAS. Please see section 2.4 for details. You might
    also consider using a dedicated MySQL account for running ILIAS instead of
    the MySQL root account.

    For MySQL 4.0 and higher you need to grant the permission LOCK TABLES to
    the ILIAS db-user. E.g. if the ILIAS db-user 'dbuser' accesses from host
    'localhost':

        /opt/ilias/bin/mysql -u root password <password>
        mysql> grant LOCK TABLES on *.* to dbuser@localhost;

    If you are using MySQL 4.1.x and create the ILIAS database manually (ILIAS
    setup can do this for you) you have to set utf8 as character set and
    an appropriate collation for the whole database, e.g.:
    
        mysql> CREATE DATABASE ilias3 CHARACTER SET utf8 COLLATE utf8_unicode_ci


(b) Apache (preparation)

        cd /opt/ilias/src/apache_1.3.29
        ./configure --prefix=/opt/ilias


(c) PHP

    Configure & make:

		PHP 4.x.x:
		
        cd /opt/ilias/src/php-4.3.6
        ./configure \
        --prefix=/opt/ilias \
        --with-apache=/opt/ilias/src/apache_1.3.29 \
        --with-config-file-path=/opt/ilias/config \
        --with-mysql=/opt/ilias \
        --with-zlib=/opt/ilias \
        --with-zlib-dir=/opt/ilias \
        --with-gd \
        --with-jpeg-dir=/opt/ilias \
        --with-png-dir=/opt/ilias
        --with-dom=/opt/ilias
        --with-dom-xslt=/opt/ilias
        --enable-xslt
        --with-pear=/opt/ilias/lib/pear
        --with-xslt-sablot=/opt/ilias
        --with-expat-dir=/opt/ilias
        make
        make install
		
        PHP 5.x.x: (Build apache first (see (d)) an replace the directive
        '--activate-module=src/modules/php4/libphp4.a' by '--enable-so'.
		
        ./configure \
        --with-apxs=/opt/ilias/bin/apxs \
        --with-mysql=/opt/ilias \
        --with-zlib=/opt/ilias \
        --with-gd
        --with-jpeg-dir=/opt/ilias \
        --with-png-dir=/opt/ilias \
        --with-config-file-path=/opt/ilias/config
        --with-libxml-dir=/opt/ilias \
        --with-xsl=/opt/ilias
        make
        make install
		
    Newer PHP releases come with an integrated libgd which is activated by
    using the --with-gd directive. If you are using a version of PHP < 4.3.0 or
    want to build it with an external libgd you should specify the location of
    the libgd on your system, e.g. by entering '--with-gd=/opt/ilias'.

    Note: If compilation/linking fails with a compile error concerning undefined
    references in 'libsablot.so' try to set the and LDFLAGS environment variable
    using the following (bash shell) command: export LDFLAGS='-lstdc++'

    ILIAS 3 also requires additional PEAR library packages, which will not be
    installed by default when building the current PHP source distribution. At
    present, these packages are:

        - Auth
        - HTML_Template_IT
		- HTTP_Request
		- XML_RPC (if lucene search is enabled)

    They can be obtained directly from the Web using the PEAR command line
    installer that comes with PHP:

        /opt/ilias/bin/pear install Auth
        /opt/ilias/bin/pear install HTML_Template_IT
        /opt/ilias/bin/pear install HTTP_Request
		/opt/ilias/bin/pear install XML_RPC

    The default PHP configuration file must be copied to /opt/ilias/config:

        cp php.ini-dist /opt/ilias/config/php.ini

    Open the file in your favourite editor.
		
    The parameter 'memory_limit' defines the maximum amount of memory a php
    script may consume. The default value of 8M maybe to low for some ILIAS
    scripts. We recommend to set this parameter to 40M.

    There are a few more settings in php.ini that might require modification:

    - session.gc_maxlifetime

      determines how many seconds an ILIAS session may be inactive before it is
      destroyed by the PHP session management. When setting this parameter
      please take into consideration that when working with the online editor
      tool an author may remain on an editor page for a much longer time than a
      normal user, e.g. when typing a longer text. However, for security reasons
      the value should not be set too high. We recommend to set it to 3600
      seconds (= 1 hour).

    - max_execution_time

      is the maximum execution time of each script in seconds. Some of the ILIAS
      scripts generating content for offline use may run longer than the default
      30 seconds. Depending on the performance of your server we recommend a
      value of up to 180 seconds.

    - post_max_size and upload_max_filesize

      determine the the maximum upload file size. Especially when using the
      file exchange functions in ILIAS the default value might be too low and
      should be corrected. 'post_max_size' should be always some megabytes higher
      than 'upload_max_filesize'.

    - include_path

      make sure that the pear library is within your include path of php.
      if you followed the installation instruction above, just add
      '.:/opt/ilias/lib/pear'.


(d) Apache

    Configure & make:

        cd /opt/ilias/src/apache_1.3.29
        ./configure \
        --prefix=/opt/ilias \
        --activate-module=src/modules/php4/libphp4.a \
        --logfiledir=/opt/ilias/log \
        --runtimedir=/opt/ilias/log \
        --sysconfdir=/opt/ilias/config \
        --datadir=/opt/ilias/www
        make
        make install

    Link to startup script apachectl:

        cd /opt/ilias/bin
        chmod 744 apachectl
        cp apachectl /etc/rc.d/init.d/
        cd /etc/rc.d/rc3.d
        ln -s ../init.d/apachectl S70apachectl
        ln -s ../init.d/apachectl K70apachectl

    The directories containing the init script and the links to it may vary.
    Please check the default runlevel for your system in /etc/inittab. On
    Solaris systems the init scripts can usually be found in /etc/init.d, the
    links in the runlevel specific directories like /etc/rc3.d.

    Please change /opt/ilias/config/httpd.conf according to your needs, e.g. set
    a daemon user/group like 'wwwrun' (default: nobody/nobody) to run the httpd
    daemon. For PHP support include the following directives:

        DirectoryIndex index.html index.php

        AddType application/x-httpd-php .php
        AddType application/x-httpd-php .lang
        AddType application/x-httpd-php .inc

    Also please make sure that the name of your server is properly specified in
    httpd.conf. The 'ServerName' entry should either contain the DNS name of your
    server or its IP address. The line should be uncommented.

    IMPORTANT: All directories in your webspace ought to be secured properly, e.g.
    using .htaccess files. It is recommended to at least disable the directory
    option 'Indexes' in /opt/ilias/config/httpd.conf, so that someone accessing
    your web server cannot obtain listings of the files inside your web space
    directories.


2.4 Installing ILIAS 3

(a) Installing the ILIAS 3 program files

    First extract the content of the ILIAS tarball into the web space directory:

        cd /opt/ilias/www/htdocs/
        tar -xzf /opt/ilias/src/tarballs/ilias-3.7.3.tar.gz

    Please make sure your webserver has write permission to the ILIAS3 web space
    and data directories and all their subdirectories. If your webserver daemon
    user is 'wwwrun' you can use these commands:

        chown -R wwwrun /opt/ilias/www/htdocs/ilias3
        chown -R wwwrun /opt/ilias/data


(b) Running the setup script

    Open the ILIAS 3 setup script in your web browser:

        http://www.yourserver.com/ilias3/setup/setup.php

    If all 'preliminaries' are fulfilled you may click on the [Installation]
    link at the end of the page and follow the instructions. The Path to the
    ILIAS data directory must be an absolut path i.e. it should start with
    "/", e.g. "/opt/ilias/data". The directory is used for data that does not
    need to be stored within the webspace.


(c) Initial login

    After all steps are passed you may proceed to the ILIAS 3 login,
    either using the [login] link or by accessing

        http://www.yourserver.com/ilias3/login.php

    Please use the ILIAS superuser account for your first login:

        User ID: root
        Password: homer

    In the Administration -> System Settings you may continue with the further
    configuration of your ILIAS system.

    Please CHANGE THE ILIAS ROOT PASSWORD on your first login!

(d) Setting up the user agreement form

    Every ILIAS user that registers to the system must confirm a user
    agreement. You should set up your own agreement text by editing the files
    that are provided in the agreement/ directory of ILIAS. You can add
    additional language versions by creating files following the format
    agreement_<langcode>.html. If you want to provide independent agreement
    texts for certain clients, you can do this by creating a directory
    agreement in your client data directory
    '<ILIAS_ROOT_DIR>/data/<CLIENT_ID>/agreement' and to provide agreement
    files within this directory, following the naming convention above, i.e.
    '<ILIAS_ROOT_DIR>/data/<CLIENT_ID>/agreement/agreement_<langcode>.html'.

(e) Settting up the chat server

    The file chat/chatserver/install.txt explains how the chat server
    installation works.

(f) Setting up cron jobs
    
    A cron job is an automated process that operates at predefined time
    intervals. As an example, you can set up a cron job that checks your ILIAS
    installation every day at 2:00 am for limited user accounts and sends an
    email notification to users which account expires within the next 2 weeks.

    How to enable this cron job?
    Please choose one of the following configurations. If possible use
    'server based configuration'.

    Server based configuration:

    - you need write access to the file /etc/crontab
    - add the following line in /etc/crontab
    0 2 * * * APACHEUSER /usr/bin/php ILIAS_ABSOLUTE_PATH/setup/cron.php > /dev/null

    To understand this even more, I'll show you what each of the values mean for
    the above cron tab.

    0                    Minutes after the hour
    2                    Hours of the day
    *                    Days of the month
    *                    Month of the year
    *                    WeekDays of the week
    APACHEUSER           The user which runs the cron job. Should be the same as
                         the apache user (wwwrun)
    ILIAS_ABSOLUTE_PATH  The absolute path to your ILIAS installation
    
    This example executes the script cron.php every night at 2 a clock.

    Web based configuration:

    - Edit the file ilias.ini.php in the main directory of your ILIAS
    installation. And add the following lines at the end of the file:
	
    [cron]
    web_enabled = "1"
    web_pass = "my_secret"
    
    Now you can point your browser to
    "http://www.your_ilias.de/setup/cron.php?web_pass=my_secret"
    
    Note: 
    cron.php can be executed only once a day. If you want to execute it again
    (e.g for testing), you have to remove the file 
	ILIAS_ABSOLUTE_PATH/setup/cron.lock.
    If logging is enabled in your ilias installation (see main setup) each
    started cron job writes messages in your log file.


3. Updating ILIAS 3

THIS INSTRUCTIONS EXPLAIN HOW TO UPDATE FROM ANY ILIAS 3 stable version to
ILIAS 3.7.3.

BACKUP YOUR ILIAS MYSQL DATABASE, THE ENTIRE CONTENTS OF THE ILIAS WEB DIRECTORY
AND THE ILIAS DATA DIRECTORIES BEFORE DOING ANY CHANGES!

IF YOU UPDATE FROM ILIAS 3.4.0 or 3.4.1 AND ALREADY USED MYSQL 4.1.x PLEASE
READ AND FOLLOW THE INSTRUCTIONS OF CHAPTER 3.1. FIRST.

We recommend not to update from an any alpha or beta version of ILIAS 3 because
this may cause ambiguous errors in the future. Please setup any stable version
of ILIAS 3 from scratch.

For major updates (e.g. 3.5.x -> 3.6.x) the safest proceeding is, to upgrade
a copy of your productive system first and test whether everything works ok.

Please also note that major updates usually include changes in the style
sheet and template files. So if you use individual styles/skins you will have
to adopt them for the new release first. This does usually not apply for bugfix
updates (e.g. 3.5.1 -> 3.5.2). See also
http://www.ilias.de/docu/goto.php?target=pg_10797&client_id=docu

At the time being no installation script is available for updating ILIAS 3. For
this reason the ILIAS script files must be updated manually. In the following
steps it is assumed that your existing ILIAS 3 installation is located in
/opt/ilias/www/htdocs/ilias/ while the contents of the ILIAS distribution tar
file lies in /tmp/. If the locations differ on your system you may need to adapt
the commands used in the following.

Some files and directories will be replaced in the update process. They must be
removed from your ILIAS web directory. If you keep any additional files or data
that is worth to be saved in one of these directories please take all necessary
precautions. This is especially important if you have modified parts of the
ILIAS source code, the language files in ./lang/, any template files in
the templates/ subdirectories and your user agreement files in the agreement
directory. It is also recommended to save the files ilias.ini.php located in the
main ILIAS directory which contains individual settings of your ILIAS
installation and chat/chatserver/server.ini which stores the setting for the
ilias chat server. After installing the new ILIAS release you may easily restore
these files.

    cd /opt/ilias/www/htdocs/ilias
    rm *.php *.xml *.dtd *.css
    rm -r classes content css docs images include java lang layouts
    rm -r modules setup sql templates xml assessment chat tracking
    rm -r survey syntax_highlight course payment webservice ilinc link
	rm -r cron Services calendar

You may ignore any 'no such file or directory' errors because depending on
your current ILIAS installation some of the directories above may not exist on
your system.

Then extract the ILIAS distribution tar file to /tmp/ (or any other directory of
your choice). Do not simply overwrite the 'ilias' directory in your webspace!
Example:

    cd /tmp
    tar -xzf /opt/ilias/src/tarballs/ilias-3.7.3.tar.gz

After extracting the files you will find a newly created subdirectory 'ilias3' in
your tmp/ directory. Depending on the ILIAS version you are replacing you must
copy various files and directories to your ILIAS web directory:

    cd /tmp/ilias3
    cp -p * /opt/ilias/www/htdocs/ilias/
    cp -rp assessment chat classes content course /opt/ilias/www/htdocs/ilias/
    cp -rp css docs images include java lang layouts /opt/ilias/www/htdocs/ilias/
    cp -rp calendar payment setup sql survey /opt/ilias/www/htdocs/ilias/
    cp -rp syntax_highlight templates tracking xml /opt/ilias/www/htdocs/ilias/
    cp -rp webservice ilinc link /opt/ilias/www/htdocs/ilias/
	cp -rp cron Services /opt/ilias/www/htdocs/ilias/

Please ignore any 'File exists' error messages. After all files have been copied
you may remove /tmp/ilias/.

Copy your saved ilias.ini.php file to /opt/ilias/www/htdocs/ilias/.

After installing a new ILIAS 3 release you must run the setup script
'http://www.yourserver.com/ilias/setup/setup.php' and update the database of all
your clients. Select "Details" for every client in the client list and click on
the "Database" button. Depending on the size of your database the update process
may take a while.

This is especially the case for an update from 3.4.x or lower to 3.6.x because
all meta data will be converted into a new format. On big installations we
recommend to set the following values to avoid multiple restarts of the database
migration:

- Apache, httpd.conf:
  Timeout = 3600
- PHP, php.ini:
  memory_limit = 128M
  max_execution_time = 3600

If the update unexpectedly stops, please restart the update until it finishes
successfully.

After that enter your clients and execute the "Refresh Languages" command
in the language administration of the system settings ("Administration" ->
"System Settings" -> "Languages" -> "Refresh Languages").


3.1. Instructions for updating from ILIAS 3.4.0 or 3.4.1 if MySQL 4.1.x has
     been used.

Due to a problem of the UTF-8 handling in these versions it is necessary to
dump and reload the entire database. Please make a backup of your database.
Then do the following steps:

a. Determine your default client character set. Change to your mysql/bin
   directory. Open the mysql shell and enter the following command:
   > mysql ilias3
   mysql> SHOW VARIABLES like '%char%';
   mysql> exit;

b. Dump the database using this character set (e.g. latin1). The result should
   be an UTF-8 encoded file. Please note the "--skip-set-charset" attribute
   which is very important here.
   > mysqldump ilias3 --default-character-set=latin1 --skip-set-charset > ilias3.dump
   (replace latin1 with your default client character set).

c. Drop and recreate an empty database using an approriate collation, e.g.:
   > mysqladmin drop ilias3
   > mysql ilias3
   mysql> CREATE DATABASE ilias3 CHARACTER SET utf8 COLLATE utf8_unicode_ci

d. Reload the database using UTF-8 as character set:
   > mysql --default-character-set=utf8 ilias3 < ilias3.dump

e. Update ILIAS following the instructions of chapter 3.

f. Check whether all content has been migrated properly.

If you run multiple ILIAS 3.4.0/3.4.1 instances on the same database server you
have to update them all at the same time.

For big installations it might be safer to update to ILIAS 3.4.3 or 3.4.4 first
(after doing the procedure above) and then to update to ILIAS 3.6.x seperately.
The data migration from 3.4.x to 3.6.x can take a long time because all meta
data has to be converted to a new format.


4. Migrating from MySQL 4.0.x to MySQL 4.1.x

    If you want to migrate an existing ILIAS from MySQL 4.0.x to 4.1.x you
    need to do the following steps:
	
    1. Backup your database
    2. Update to ILIAS 3.4.0 stable or higher (run db migration in setup)
    3. Dump your ILIAS 3 MySQL 4.0.x database
       /opt/ilias/bin/mysqldump > ilias3.dump
    4. Update to MySQL 4.1.x
    5. Create a new ILIAS database, set the default character set to utf-8
       and the default collation to your appropriate utf-8 collation
       (see http://dev.mysql.com/doc/mysql/en/charset-unicode-sets.html), e.g.
       if you are located in germany:
       /opt/ilias/bin/mysql
       mysql> CREATE DATABASE ilias3 CHARACTER SET utf8 COLLATE utf8_unicode_ci;
    6. Load the MySQL 4.0 dump file into the newly created database:
       /opt/ilias/bin/mysql --default-character-set=utf8 ilias3 < ilias3.dump
    7. Check if all content has been successfully migrated. Especially all
       special characters.

If you run multiple ILIAS versions on the same database server you have to
update them all at the same time.
	   
A P P E N D I X  A: Note on using Apache 2

Please proceed as follows:

    - Omit the preparatory step and directly compile and install Apache 2 as
      described in section '2.3.2 - (d) Apache'" but replace the configure
      directive '--activate-module=src/modules/php4/libphp4.a' by '--enable-so'.

    - Add this line to the Apache configuration file httpd.conf, so that PHP
      is loaded as a Dynamic Shared Object (DSO):

          LoadModule php4_module modules/libphp4.so

    - Build PHP as described in section '2.3.2 - (c) PHP' but replace the
      configure directive '--with-apache=/opt/ilias/src/apache_1.3.29' with
      '--with-apxs2=/opt/ilias/bin/apxs'.

    - Starting the Apache 2 daemon should now also invoke the PHP module.
