OLAT

Installation & Administration DocumentationMELS - Multimedia & E-Learning Services, University of Zuerich, Switzerland

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

Table of Contents

Preface1. OLAT easy installer - Placeholder2. Installation and Configuration

2.1. Prerequisites2.2. Standard Installation2.3. Impatient Developer Installation2.4. Developer Installation2.5. Deployment

List of Tables

2.1. Local configuration properties2.2. MySQL configuration file parameters2.3. Eclipse Variables2.4. Developer configuration properties2.5. Common Build Goals2.6. Common Build Profiles

PrefaceThis 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 ConfigurationThe 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. PrerequisitesBefore 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 InstallationThis 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.dirThis 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.idThis 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_engine (or default_table_type)

This must be set to innodb and applies to all OLAT tables (unless the table definition states otherwise)

innodb_data_home_dir

This establishes the tablespace for your OLAT database which you can place under your MySQL data directory i.e., datadir in a directory called olat. You must create this directory yourself before starting the MySQL instance. We recommend a dedicated tablespace for OLAT and hence a dedicated MySQL instance.

innodb_log_group_home_dir

This establishes the logfiles for your OLAT database which you can place under your MySQL data directory i.e., datadir in a directory called olatlogs We recommend dedicated logfiles for OLAT and 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.

innodb_flush_log_at_trx_commit

When set to 1 this flushes the log buffer to the log file with each commit and a a disk write is performed. This is a reasonable default value for OLAT which ensures ACID compliance though you may wish to review other possible values depending on your circumstances.

innodb_buffer_pool_size

Generally speaking we recommend a value of c. 300M for production systems though a (considerably) smaller value is appropriate for trial instances

innodb_additional_mem_pool_size

This should be set to 20M and is required exclusively for the data 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 InstallationThis 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 InstallationThis 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_EXEC This should point to your local Maven executable.

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.fontsMay 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.nameThe 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

cleanRemoval 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.

installSets 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 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.

siteGeneration 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

None When no -P is present the build injects no specific features and creates standard build assets

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. DeploymentThere 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.