ILIAS Installation

ILIAS is a powerful Open Source Learning Management System for developing and realising web-based e-learning. The software was developed to reduce the costs of using new media in education and further training and to ensure the maximum level of customer influence in the implementation of the software. ILIAS is published by ILIAS open source e-Learning e.V. under the General Public Licence and free of charge.

Please note: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Table of Contents

1. System Requirements
   1. CPU
   2. Memory
   3. Harddrive
   4. Bandwidth
   5. Recommended Setup for Running ILIAS
   6. Supported Platforms
      1. Server
      2. Client
   7. Database Recommendations
2. Manual Installation on Linux
   1. Git Clone/Checkout
   2. Build PHP-Dependencies and Artifacts
3. Dependency Installation
   1. Apache Installation/Configuration
   2. PHP Installation/Configuration
   3. Database Installation/Configuration
      1. MySQL Strict Mode (5.6+)
      2. MySQL Perfomance tuning (OPTIONAL)
   4. E-Mail Configuration (OPTIONAL)
   5. WebDAV Configuration (OPTIONAL)
   6. Install other Depedencies
      1. Optional Dependencies
   7. Installation Wizard
   8. Configure ILIAS Java RPC server (OPTIONAL)
4. Hardening and Security Guidance
5. Customizing ILIAS
   1. Plugin Repository
6. Upgrading ILIAS
   1. Minor Upgrade
   2. Major Upgrade
   3. Database Update
   4. Information on Updates
7. DBMS
   1. PHP
   2. MySQL
   3. ImageMagick
8. Contribute
   1. Pull Requests
   2. Reference System

System Requirements

The necessary hardware to run an ILIAS installation is always dependent from the number of users and the kind of usage.

CPU

We RECOMMEND a common dual core server CPU.

Memory

Memory requirements are greatly variable, depending on the number of users and server activity. We RECOMMEND a minimum of 4096 MB.

Harddrive

We RECOMMEND 250 GB for usual ILIAS deployments. 25 GB would be used by the operating system and ILIAS itself. 225 GB would remain for the database and files.

Bandwidth

We RECOMMEND at least 100 Mbit/sec. for the web server WAN connection.

Recommended Setup for Running ILIAS

For best results we RECOMMEND:

• Debian GNU Linux 8 / Red Hat Enterprise Linux 7 / Ubuntu 16.04 LTS
• MySQL 5.6+
• MariaDB 10.2
• PHP 7.3
• Apache 2.4.18 with mod_php
• ImageMagick 6.8+
• php-gd, php-xml, php-mysql, php-mbstring
• OpenJDK 7+
• zip, unzip
• git

Package names may vary depending on the Linux distribution.

Supported Platforms

Please note that different configurations SHOULD be possible, but it might be harder to find someone who can help when things go south. You SHALL NOT use a different configuration unless you are an experienced system administrator.

Server

• Server OS: Linux
• Web Server: Apache 2.4 (mod_php, php-fpm)
• Databases: MySQL/MariaDB 5.6 and 5.7 and Galera (experimental), PostgreSQL 9.x
• PHP: Version 7.2, 7.3 and 7.4 are supported
• zip: 3.0+
• unzip: 6.0+
• Imagemagick: 6.8.9-9+
• PhantomJS: 2.0.0+
• NodeJS: 8.9.4 (TLS) - 10.15.3 (LTS)
• Java: Version 7 and 8 are suported

Client

• Desktop: Windows 7+, MacOS X 10.7+, Linux
• Web Browser: Microsoft Edge, Firefox 14+, Chrome 18+, Safari 7+

Database Recommendations

Please note that installing ILIAS in utf8mb4-collations is currently not supported! ILIAS supports UTF-8 (with 3 bytes per character, such as utf8_general_ci) only.

We RECOMMEND to use MySQL/MariaDB with the following settings:

• InnoDB storage engine
• Character Set: utf8
• Collation: utf8_general_ci
• query_cache_size (> 16M)
• join_buffer_size (> 128.0K, or always use indexes with joins)
• table_open_cache (> 400)
• innodb_buffer_pool_size (>= 2G, depending on DB size)

On MySQL 5.6+ and Galera the Strict SQL Mode MUST be disabled. See MySQL Strict Mode for details.

On MySQL/MariaDB innodb_large_prefix must be set to OFF if the ROW_FORMAT is set to COMPACT.

Manual Installation on Linux

