OLAT

Installation & Administration Documentation

MELS - Multimedia & E-Learning Services, University of Zuerich, Switzerland
Copyright 2009 MELS - Multimedia & E-Learning Services, University of Zuerich, Switzerland

Table of Contents
Preface
1. OLAT easy installer - Placeholder
2. Installation and Configuration
2.1. Prerequisites
2.2. Standard Installation
2.3. Impatient Developer Installation
2.4. Developer Installation
2.5. Deployment
List of Tables
2.1. Local configuration properties
2.2. MySQL configuration file parameters
2.3. Eclipse Variables
2.4. Developer configuration properties
2.5. Common Build Goals
2.6. Common Build Profiles

Preface
This documentation is intended for OLAT system administrators. It describes how to install, update and
run OLAT. It also describes OLAT capabilities of customization on configuration level.
$Revision: 1.32 $, $Date: 2009/10/09 10:02:04 $

Chapter 1. OLAT easy installer - Placeholder

Chapter 2. Installation and Configuration
The following sections describe both the standard installation (see Section 2.2, Standard Installation) as
well as the developer installation (see Section 2.4, Developer Installation.) Those already familiar with
the application may wish to install following our guidelines for the Impatient (see Section 2.3, Impatient
Developer Installation.) Before proceeding with either installation you should ensure that you have read
and understood the prerequisites (see Section 2.1, Prerequisites) for installing OLAT.
When you download and unpack the OLAT distribution you will find in the top level directory the
olat.properties file that contains settings required to build and install OLAT. Most of these

settings you will not need to change though you may wish to review them anyway. In addition there is
also a olat.local.properties.sample file (developers have an additional section within this
file which can be safely ignored by non-developers!) that contains configuration settings you are likely to
want to change to suit your environment. During the installation you will be instructed to make a copy of
this file and apply the necessary changes.
Windows users should note the (Java) practice of using forward slashes in directory paths (e.g.,
C:/TEMP instead of C:\TEMP) when setting OLAT properties. In addition users of Mac OS/X should
be aware that the the OS/X VM implementation of Java may be installed on your system and that you will
need to install the Sun Microsystems JVM and set it as your default JVM.

2.1. Prerequisites
Before commencing with your OLAT installation you must first ensure that the following prerequisites
are present and are functioning correctly. Please consult the relevant product documentation for further
information as well as installation and configuration instructions.
JDK SDK 1.6 must be installed on your Tomcat host and when compiling from source. Note that
it is not sufficient to have a JRE installed as Tomcat requires the compiler at runtime! It is,
however, possible for JDK 1.6 to co-exist on systems that already have other JDKs installed.
Maven (version 2.2.x or later) is required in order to build and deploy the OLAT application. Note
that during the build Maven will download depedencies and that an Internet connection is required
during the build.
Tomcat web container (version 6.x or later) to host the web application. On UNIX systems OLAT
recommends that Tomcat runs under a dedicated user (e.g., "tomcat") for security reasons. In
situations where more than one instance is required (e.g., multiple cluster nodes on the same host)
it is worth setting up each OLAT instance in its own JVM and sharing a common base installation
(see Tomcat documentation concerning CATALINA_BASE installations.)
MySQL (version 5.0.x or later.) Since OLAT uses the InnoDB storage engine which employs a
single tablespace and logfile structure per database instance it is recommended that OLAT be
provided with a dedicated instance. On UNIX systems OLAT recommends that MySQL runs
under a dedicated user (e.g., "mysql") for security reasons. Note that for the installation you will
need to have administrative acces to your database (e.g., the root account)
Openfire (version 3.4.x or later.) to support Instant Messaging (XMPP) This component is
optional and may be omitted if you do not wish to use such services.
On busy production sites continuous monitoring of OLAT is recommended in order to assess
performance and to resource dimensioning needs accurately. OLAT recommends the use of SNMP based
monitoring tools such as Multi Route Traffic Grapher or Nagios as well as log analysis tools (e.g., access
statistics etc.) such as Webalizer. Please refer to the relevant product documentation for installation and
configuration instructions.

2.2. Standard Installation

This chapter describes the installation of OLAT for those wishing to use OLAT in a test or production
environment. If you are a developer then please skip this section and proceed to Section 2.4, Developer
Installation where the installation process for an Eclipse IDE environment is described. If you are a
deployment manager then we suggest that you review the Operations chapter to consider additional
installation and configuration details. This installation process has been tested on Linux, MacOSX and

