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


          Author: Boris H. Schuermann

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. Updating ILIAS

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, Windows and Mac OS.

We highly recommend to use one of the distribution related instructions
provided at http://www.ilias.de/docu/goto.php?target=st_6487_367&client_id=docu

This documentation describes how to install all the tools needed from scratch.
Usually you should prefer to use any package manager provided by your
distribution. Many of these tools are already installed in standard
configurations of many distributions.

The following third-party tools are necessary for running ILIAS. Release
numbers refer to the versions tested, usually minimum versions. Newer versions
should work, see also:
http://www.ilias.de/docu/goto_docu_pg_6531_367.html (II. General Requirements)

    - Apache 2.2.x             http://www.apache.org
    - MySQL 5.1.32             http://www.mysql.com
    - PHP 5.3.27               http://www.php.net
    - Zlib (libz) 1.1.4        http://www.gzip.org/zlib/
    - libpng 1.2.5             http://www.libpng.org
    - libjpeg 6b               ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
    - ImageMagick 6.3.8-3      http://www.imagemagick.org
    - Info-ZIP (Zip/UnZip)     http://www.info-zip.org
    - libxml2 2.6.31           http://www.xmlsoft.org
    - libxslt 1.1.22           http://www.xmlsoft.org

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

Please visit http://www.ilias.de/docu/goto.php?target=st_6487_367&client_id=docu
and try a install procedure that suits your OS distribution. If this fails, you
may try to install the tools from scratch.


2.1 Where to install ILIAS

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.

When compiling the components necessary to run ILIAS from source you may easily
specify their installation location using an appropriate '--prefix' directive.


2.2 First steps

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/ImageMagick-6.3.8-3.tar.gz
    tar -xzf tarballs/zip23.tar.gz
    tar -xzf tarballs/unzip550.tar.gz
    tar -xzf tarballs/mysql-5.1.32.tar.gz
    tar -xzf tarballs/apache_1.3.44.tar.gz
    tar -xzf tarballs/php-5.3.27.tar.gz
    tar -xzf tarballs/libxml2-2.6.31.tar.gz
    tar -xzf tarballs/libxslt-1.1.22.tar.gz

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

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

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

	We recommend to use the PHP bundled version of GD. Please visit the
	PHP GD requirements page at http://php.net/manual/en/image.requirements.php
	The page lists libraries for download to support various image formats.
	We recommend to install a version that at least supports gif, jpeg and png.
	
	Configure options for PHP needed for GD:
	--with-gd --with-jpeg-dir=DIR --with-png-dir=DIR (and more, if wanted)


(e) ImageMagick

        cd /opt/ilias/src/ImageMagick-6.3.8
        ./configure \
        --prefix=/opt/ilias \
        --without-perl \
        --enable-lzw \
        --enable-delegate-build \
        --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.


(g) libxml

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


(h) libxslt

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


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

    Using one of the actual binaries provided at the MySQL web site is always the best idea.
    However, if you decide to build MySQL from scratch, here are the basic steps:

    Configure & make:

        cd /opt/ilias/src/mysql-5.1.x
        ./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 5.1.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 5.1 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 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 ilias CHARACTER SET utf8 COLLATE utf8_unicode_ci


(b) Apache

    Configure & make:

        cd /opt/ilias/src/apache_1.3.44
        ./configure \
        --prefix=/opt/ilias \
        --enable-so \
        --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.


(c) PHP

    Configure & make:

    PHP 5.3.27:
		
        ./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 \
        --enable-mbstring
        make
        make install
		
    The default PHP configuration file must be copied to /opt/ilias/config:

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

    Visit http://www.ilias.de/docu/goto.php?target=pg_6531_367&client_id=docu
    to get current recommendations for php.ini settings.


2.4 Installing ILIAS


(a) Installing the ILIAS 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-5.0.8.tar.gz

    Please make sure your webserver has write permission to the ILIAS 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/ilias
        chown -R wwwrun /opt/ilias/data


(b) Running the setup script

    Open the ILIAS setup script in your web browser:

        http://www.yourserver.com/ilias/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 login,
    either using the [login] link or by accessing

        http://www.yourserver.com/ilias/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. See
    http://www.ilias.de/docu/goto.php?target=pg_15915_367&client_id=docu
	for more information how to do this.

(e) Settting up the chat server

    The file Modules/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/cron/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.


3. Updating ILIAS


THIS INSTRUCTIONS EXPLAIN HOW TO UPDATE FROM ANY ILIAS stable version to
ILIAS 5.0

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

BEFORE UPDATING FROM ANY ILIAS VERSION 3.9 OR LOWER YOU MUST UPGRADE TO
ILIAS 3.10 FIRST. YOU SHOULD ONLY UPGRADE FROM A 3.10.x VERSION OR HIGHER TO
ILIAS 5.0.

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

For major updates (e.g. 4.4.x -> 5.0.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. 5.0.0 -> 5.0.1).

At the time being no installation script is available for updating ILIAS. For
this reason the ILIAS script files must be updated manually. In the following
steps it is assumed that your existing ILIAS 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.

It is 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.

Please note that the way user agreements, adapted language files and individual
skins and styles are stored has been changed with ILIAS 3.8.0. See
http://www.ilias.de/docu/goto.php?target=st_15914_367&client_id=docu
for more information.

    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 Modules

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-5.0.8.tar.gz

After extracting the files you will find a newly created subdirectory 'ilias' 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/ilias
    cp -p * /opt/ilias/www/htdocs/ilias/
    cp -rp classes cron docs include lang /opt/ilias/www/htdocs/ilias/
    cp -rp Modules payment Services setup templates /opt/ilias/www/htdocs/ilias/
    cp -rp webservice xml /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/.

Make sure that the apache user is the owner of all files using chown, e.g.
'chown -R wwwrun /opt/ilias/www/htdocs/ilias/'.

After installing a new ILIAS 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.10.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 = 200M
  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").


	   
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/php5/libphp5.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 php5_module modules/libphp5.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.
