This guide walks you through installing OpenOLAT on a local GNU/Linux or similar system with Tomcat8, Java8 and MySQL.

Create a user for OpenOLAT

The username is openolat in this guide with home directory in /home/openolat/. From here onwards do everything as the user openolat (unless pointed out differently).

Download OpenOLAT, JRE and tomcat

Download JRE 1.8.x, tomcat-8.x.x and OpenOLAT-14.x.x war file. Create a directory downloads and keep the downloaded files there:

openolat~$ ls -l downloads/
-rw-r--r-- 1 openolat openolat  7843733 Sep 18 10:34 apache-tomcat-8.x.x.tar.gz
-rw-r--r-- 1 openolat openolat 46808550 Sep 18 10:34 jre-xuxx-linux-x64.tar.gz
-rw-r--r-- 1 openolat openolat 85277009 Sep 10 21:42 openolat_xxx.war
Note that you do not need a JDK to run OpenOLAT.

Prepare home directory

In the home directory:

tar xvf downloads/apache-tomcat-8.x.x.tar.gz
ln -s apache-tomcat-8.x.x tomcat
tar xvf downloads/jre-xuxx-linux-x64.tar.gz
ln -s jre1.8.x_xx/ jre
unzip -d openolat-xxx downloads/openolat_xxx.war
ln -s openolat-xxx webapp

Note that this setup allows you to switch between different versions of JRE and tomcat by adjusting the symlinks jre and tomcat.

Set up tomcat in home directory

mkdir bin conf lib run logs

Link the following files

cd ~/conf
ln -s ../tomcat/conf/web.xml web.xml
cd ~/bin
ln -s ../tomcat/bin/

Create additional, handy links

cd ~
ln -s tomcat/bin/ start
ln -s tomcat/bin/ stop

Create the file bin/ containing

CATALINA_OPTS="-Xmx1024m -Xms512m -XX:MaxMetaspaceSize=512m  \                                   \
-Duser.timezone=Europe/Zurich                          \                     \
-Djava.awt.headless=true                               \                        \
-Djava.endorsed.dirs=./common/endorsed                 \
-XX:+HeapDumpOnOutOfMemoryError                        \
-XX:HeapDumpPath=.                                     \
The scripts of tomcat will parse this file at startup.

Create the file conf/server.xml

<?xml version='1.0' encoding='utf-8'?>
<Server port="8085" shutdown="SHUTDOWN">
  <Service name="Catalina">
    <Connector port="8088" protocol="HTTP/1.1" />
    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost"  appBase="webapps" />

Make sure the chosen ports (8085 and 8088 in this example) are available.

Set the environment variables CATALINA_HOME and JRE_HOME, for example by appending the following to your .bashrc

export CATALINA_HOME=~/tomcat
export JRE_HOME=~/jre
and activate them by issuing
. .bashrc

Test tomcat


... should output something like this:

Using CATALINA_BASE:   /home/openolat
Using CATALINA_HOME:   /home/openolat/tomcat
Using CATALINA_TMPDIR: /tmp/openolat
Using JRE_HOME:        /home/openolat/jre
Using CLASSPATH:       /home/openolat/tomcat/bin/bootstrap.jar:/home/openolat/tomcat/bin/tomcat-juli.jar
Using CATALINA_PID:    /home/openolat/run/
Tomcat started.

Check whether these values make sense, then stop tomcat again


Set up mysql database and user

If you have any choice, use MySQL 5.6. If you can't, use 5.5. Do not use 5.1, there are many issues with 5.1. You can also use PostgreSQL as an alternative, the installation manual should be at the same level as this manual.

Do the following as mysql root user (you may need the mysql root password)

mysql -u root -p

and do this:

create database oodb character set utf8 collate utf8_unicode_ci;
create user oodbu@localhost identified by 'oodbpasswd';
grant all on oodb.* to oodbu@localhost;

Test the mysql account as openolat user

mysql oodb -u oodbu -poodbpasswd
You should get the mysql cli prompt. Exit.

Optionally create a file named .my.cnf containing

then you can access the database by just typing mysql.

Create the OpenOLAT database schema

cd /home/openolat/webapp/WEB-INF/classes/database/mysql/
mysql oodb -u oodbu -poodbpasswd < setupDatabase.sql

Create OpenOLAT configuration