Windows systems. Our production systems run on Linux and use JDK 1.6.x, Tomcat 6.x, MySQL 5.x and
the latest Openfire 3.4.x
We anticipate that you will download and build OLAT on a host and then transfer the deployment asset
(i.e., the Web ARchive or WAR file) to your Tomcat host. We do not recommend building directly into
your deployment i.e., colocating build and deployment trees, unless you are a developer working on the
code.
Download OLAT and unpack it into a working directory. It is not necessary to have administrative
rights on your machine in order to configure and build OLAT. However, you will likely need
administrative access to deploy the database and web application components.
The olat.properties file contains settings required to build and install OLAT most of which
you will seldom, if ever, need to change. The olat.local.properties.sample file
contains those configuration settings you are most likely going to need to change for your
environment. Begin by making a copy of this sample file and naming it
olat.local.properties. Review its contents and amend them as appropriate for your local
environment.
Please note that OLAT application directories will be created for you during the build for which
the build user account must have sufficient access rights. Pre-existing directories will not be
removed though their contents may become overwritten.
The follow remarks apply to the local properties:
Table 2.1. Local configuration properties
userdata.dir

This should be set to an appropriate application data location. A typical

choice on a Linux system would be /var/lib/olat.

share.dir

This contains samples of optional configurations generated from your

property settings. A typical location on a Linux system for such assets
would be /var/share/olat.

smtp.*

Mail settings for your local SMTP agent (typically an MTA such as
Sendmail, Postfix or Exim) Without these settings your OLAT instance
will be unable to issue emails.

instance.id

This is an internal instance identifier used by OLAT and should only be

changed in the event that several instances are deployed within a single
cluster.

skip.db.install
and db.prompt

It is important to note that during the installation the database will be

created along with necessary tables. If you already have a working
database that you do not wish to alter then you must set the value of this
property to false! Note that if you are installing a database then the
db.prompt (which defaults to true) will determine whether or not
you are prompted to confirm the installation of your database. You
should set this to false if you do not want to be prompted (e.g., if you
want a non-interactive build.)

db.*

The database settings are mostly self explanatory and refer to the
database server that will host the OLAT database. Note that it is

necessary to state the name of an administrative user with the necessary