You can download the latest ILIAS release at http://www.ilias.de/docu/goto.php?target=st_229 or clone it from GitHub at https://github.com/ILIAS-eLearning/ILIAS (for production make sure to checkout the latest stable release, not trunk).

We RECOMMEND to clone from GitHub as this will offer some kind of autoupdate for future releases and versions.

• Install dependencies (see Recommended Setup for Running ILIAS)
• Untar/Clone ILIAS into the web servers docroot (e.g. /var/www/html/)
• Create directory outside the web servers docroot (e.g. /var/www/files/)
• Change owner/group to www-data (on Debian) or apache (on RHEL) for the files and directories created above

Git Clone/Checkout

To checkout the ILIAS release 6 in /var/www/html/ilias/ use the following commands:

cd /var/www/html/
git clone https://github.com/ILIAS-eLearning/ILIAS.git ilias
cd ilias
git checkout release_6
chown www-data:www-data /var/www/html/ilias -R

The files SHOULD be owned by your webserver user/group (e.g. www-data or apache) the mode SHOULD be 644 for files and 755 for directories.

For more details on file access rights see File Access Rights in the Security section of this document.

Build PHP-Dependencies and Artifacts

The repository of ILIAS doesn't contain all code that is required to run. To download the required PHP-dependencies and to create static artifacts from the source, run the following in your ILIAS folder:

composer install --no-dev

This requires that the php dependency manager composer is available in your $PATH.

The files SHOULD be owned by your webserver user/group (e.g. www-data or apache) the mode SHOULD be 644 for files and 755 for directories.

Dependency Installation

Depending on your Linux Distribution you have several ways to install the required dependencies. We RECOMMEND to always use your distributions package manager to keep your packages up to date in an easy manner avoiding security issues.

Apache Installation/Configuration

On Debian/Ubuntu execute:

apt-get install apache2

On RHEL/CentOS execute:

yum install httpd

Usually Apache ships with a default configuration (e.g. /etc/apache2/sites-enabled/000-default.conf on Debian). A minimal configuration MAY look as follows:

<VirtualHost *:80>
    ServerAdmin webmaster@example.com

    DocumentRoot /var/www/html/ilias/
    <Directory /var/www/html/>
        Options FollowSymLinks -Indexes
        AllowOverride All
        Require all granted
    </Directory>

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    ErrorLog /var/log/apache2/error.log
    CustomLog /var/log/apache2/access.log combined
</VirtualHost>

In order to secure access to the files in your data directory, you SHOULD enable mod\_rewrite on Debian/Ubuntu (should be enabled by default on RHEL/CentOS):

a2enmod rewrite

Please take care to restrict access to the setup-folder Normal users should not be able to access the setup at all. Also see Hardening and Security Guidance for further security enhancing configuration.

After changing the configuration remember to reload the web server daemon:

On Debian/Ubuntu:

systemctl restart apache2.service

On RHEL/CentOS:

systemctl restart httpd.service

PHP Installation/Configuration

On Debian/Ubuntu 14.04 or 16.04 execute:

apt-get install libapache2-mod-php7.1 php7.1-gd php7.1-mysql php7.1-mbstring php7.1-curl php7.1-dom php7.1-zip php7.1-xml php7.1-soap

On RHEL/CentOS execute:

yum install php
systemctl restart httpd.service

To check if the installation was successfull create the file /var/www/html/ilias/phpinfo.php with the following contents:

Then point your browser to http://yourservername.org/phpinfo.php. If you see the content of the file as shown above your configuration is not working. If you can see details of your PHP Configuration everything works fine. Search for the entry Loaded configuration file as we now made some changes to it (e.g. /etc/php5/apache2/php.ini).

We RECOMMEND the following settings for your php.ini:

; you may choose higher values for max_execution_time and memory_limit
max_execution_time = 600
memory_limit = 512M

error_reporting = E_ALL & ~E_NOTICE & ~E_DEPRECATED & ~E_STRICT ; PHP 5.4.0 and higher
display_errors = Off

; or any higher values for post_max_size and upload_max_filesize
post_max_size = 256M
upload_max_filesize = 256M

; choose a non-zero value for session.gc_probability, otherwise old session data will not be deleted
session.gc_probability = 1
session.gc_divisor = 100
session.gc_maxlifetime = 14400
session.hash_function = 0
session.cookie_httponly = On
session.save_handler = files ; for ILIAS setup, ILIAS installations override this
; If you installation is served via HTTPS also use:
session.cookie_secure = On