Create the file lib/


Create the context file for the OpenOLAT Application

mkdir -p conf/Catalina/localhost/
and create the file conf/Catalina/localhost/ROOT.xml containing:
<?xml version="1.0" encoding="UTF-8" ?>
<Context path="" docBase="/home/openolat/webapp" debug="0" reloadable="false" allowLinking="true">
  <Resource name="jdbc/OpenOLATDS" auth="Container" type="javax.sql.DataSource"
     maxTotal="16" maxIdle="4" maxWaitMillis="60000"
     username="oodbu" password="oodbpasswd"
     validationQuery="SELECT 1" 
Make sure the values of username, password and the "localhost:3306/oodb" part in the url value are the ones of your mysql account for OpenOLAT.

Configure log4j2 for OpenOlat 14 and newer

Create the file lib/log4j2.xml containing

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
       <RollingFile name="RollingFile" fileName="/home/openolat/logs/olat.log"
                   pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %marker %c{1} ^%%^ I%X{ref}-J%sn ^%%^ %logger{36} ^%%^ %X{identityKey} ^%%^ %X{ip} ^%%^ %X{referer} ^%%^ %X{userAgent} ^%%^ %msg%ex{full,separator( )}%n" />
               <TimeBasedTriggeringPolicy interval="1" />
       <Logger name="org.apache.commons.httpclient" additivity="false" level="warn">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.apache.pdfbox" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.apache.fontbox" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.hibernate.engine.internal.StatisticalLoggingSessionEventListener" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <!-- Change the level to debug to see the SQL statements generated by Hibernate -->
       <Logger name="org.hibernate.SQL" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <Logger name="org.hibernate.type.descriptor.sql.BasicBinder" additivity="false" level="fatal">
           <AppenderRef ref="RollingFile" />
       <Root level="info">
           <AppenderRef ref="RollingFile" />

Configure log4j for OpenOLAT 13.x.x and older

Create the file lib/log4j.xml containing

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="" debug="false" threshold="all">
<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d [%t] %-5p %c{1} %x - %m%n"/>
<appender name="DebugLog" class="org.apache.log4j.DailyRollingFileAppender">
   <param name="File" value="/home/openolat/logs/olat.debug.log"/>
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="%d [%t] %-5p %c{1} %x - %m%n"/>
 <appender name="syslog" class="org.apache.log4j.DailyRollingFileAppender">
   <param name="File" value="/home/openolat/logs/olat.log"/>
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="%d [%t] %-5p %c{1} %x - %m%n"/>
 <logger name="org.olat"> <level value="INFO"/> </logger>
 <logger name="org.olat.basesecurity.AuthHelper"> <level value="ERROR"/> </logger>
 <logger name="org.apache.commons.httpclient"> <level value="WARN"/> </logger>
 <logger name="org.olat.core.commons.taskExecutor.ThreadPoolTaskExecutor"> <level value="ERROR"/> </logger>
 <logger name="org.apache.pdfbox.filter.FlateFilter"> <level value="FATAL" /> </logger>
 <logger name="org.apache"> <level value="ERROR"/> </logger>
 <logger name="org.hibernate"> <level value="ERROR"/> </logger>
 <logger name="org.springframework"> <level value="ERROR"/> </logger>
 <logger name="org.hibernate.event.def.AbstractFlushingEventListener"> <level value="FATAL"/> </logger>
 <logger name="net.sf.hibernate"> <level value="WARN"/> </logger>
 <logger name="org.jboss.cache"> <level value="WARN" /> </logger>
 <logger name="org.hibernate.cache"> <level value="WARN" /> </logger>
 <logger name="org.hibernate.engine.internal.StatisticalLoggingSessionEventListener"><level value="FATAL"/></logger>
 <root> <level value="INFO" /> <appender-ref ref="syslog"/> </root>

Delete the log4j.xml file packaged with OpenOLAT. The file will not be present in newer version of OpenOLAT.

rm webapp/WEB-INF/classes/log4j.xml

Start OpenOLAT


The file log/catalina.out should say

INFO: Deploying configuration descriptor /home/openolat/conf/Catalina/localhost/ROOT.xml
near the end and the last line should be like
INFO: Server startup in 16310 ms 

Try OpenOLAT

point your browser to

username: administrator
password: openolat

Happy testing!