Professional Documents
Culture Documents
Olat Installation & Administration Documentation: Preface
Olat Installation & Administration Documentation: Preface
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 $
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.
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
share.dir
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
skip.db.install
and db.prompt
db.*
The database settings are mostly self explanatory and refer to the
database server that will host the OLAT database. Note that it is
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.
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
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.
skip.unit.tests
unpack.fonts
eclipse.server.name
eclipse.server.port /
eclipse.server.secure.port
eclipse.admin.port
eclipse.ajp.port
eclipse.server.keystore.*
eclipse.recreate.dirs
clean.plugin.clean.*
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
site
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:
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.