; for chat server since ILIAS 4.2
allow_url_fopen = 1

; How many GET/POST/COOKIE input variables may be accepted
max_input_vars = 10000

Please see Hardening and Security Guidance for HTTPS configuration and further security relevant configuration.

Remember to reload your web server configuration to apply those changes.

Database Installation/Configuration

On Debian/Ubuntu execute:

apt-get install mysql-server

On RHEL/CentOS execute:

yum install mariadb

We RECOMMEND to create a dedicated database user for ILIAS:

mysql -u root -p
CREATE DATABASE ilias CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE USER 'ilias'@'localhost' IDENTIFIED BY 'password';
GRANT LOCK TABLES on *.* TO 'ilias@localhost';
GRANT ALL PRIVILEGES ON ilias.* TO 'ilias'@'localhost';
FLUSH PRIVILEGES;

MySQL Strict Mode (5.6+)

With MySQL 5.6+ and Galera you might see SQL errors like:

SQLSTATE[42000]: Syntax error or access violation: 1055 Expression #1 of
SELECT list is not in GROUP BY clause and contains nonaggregated column
'yourdbname.tblname.foobar' which is not functionally dependent on
columns in GROUP BY clause; this is incompatible with sql_mode=only_full_group_by

As a workaround STRICT_TRANS_TABLES, STRICT_ALL_TABLES and ONLY_FULL_GROUP_BY MUST be disabled. To do so create the file /etc/mysql/conf.d/disable_strict_mode.cnf and enter the following (or add it to /etc/mysql/my.cnf):

[mysqld]
sql_mode=IGNORE_SPACE,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

After restarting the MySQL-Server use the following command to confirm the changes:

mysql -i -BN -e 'SELECT @@sql_mode' | grep -E 'ONLY_FULL_GROUP_BY|STRICT_TRANS_TABLES|STRICT_ALL_TABLES'

If strict mode is disabled, there will be no output.

MySQL Perfomance tuning (OPTIONAL)

We RECOMMEND to use https://github.com/major/MySQLTuner-perl to optimize your MySQL configuration (e.g. /etc/mysql/my.cnf). Execute mysqltuner.pl after several days of using ILIAS in production.

E-Mail Configuration (OPTIONAL)

You MAY use whatever MTA you like to send E-Mail generated by ILIAS. We RECOMMEND to use an already existing smarthost (mailhub). A very simple way to do so is using ssmtp:

On Debian/Ubuntu execute:

apt-get install ssmtp

On RHEL/CentOS execute:

yum install ssmtp

The configuration file for SSMTP (e.g. /etc/ssmtp/ssmtp.conf) MAY look as follows:

#
# Config file for sSMTP sendmail
#
# The person who gets all mail for userids < 1000
# Make this empty to disable rewriting.
root=yourmail@mail.com

# The place where the mail goes. The actual machine name is required no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
mailhub=smtp.yourmail.com

# Where will the mail seem to come from?
rewriteDomain=yourservername.org

# The full hostname
hostname=yourserver.example.com

# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES

WebDAV Configuration (OPTIONAL)

The recommended webserver configuration is either Apache with mod_php or Nginx with PHP-FPM (> 1.3.8). Do NOT use Apache with PHP-FPM if you use WebDAV.

WebDAV with Windows Explorer

Because of a special behaviour in the Windows Explorer, it sometimes fails to add a WebDAV connection with the error code "0x80070043 The Network Name Cannot Be Found".

To prevent this behaviour, add the following rewrite rules to a .htaccess file in your webroot or to the corresponding section of the configuration of your webserver:

RewriteCond % ^(DavClnt)$
RewriteCond % ^(OPTIONS)$
RewriteRule .* "-" [R=401,L]

WebDAV with Mac Finder

To upload files, the WebDAV Client Finder on Mac uses chunked transfer encoding. Some webservers can't handle this way of uploading files and are serving ILIAS an empty files, which results in an empty file object on ILIAS. Due to a bug in apache, the configuration of Apache with PHP-FPM does not work with the Mac Finder. If you use WebDAV on your ILIAS installation, we recommend to either use Apache with mod_php or Nginx with PHP-FPM (> 1.3.8).

Install other Depedencies

On Debian/Ubuntu 14.04 execute:

apt-get install zip unzip imagemagick openjdk-7-jdk

On Ubuntu 16.04 execute:

apt-get install zip unzip imagemagick openjdk-8-jdk

On RHEL/CentOS execute:

yum install zip unzip libxslt ImageMagick java-1.8.0-openjdk

Optional Dependencies

Depending on your use case, you MAY want to install further dependencies (exact package names vary by distribution):

• php-curl
• php-xmlrpc
• php-ldap
• ffmpeg
• mimetex
• phantomjs

Please ensure that the phantomjs version you use is at least 2.0.0. Please note that phantomjs development has been suspended until further notice. See https://github.com/ariya/phantomjs/issues/15344 for details.

Installation Wizard

After having all dependencies installed and configured you should be able to run the ILIAS Installation Wizard using http://yourservername.org/setup/setup.php

Make sure to reload your Apache configuration before entering the Wizard. Otherwise there are unmet dependencies in the setup (like XLS and GD are both installed but ILIAS does not see them, yet).

Configure ILIAS Java RPC server (OPTIONAL)

The ILIAS Java RPC server is used for certain OPTIONAL functions as Lucene Search or generating PDF Certificates. To enable the RPC server you need to place a configuration file in <YOUR_ILIAS_DIR>/Services/WebServices/RPC/lib/ilServer.properties:

[Server]
IpAddress = localhost
Port = 11111
IndexPath = /var/www/html/ilias/data/
LogFile = /var/www/files/ilServer.log
LogLevel = WARN
NumThreads = 1
RamBufferSize = 256
IndexMaxFileSizeMB = 500

[Client1]
ClientId = ACMECorp
NicId = 0
IliasIniPath = /var/www/html/ilias/ilias.ini.php

ILIAS can generate a proper configuration file via the Administration menu ("Administration -> General Settings -> Server -> Java-Server -> Create Configuration File"). Please note that the configuration file is not directly written to the file system, you MUST copy the displayed content and create the file manually.

You MAY use the following systemd service description to start the RPC server. If you still use SysV-Initscripts you can find one in the Lucene RPC-Server documentation.

[Unit]
Description=ILIAS RPC Server
After=network.target

[Service]
Environment=JAVA_OPTS="-Dfile.encoding=UTF-8"
Environment=ILSERVER_JAR="/var/www/html/ilias/Services/WebServices/RPC/lib/ilServer.jar"
Environment=ILSERVER_INI="/var/www/html/ilias/Services/WebServices/RPC/lib/ilServer.properties"

ExecStart=-/usr/bin/java $JAVA_OPTS -jar $ILSERVER_JAR $ILSERVER_INI start
ExecStop=/usr/bin/java $JAVA_OPTS -jar $ILSERVER_JAR $ILSERVER_INI stop

[Install]
WantedBy=multi-user.target

At this point the RPC server will generate PDF certificates, but to use Lucence search further step are needed. See Lucene RPC-Server for details.

Hardening and Security Guidance

Due the Call for Bids "Documentation for 'Secure ILIAS'", the content is moved to an own file.

See Hardening and Security Guidance

Customizing ILIAS

If you need to customize your ILIAS installation you MUST NOT edit the core files, otherwise you will not be able to update your installation in a timely manner (e.g. due to security fixes).

You can find proper ways to customize ILIAS in the ILIAS Development Guide:

• Plugins and Plugin Slots - ILIAS Development Guide
• Custom Styles

Plugin Repository

ILIAS can be extended with a lot of Plugins. You find the complete list in the Plugin Repository

Upgrading ILIAS

The easiest way to update ILIAS is using Git, please note that this is only possible if you installed ILIAS via git as advised in this document. If Git wasn't used you can always download the ZIP or Tarball in the release section of the ILIAS GitHub pages.

Before you start you SHOULD consider to:

• Backup your database
• Backup your docroot
• Change your skin to delos (default skin)

We also RECOMMEND to use a decent test instance to make a pre-flight check, to see if all plugins, skins, etc. still working as expected with the new version.

Minor Upgrade

To apply a minor update (e.g. v5.2.0 to v5.2.1) execute the following command in your ILIAS basepath (e.g. /var/www/html/ilias/):

git pull
composer install --no-dev

In case of merge conflicts refer to Resolving Conflicts - ILIAS Development Guide.

See Database Update for details on how to complete the Upgrade by updating your database.

Major Upgrade

To apply a major update (e.g. v5.4.0 to 6.0) please check that your OS has the proper dependency versions installed. If everything is fine change your default skin to Delos and apply this at least to your root user, otherwise ILIAS might become unusable due to changes in the layout templates. Then execute the following commands in your ILIAS basepath (e.g. /var/www/html/ilias/):