rights to create databases (on MySQL the root user is often used for
this) using the db.admin.user property. You may, if you wish, also
store the administrative user password in your
olat.local.properties file but if you do so, then you should
ensure that the file is not publicly readable for security reasons. If you
choose not to set this property then you will be prompted for the
password during installation. Generally speaking you must create
user/host (i.e., user@host combinations for MySQL for each host that
wishes to connect to your database. When a user tries to connect his/her
IP is checked against the GRANT table entries and if necessary a DNS
reverse lookup may be performed. You may therefore opt to create
accounts based on either IP or hostname (or both which is the default)
by setting the appropriate db.client.* properties.

The following MySQL configuration parameters should be applied to your server configuration
file (i.e., my.cnf)
Table 2.2. MySQL configuration file parameters
default_storage_e
ngine (or
This must be set to innodb and applies to all OLAT tables (unless the
default_table_typ table definition states otherwise)
e)
This establishes the tablespace for your OLAT database which you can
place under your MySQL data directory i.e., datadir in a directory
innodb_data_home_
called olat. You must create this directory yourself before starting the
dir
MySQL instance. We recommend a dedicated tablespace for OLAT
and hence a dedicated MySQL instance.
This establishes the logfiles for your OLAT database which you can
place under your MySQL data directory i.e., datadir in a directory
innodb_log_group_ called olatlogs We recommend dedicated logfiles for OLAT and
home_dir
hence a dedicated MySQL instance. For heavy loads you may consider
locating these files on a separate partition or volume. You must create
this directory yourself before starting the MySQL instance.
When set to 1 this flushes the log buffer to the log file with each
innodb_flush_log_ commit and a a disk write is performed. This is a reasonable default
at_trx_commit
value for OLAT which ensures ACID compliance though you may
wish to review other possible values depending on your circumstances.
Generally speaking we recommend a value of c. 300M for production
innodb_buffer_poo
systems though a (considerably) smaller value is appropriate for trial
l_size
instances
innodb_additional This should be set to 20M and is required exclusively for the data
_mem_pool_size
dictionary and related matters.

 Issue the following command from the root of the OLAT installation directory
mvn install

During the build you will need Internet access since depedencies will be downloaded and stored in
your local Maven repository. Moreover you will need network access to your MySQL database
since the necessary tables, contraints and indexes will be created automatically during the build
unless you have set skip.db.install to true. When the build is complete you will find a
Web ARchive or WAR file in the olat/target/ subdirectory of olat3 which you can copy
over into the webapps directory of your Tomcat server from whence it can be deployed as
described in Section 2.5, Deployment.

2.3. Impatient Developer Installation

This section concerns an installation for those with some development familiarity with the application and
who wish to set up a running instance quickly. If necessary, please refer to the appropriate section of
Section 2.4, Developer Installation for further details (incl. the use of external tool invocations which
we recommend for regular developerment work.)
Download OLAT or checkout from the sources from the CVS repository of both olat3 and
olatcore modules.
Ensure that you are using the Sun JDK 1.6 or later and that your compiler has sufficient heap
allocation (e.g., use -Xms1024m -Xmx1024m)
Make a copy of olat.local.properties.sample to olat.local.properties,
review and edit as appropriate. In particular set skip.db.install to true if you have an
existing database that you plan to use and review the developer section carefully and configure
according to your needs.
Issue mvn -Pdeveloper eclipse:eclipse clean install
Copy the WAR from olat/target into your Tomcat webapps directory and configure a
context pointing to the location of the WAR and using the olat context path. Deploy your
application. Later in the developer installation notes you will learn how to use an internal IDE
Tomcat instance into which you can deploy the WAR.
Access OLAT via http://tomcat_host:tomcat_port/olat using the username
Administrator and password olat.

2.4. Developer Installation

This chapter describes the installation process for developers working on OLAT code. Please ensure that
you have already installed the necessary prerequisites as described in Section 2.1, Prerequisites and that
these are functioning correctly.
Throughout we assume that you are working with Eclipse and have the Web Tools Platform (WTP) and
Concurrent Version Systems (CVS) support installed. Note that we do not recommend the use of the
Eclipse Maven (i.e., m2eclipse) plugin though we do suggest you use the Maven Eclipse (i.e.,
eclipse:eclipse) plugin.
As described below we make much use of external tool launch configurations and a custom builder in

order to better integrate the external Maven tool into the Eclipse IDE. This is a conscious decision taken
in light of difficulties we experienced with Maven and Eclipse. We describe how to setup such
configurations below and encourage you to establish as many such configurations as you may need for
your development.
OLAT also has its own Maven plugin which addresses specific functions that the OLAT team use
frequently. To simplify usage of this plugin you will first need to define a plugin group in your Maven
settings.xml file (on Linux systems this is found in the .m2 directory of your home account. This
can be done by adding the following line to the pluginGroups element
<pluginGroup>org.olat.plugins</pluginGroup>

Now you can invoke the OLAT plugin via the olat: prefix instead of having to provide the entire
Maven POM coordinates e.g., you can issue olat:clean from within an external tool launch
configuration.
The following steps describe in detail the installation of OLAT as an Eclipse project.
If not already the case we recommend that you allocate 1024M memory for your Eclipse instance.
Perhaps the best way to do so is to edit your eclipse.ini found in the root of your Eclipse
installation directory by adding -Xms1024m -Xmx1024m to this file.
To invoke Maven directly (e.g., via the OLATBuilder custom builder) you will need to create the
following environment variables These can be created in the "String Substitution" submenu of
"Run/Debug" under Window/Preferences as illustrated below.
Table 2.3. Eclipse Variables
M2_REPO

This should point your local Maven repository (e.g., on Linux systems this is usually
in your ~/.m2/repository.)

MVN_EXE
This should point to your local Maven executable.
C

Direct the environment variable to your local Maven executable

Check out the OLAT code ensuring that the olat3 and corresponding olatcore are sibling
projects within your Eclipse workspace. You may, if you wish, check out other modules but this is
not necessary. We recommend that you either import (i.e., "Import" under "File" menu) the project
into your workspace or checkout via CVS from within the IDE rather than create a new Java
project as it may not be recognised as an Eclipse project if you do so.

Use "Import" to ensure that your environment is setup appropriately

As we will be making frequent use of the external tool facility in Eclipse you should understand
how to configure this under the "Run" menu "External Tools" and "External Tools Configuration"
item. In general you should create a new launch configuration under the "Program" list citing the
MVN_EXEC variable you defined earlier in "Location" and your Eclipse project_loc variable
in "Working Directory" as indicated below

Sample external tool configuration

We recommend that you select your projects under the "Specific Resources" radio button of the
"Refresh" tab in order to ensure that your workspace is refreshed by the filesystem activity of
Maven.
Now that you know how to create an external tool launch configuration you are ready to create
your first configuration to invoke the Maven eclipse:eclipse goal which updates your
classpath and project settings.

The eclipse:eclipse external tool configuration

It is important here to select both the olat3 and the olatcore projects under "Specific
Projects" radio button of both the "Refresh" and "Build" tabs. Finally you may find it convenient
to select "External Tools" in the "Display in Favourites Menu" of the "Common" tab. This will
make it automatically appear under the External Tools widget of your toolbar.

Sample external tool configuration

Now run the eclipse:eclipse launch configuration to update your projects. You will not
often need to run this tool but it is sometimes necessary (e.g., when plugin changes result in
classpath changes etc.)
A common error that you might find confusing is when an external launch configuration has been
invoked when no project is in focus (i.e., has not been selected on the project browser) When this
occurs you may see an error like the one illustrated below - simple select your "olat3" project and
re-launch the configuration!

Error when no project is selected

Using the Servers view, which is provided by the Web Tools Platform (WTP), create a new

Tomcat 6 server and configure it with a simple name (e.g., "OLAT-x.y.z") which you will need
later. Note that there is no need to assign resources to this server as this will be done for you
automatically by the build process.

Create a new WTP Tomcat 6 Server

You might find it helpful to note that you can open your Tomcat configuration via the Servers
view to edit it directly. Please note that you should answer "Yes" when prompted to apply changes
to the underlying files.

Edit your server configuration to suit your needs

OLAT build time properties are sourced from olat.properties and can be overwritten by
values set in the olat.local.properties file which you should first create (e.g., it may be
empty or a copy of olat.local.properties.sample) The local file should remain
outside of version control.
Much of the local properties are self-explanatory and have already been described in Section 2.2,
Standard Installation so please review those comments first before continuing.
Developers should pay particular attention to the developer section within
olat.local.properties since this makes reference to a number of settings that you may
wish to change (e.g., it is probably not necessary to unpack fonts with each build and you probably
do want to run unit tests etc.)

Table 2.4. Developer configuration properties

skip.db.install

Required only for installations and should be set to true

for developers if the database is already present

skip.unit.tests

May be set to true for developers though we require

periodic execution of all unit tests

unpack.fonts

May be set to false if you do not require the use of

mathematical fonts and therefore do not wish them to be
unpacked during the build.

eclipse.server.name

The name of your WTP Tomcat Server as your configured

it in Eclipse. Note that -config is appended to your
server name on the filesystem by Eclipse - your entry here
should not include this.

eclipse.server.port /
eclipse.server.secure.port

The ports on which your Tomcat Server is configured to

listen

eclipse.admin.port

The ports on which your Tomcat Server shutdown port is

configured to listen

eclipse.ajp.port

The ports on which your Tomcat Server APJP connector

is configured to listen (optional)

eclipse.server.keystore.*

The PKCS#12 keystore settings for your Tomcat server if

using SSL (optional)

eclipse.recreate.dirs

If set to true then application directories (e.g., userdata

etc.) are removed with each build.

clean.plugin.clean.*

If set to true then the relevant componet will be

removed when the Maven olat:clean goal is issued
(this goal is called automatically when you issue a Maven
clean goal.) Specifically this concerns the dropping of
the database, removal of application directories (e.g.,
userdata etc.) and removal of application logs.

Table 2.5. Common Build Goals

clean

Removal of all generated and distributed assets. Depending on how you have set your
olat.plugin.clean.* properties your database may be dropped and application and/or
log directories removed.

compile Compilation of Java assets and distribution of related XML files, properties files and server
configurations

package Packging of all compiled and distributed assets into a WAR file. The package staging area
servers as the application root of your IDE Tomcat instance.
Sets up the database (depending on your database properties) and places generated assets
(e.g., WAR) in your local repository (i.e., where your M2_REPO points to) If you are only
install
interested in invoking this target in order to install the database then you can do so directly
by issuing the olat:dbinstall goal.
deploy

Deployment of WAR into your Tomcat container.

site

Generation of a website, found under olat/target/site, including extensive

information of interest to developers (e.g., output of static code analysers, project
information etc.)

The following lists the common profiles you are likely to want to use (this require the -P option)
Generally speaking profiles can be combined (e.g., developer and cluster)
Table 2.6. Common Build Profiles
When no -P is present the build injects no specific features and creates standard build
assets

None

developer Ensures that the WTP Tomcat server is appropriately configured and that specific
developer practices and expectations are honoured.
cluster

Ensures the OLAT cluster configuration (instead of the Single VM) is deployed

There are two config files for Tomcat generated by 'ant config-all':
server.xml configures Tomcat to accept HTTP requests directly. All requests to OLAT rebuild
code will go to Tomcat directly. For testing go with this file and you don't need to install Apache.
To configures your Tomcat with Apache as main gateway to OLAT. All requests go through
Apache first and are forwarded through a Tomcat JK Connector by Apache if necessary. This
shields Tomcat from the outside world. We suggest using this connector for security reasons.
Uncomment the jk connector part in the server.xml file.
Copy the server.xml file to your tomcat installation. TOMCAT_HOME/conf/server.xml
Now you should be ready to compile OLAT, type:
# ant build

Finally you'll need to setup the necessary database tables for OLAT. 'ant dbsetup' will do the job
for you. Be careful with that target on a productive system since you will loose all your data!
You can now start Tomcat (if configured restart Apache)
Access your OLAT installation:

You can reach your OLAT installation at http://your.site.com:[PORT]/CONTEXT_PATH where

CONTEXT_PATH is the context path of your application as you've configured it in your
build.properties file. The default is "olat" e.g. http://localhost:8080/olat
There are some accounts setup by default:
Login: 'administrator' Password: 'olat'. This account has full administrative rights. We advise you
to change the password immediately (see 'Home' -> 'settings' -> 'Password')
Login: 'gast' Password: 'gast'. This account is the default account for 'Learningresources' which
grant access to guests. By default, this account does not have access to any content in OLAT.
Note: If you encounter an error like: "Error creating bean with name 'bbfactory' defined in file
[/opt/OLAT/webapp/WEB-INF/olat_extensions.xml" make shure you give the right ownership to
all files processed by the user that runs tomcat. On linux you can reach this by using the command
"chown -R yourtomcatuser:yourgroup PATH_TO_YOUR_INSTALLATION".

2.5. Deployment
There are basically two options open to you both of which require that you have a running Tomcat
instance already installed on your target host.
The first option is to use the Maven deploy goal to from the build host to automatically copy the WAR
into your container. This method may be preferable to developers, those testing and evaluating the
application where access to a local or remote running Tomcat instance is not an issue. This option
requires that your Tomcat instance has the manager deployed (which is often the case) and that you have
the necessary username and password as defined in the tomcat-users.xml file in your container.
Before commencing you should add the following entry to your $M2_REPO/settings.xml file
replacing the value for username with your Tomcat manager user (usually this is called manager or
admin but consult your Tomcat documentation if necessary) and the password value with your
manager password.
<settings>
...
<servers>
...
<server>
<id>olat-mvn-tomcat</id>
<username>myusername</username>
<password>mypassword</password>
</server>
...
</servers>
...
</settings>

Next you should review the tomcat.* properties as found in your olat.local.properties file
and ammend them according to your target Tomcat environment. Once down you can deploy your
application by issuing
mvn tomcat:deploy

The second involves manual configuration of your Tomcat context and file copy of the application WAR
into the target directory. For those familiar with Tomcat administration and those who require separation
of builds and deployment this is the preferred option.

Configuration of Tomcat requires an application context be configured pointing to the directory where
you have deployed your WAR file. Practices vary with some administrators preferring to put this context
into the server.xml file and others preferring to place it separately under the Catalina engine
directory tree. Either way your context should resemble something of the form:
<Context path="/olat"
docBase="/path/to/olat"
debug="4" reloadable="false" />

You may now deploy your application from either the administrative or the manager consoles within
Tomcat or by restating your Tomcat instance (which is often the preferred approach if you are using the
CATALINA_BASE methodology.
Irrespective of how you choose to deploy your application you can access it by visiting
http://tomcat_host:tomcat_port/olat in your browser (if you are accessing the instance
from behind a reverse proxy then your should use your virtual host name.) By default you can either login
as administrator (password olat) or as gast (password gast,) The former has full
administrative rights and we strongly recommend that you change the password immediately by
navigating to 'Home', 'Settings' and 'Password'. The latter account is the default account for access to
guest access to learning resources (gast is the German word for "guest" !) and does not have any access
to content in OLAT.