Installation and Maintenance
Installing ILIAS from scratch
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 1.3.44 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-4.4.0.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-4.4.0.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.
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
THIS INSTRUCTIONS EXPLAIN HOW TO UPDATE FROM ANY ILIAS stable version to
ILIAS 4.4
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 4.4.
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.3.x -> 4.4.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. 4.4.0 -> 4.4.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-4.4.0.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.
</pre>