git fetch
git checkout release_6
composer install --no-dev

Replace release_6 with the branch or tag you actually want to upgrade to. You can get a list of available branches by executing git branch -a and a list of all available tags by executing git tag. Never use trunk or *beta for production.

In case of merge conflicts refer to Resolving Conflicts - ILIAS Development Guide.

See Database Update for details on how to complete the Upgrade by updating your database.

As a last step you should log in with a User using your custom skin. If everything works fine change back from Delos to your skin. If not refer to Customizing ILIAS to modify your skin to match the new requirements.

Database Update

A Database Updates MUST be done for both minor and major updates. Open the ILIAS Installation Wizard (e.g. http://yourservername.org/setup/setup.php) to check and apply the needed updates and/or hotfixes.

The update process usually will be splitted into several runs to avoid timeouts. Each update step can take quite some time without huge load peaks on your PHP/Database processes. To check which update step gets currently executed run the following SQL-Statement on your ILIAS database: SELECT * FROM `settings` WHERE keyword = "db_update_running"

Information on Updates

To keep your ILIAS Installation secure and healthy it is important that you keep it up to date. To get informations about updates and security fixes you SHOULD consider to subscribe to the ILIAS Admin Mailing-List: http://lists.ilias.de/cgi-bin/mailman/listinfo/ilias-admins

Upgrading Dependencies

When you upgrade from rather old versions please make sure that the dependencies, like MySQL and PHP, are up to date. Below you will find the supported versions for each ILIAS release.

PHP

ILIAS Version	PHP Version
6.0.x	7.2.x, 7.3.x, 7.4
5.4.x	7.0.x, 7.1.x, 7.2.x, 7.3.x
5.3.x	5.6.x, 7.0.x, 7.1.x
5.2.x	5.5.x - 5.6.x, 7.0.x, 7.1.x
5.0.x - 5.1.x	5.3.x - 5.5.x
4.4.x	5.3.x - 5.5.x
4.3.x	5.2.6 - 5.4.x
4.2.x	5.2.6 - 5.3.x
4.0.x - 4.1.x	5.1.4 - 5.3.x
3.8.x - 3.10.x	5.1.4 - 5.2.x

DBMS

ILIAS Version	MySQL Version	MariaDB Version	Postgres (experimental)
6.0 - 6.x	5.6.x, 5.7.x, 8.0.x	10.0, 10.1, 10.2, 10.3	9.x
5.4.x - x.x.x	5.6.x, 5.7.x
5.3.x - 5.4.x	5.5.x, 5.6.x, 5.7.x
4.4.x - 5.2.x	5.0.x, 5.1.32 - 5.1.x, 5.5.x, 5.6.x
4.2.x - 4.3.x	5.0.x, 5.1.32 - 5.1.x, 5.5.x
4.0.x - 4.1.x	5.0.x, 5.1.32 - 5.1.x
3.10.x	4.1.x, 5.0.x, 5.1.32 - 5.1.x
3.7.3 - 3.9.x	4.0.x - 5.0.x

ImageMagick

ILIAS Version	ImageMagick Version
4.2.x - 5.2.x	6.8.9-9 or higher
< 4.2.x	No specific version requirements

Contribute

We have a big community and you can get a member of ILIAS Society. You may even join us at one of our regular ILIAS Conferences.

Pull Requests

We highly appreciate Pull-Request from external developers. Due to some regulations in the developments process of ILIAS, some kinds of Pull-Request need further steps. Additionally Pull-Request SHOULD target the correct branch for easy merging.

• Language-Fixes or additions to language-files don't need further steps.
• Bugfixes need an entry in the ILIAS-Bugtracker. Pull-Request for Bugfixes target always to the branch where the bug occurs. The developer which merges it will cherry-pick the fix to all branches needed
• Features/Refactorings need an entry in Feature-Wiki and has to get through the existing procedure for Feature-Requests. Pull-Request target to trunk.

Pull-Request will be assigned to the responsible maintainer(s). See further information on how contributions are handled in /docs/CONTRIBUTING.md

Reference System

The ILIAS Testserver (https://test6.ilias.de) is currently configured as follows:

Package	Version
Distribution	Ubuntu 16.04.7 LTS
MariaDB	10.0.38
mysql	5.6
PHP	7.3.22
Apache	2.4.18
zip	3.0
unzip	6.00
JDK	1.8.0_265
NodeJS	v10.22.0

Please note: Shibboleth won't work with Nginx.